Clarify scope of ClientID between JavaDoc and specification

[glassfishrobot]

The JavaDoc for the javax.jms.Connection setClientID method includes the following line

"If another connection with the same clientID is already running when this method is called, the JMS provider should detect the duplicate ID and throw an InvalidClientIDException."

The JMS2.0 TCK does include a test that checks that if a second connection is created from a CF with a client ID set, then the second create connection fails. I do not believe that this tested existing within the 1.1 TCK.

This line and test means that the scope of a ClientID is per active Connection (or context).

The text (PDF) specification does not explicitly state this - it says..

"The purpose of client identifier is to associate a connection and its objects with a state maintained on behalf of the client by a provider. By definition, the client state identified by a client identifier can be 'in use' by only one client at a time. A JMS provider must prevent concurrently executing clients from using it."

It says "concurrently executing clients" not "concurrently executing connections". This also implies that the definition of the word 'client' is a single active connection. Again this is not stated explicitly.

It does mean that pooling implementations have to be careful. They can not keep pools of active connections all from the same client ID. The connections in the pools must be stopped first.

Affected Versions

[2.0]

[glassfishrobot]

• Issue Imported From: https://github.com/javaee/jms-spec/issues/139
• Original Issue Raised By:@glassfishrobot
• Original Issue Assigned To: Unassigned

[glassfishrobot]

@glassfishrobot Commented Reported by mbwhite

[glassfishrobot]

@glassfishrobot Commented mbwhite said: Forget to add - that this would also imply, I think, that a ConnectionFactory with a clientID set in it (the preferred) way can only have 1 active connection at time created from it. A set of programs running in 2 JVMs therefore could not share a common ConnectionFactory stored in JNDI.

[glassfishrobot]

@glassfishrobot Commented genomeprjct said:

a ConnectionFactory with a clientID set in it (the preferred) way can only have 1 active connection at time created from it

Can you clarify what you mean here? There is no way to set the clientId on a connection factory: https://jms-spec.java.net/2.0/apidocs/javax/jms/ConnectionFactory.html

Maybe for this issue in general we can discuss further on the users@ or eg groups? Maybe there's just a misunderstanding here.

[glassfishrobot]

@glassfishrobot Commented @nigeldeakin said: Thanks for reporting the issue. I've added it to the list of issues to be considered for 2.1.

JMS 2.0 has not changed the clientID uniqueness requirements from JMS 1.1. All it did was to define a new method on JMSContext to set the clientID of the underlying connection.

If the JMS 2.0 TCK has added a new test, and that test is causing difficulty for vendors, then TCK licensees can address that through the TCK challenge procedure.

I think the intention of the JMS 1.1 spec was that no two JMS connections should have the same clientID. The use of the word "client" here is vague and it would be clearer if this were changed to refer to connections.

The use of the word "should" rather than the word "must" suggests that the clientID uniqueness requirement is a recommendation rather than an absolute requirement. It would be clearer if the spec as a whole clarified the meaning of the word "should". There's a document, RFC 2119, which the spec could refer to http://www.ietf.org/rfc/rfc2119.txt

The other comments you make are perfectly correct.

The clientID uniqueness requirement means that you can't have a pool of connections all of which have the same clientID.

And the statement in JMS 1.1 and 2.0 that "the preferred way to assign a client’s client identifier is for it to be configured in a client-specific ConnectionFactory and transparently assigned to the connection it creates" means that such a connection factory can only be used to create only one connection at a time.

I think the best solution to all these issues with clientID is to remove the need to set clientID at all, especially when working in a Java EE environment, and there have been various changes in JMS 2.0 to partially achieve that.

[glassfishrobot]

@glassfishrobot Commented mbwhite said: From the 6.2.1 section of the PDF... 'ClientId'

"The preferred way to assign a client’s client identifier is for it to be configured in a client-specific ConnectionFactory and transparently assigned to the connection it creates" So the spec prefers a ClientID to already be in place when a connection is created - and from a JavaEE perspective applications can't set it. (section 12.2).

It's true that clientID is really only used for non-shared durable subscriptions. And only one of those could be active at once anyway - but there's a logical consequence here that the TCK brought to my attention that I'm not sure is what is intended.

Yes - can send out an email to the list - good point.

[glassfishrobot]

@glassfishrobot Commented mbwhite said: Thanks Nigel; I agree that the scope hasn't changed between 1.1 & 2 - nor is the TCK specifically at fault. Rather it has improved and is now checking something that as you state was always the intent but was perhaps not quite as clear. Hence it triggered the discussion and the logical conclusion that you've confirmed.

Would you agree it would be valid to have a pool of 'stopped' connections? i.e. only 1 active/started. Though that might be a little academic anyway!

[glassfishrobot]

@glassfishrobot Commented @nigeldeakin said: It doesn't matter whether the connection is stopped or not. The spec is clear that calling stop() simply suspends the delivery of incoming messages. It doesn't have any effect on clientID. Only calling close() will release a client identifier from being in use.

Note that JMS doesn't define the internal implementation of your connection pool. It only defines the behaviour seen by the application. It doesn't matter what the connection pool does internally.

[glassfishrobot]

@glassfishrobot Commented mbwhite said: ok; my comment was because the JavaDoc uses the work 'running' rather than 'created'. Running implies started and delivering messages.

Agree that JMS doesn't defined internal implementation of connection pool - my point is that with this definition of clientID there is no possibility of pooling these connections at all. Only one connection object can be created at any point in time.

[glassfishrobot]

@glassfishrobot Commented This issue was imported from java.net JIRA JMS_SPEC-139