jms-spec
  1. jms-spec
  2. JMS_SPEC-70

Define annotations for injecting MessagingContext objects

    Details

    • Type: Improvement Improvement
    • Status: Resolved
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 1.1
    • Fix Version/s: 2.0PD, 2.0
    • Labels:
      None

      Description

      The simplified API (JMS_SPEC-64) defines a single object, javax.jms.MessagingContext, which provides methods for sending and receiving messages.

      It is proposed that the JMS API define some standard annotations that can be used to inject MessagingContext objects into application code.

      • The injection point should allow the application define the two parameters needed to create a MessagingContext: JNDI name (of the connection factory) and sessionMode. Both should be optional with suitable defaults.
      • The implementation should ideally be implemented using CDI and have behaviour consistent with it. However this is not essential.
      • It must be possible to use injection in Java EE applications. It is desirable but not essential to be able to use injection in Java SE applications.
      • Injected MessagingContexts must have an appropriate scope and must be automatically closed when they fall out of scope.

        Issue Links

          Activity

          Nigel Deakin created issue -
          Nigel Deakin made changes -
          Field Original Value New Value
          Affects Version/s 1.1 [ 14685 ]
          Nigel Deakin made changes -
          Link This issue depends on JMS_SPEC-64 [ JMS_SPEC-64 ]
          Nigel Deakin made changes -
          Link This issue blocks JMS_SPEC-33 [ JMS_SPEC-33 ]
          Nigel Deakin made changes -
          Tags eg prd-planned eg
          Nigel Deakin made changes -
          Tags eg eg pd20-planned
          Hide
          Nigel Deakin added a comment -

          Here is the proposed text to be added to the JMS spec:

          This section relates to application classes which run in the Java EE web, EJB or application client containers and which support injection. Section EE.5 of the Java EE specification lists the application classes that support injection.

          Applications may declare a field of type javax.jms.MessagingContext and annotate it with the javax.inject.Inject annotation:

          @Inject
          private MessagingContext context;
          

          The container will inject a MessagingContext. It will have request scope and will be automatically closed when the request ends. However, unlike a normal CDI request-scoped object, a separate MessagingContext instance will be injected for every injection point.

          The annotation javax.jms.JMSConnectionFactory may be used to specify the JNDI lookup name of the ConnectionFactory used to create the messaging context. For example:

          @Inject
          @JMSConnectionFactory("jms/connectionFactory")
          private MessagingContext context;
          

          If no lookup name is specified or the JMSConnectionFactory annotation is omitted then the platform default JMS connection factory will be used.

          The annotation javax.jms.JMSSessionMode may be used to specify the session mode of the messaging context:

          @Inject
          @JMSConnectionFactory("jms/connectionFactory")
          @JMSSessionMode(MessagingContext.AUTO_ACKNOWLEDGE)
          private MessagingContext context;
          

          The meaning and possible values of session mode are the same as for the ConnectionFactory method createMessagingContext(int sessionMode):

          • In the Java EE application client container, session mode may be set to any of MessagingContext.SESSION_TRANSACTED, MessagingContext.CLIENT_ACKNOWLEDGE, MessagingContext.AUTO_ACKNOWLEDGE or MessagingContext.DUPS_OK_ACKNOWLEDGE. If no session mode is specified or the JMSSessionMode annotation is omitted a session mode of MessagingContext.AUTO_ACKNOWLEDGE will be used.
          • In a Java EE web or EJB container, when there is an active JTA transaction in progress, session mode is ignored and the JMSSessionMode annotation is unnecessary.
          • In a Java EE web or EJB container, when there is no active JTA transaction in progress, session mode may be set to either of MessagingContext.AUTO_ACKNOWLEDGE or MessagingContext.DUPS_OK_ACKNOWLEDGE. If no session mode is specified or the JMSSessionMode annotation is omitted a session mode of MessagingContext.AUTO_ACKNOWLEDGE will be used.

          For more information about the use of session mode when creating a messaging context, see section 10.3 of the JMS 2.0 Early Draft, "Behaviour of JMS sessions in the Java EE web or EJB container" and the API documentation for the ConnectionFactory method createMessagingContext(int sessionMode).

          Show
          Nigel Deakin added a comment - Here is the proposed text to be added to the JMS spec: This section relates to application classes which run in the Java EE web, EJB or application client containers and which support injection. Section EE.5 of the Java EE specification lists the application classes that support injection. Applications may declare a field of type javax.jms.MessagingContext and annotate it with the javax.inject.Inject annotation: @Inject private MessagingContext context; The container will inject a MessagingContext . It will have request scope and will be automatically closed when the request ends. However, unlike a normal CDI request-scoped object, a separate MessagingContext instance will be injected for every injection point. The annotation javax.jms.JMSConnectionFactory may be used to specify the JNDI lookup name of the ConnectionFactory used to create the messaging context. For example: @Inject @JMSConnectionFactory("jms/connectionFactory") private MessagingContext context; If no lookup name is specified or the JMSConnectionFactory annotation is omitted then the platform default JMS connection factory will be used. The annotation javax.jms.JMSSessionMode may be used to specify the session mode of the messaging context: @Inject @JMSConnectionFactory("jms/connectionFactory") @JMSSessionMode(MessagingContext.AUTO_ACKNOWLEDGE) private MessagingContext context; The meaning and possible values of session mode are the same as for the ConnectionFactory method createMessagingContext(int sessionMode) : In the Java EE application client container, session mode may be set to any of MessagingContext.SESSION_TRANSACTED , MessagingContext.CLIENT_ACKNOWLEDGE , MessagingContext.AUTO_ACKNOWLEDGE or MessagingContext.DUPS_OK_ACKNOWLEDGE . If no session mode is specified or the JMSSessionMode annotation is omitted a session mode of MessagingContext.AUTO_ACKNOWLEDGE will be used. In a Java EE web or EJB container, when there is an active JTA transaction in progress, session mode is ignored and the JMSSessionMode annotation is unnecessary. In a Java EE web or EJB container, when there is no active JTA transaction in progress, session mode may be set to either of MessagingContext.AUTO_ACKNOWLEDGE or MessagingContext.DUPS_OK_ACKNOWLEDGE . If no session mode is specified or the JMSSessionMode annotation is omitted a session mode of MessagingContext.AUTO_ACKNOWLEDGE will be used. For more information about the use of session mode when creating a messaging context, see section 10.3 of the JMS 2.0 Early Draft, "Behaviour of JMS sessions in the Java EE web or EJB container" and the API documentation for the ConnectionFactory method createMessagingContext(int sessionMode).
          Hide
          Nigel Deakin added a comment -

          The proposed new annotations are as follows:

          New annotation javax.jms.JMSConnectionFactory:

          package javax.jms;
          
          import static java.lang.annotation.ElementType.FIELD;
          import static java.lang.annotation.ElementType.METHOD;
          import static java.lang.annotation.ElementType.PARAMETER;
          import static java.lang.annotation.ElementType.TYPE;
          import static java.lang.annotation.RetentionPolicy.RUNTIME;
          
          import java.lang.annotation.Retention;
          import java.lang.annotation.Target;
          
          /**
           * This optional annotation may be used to specify the JNDI lookup name of a <code>javax.jms.ConnectionFactory</code>
           * to be used when injecting a <code>javax.jms.MessagingContext</code> object.
           */
          @Retention(RUNTIME)
          @Target({METHOD, FIELD, PARAMETER, TYPE})
          public @interface JMSConnectionFactory {
              /**
               * (Optional) Specifies the JNDI lookup name of a <code>javax.jms.ConnectionFactory</code>
               * to be used when injecting a <code>javax.jms.MessagingContext</code> object.
               */
              String value() default "";
          }
          

          New annotation javax.jms.JMSSession:

          package javax.jms;
          
          import static java.lang.annotation.ElementType.FIELD;
          import static java.lang.annotation.ElementType.METHOD;
          import static java.lang.annotation.ElementType.PARAMETER;
          import static java.lang.annotation.ElementType.TYPE;
          import static java.lang.annotation.RetentionPolicy.RUNTIME;
          
          import java.lang.annotation.Retention;
          import java.lang.annotation.Target;
          
          /**
           * This optional annotation may be used to specify the session mode
           * to be used when injecting a <code>javax.jms.MessagingContext</code> object.
           * The meaning and possible values of session mode are the same as for the 
           * <code>ConnectionFactory</code> method <code>createMessagingContext(int sessionMode)</code>.
           * 
           * @see javax.jms.MessagingContext#createMessagingContext(int) 
           */
          @Retention(RUNTIME)
          @Target({METHOD, FIELD, PARAMETER, TYPE})
          public @interface JMSSessionMode {
              /**
               * (Optional) Specifies the session mode used when injecting a <code>javax.jms.MessagingContext</code> object.
               */
              int value() default MessagingContext.AUTO_ACKNOWLEDGE;
          }
          
          Show
          Nigel Deakin added a comment - The proposed new annotations are as follows: New annotation javax.jms.JMSConnectionFactory: package javax.jms; import static java.lang.annotation.ElementType.FIELD; import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.ElementType.PARAMETER; import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; import java.lang.annotation.Retention; import java.lang.annotation.Target; /** * This optional annotation may be used to specify the JNDI lookup name of a <code>javax.jms.ConnectionFactory</code> * to be used when injecting a <code>javax.jms.MessagingContext</code> object. */ @Retention(RUNTIME) @Target({METHOD, FIELD, PARAMETER, TYPE}) public @interface JMSConnectionFactory { /** * (Optional) Specifies the JNDI lookup name of a <code>javax.jms.ConnectionFactory</code> * to be used when injecting a <code>javax.jms.MessagingContext</code> object. */ String value() default ""; } New annotation javax.jms.JMSSession: package javax.jms; import static java.lang.annotation.ElementType.FIELD; import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.ElementType.PARAMETER; import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; import java.lang.annotation.Retention; import java.lang.annotation.Target; /** * This optional annotation may be used to specify the session mode * to be used when injecting a <code>javax.jms.MessagingContext</code> object. * The meaning and possible values of session mode are the same as for the * <code>ConnectionFactory</code> method <code>createMessagingContext(int sessionMode)</code>. * * @see javax.jms.MessagingContext#createMessagingContext(int) */ @Retention(RUNTIME) @Target({METHOD, FIELD, PARAMETER, TYPE}) public @interface JMSSessionMode { /** * (Optional) Specifies the session mode used when injecting a <code>javax.jms.MessagingContext</code> object. */ int value() default MessagingContext.AUTO_ACKNOWLEDGE; }
          Hide
          Nigel Deakin added a comment -

          I've now updated the API, javadocs and the draft spec in accordance with the proposals made above.

          The updated API and Javadocs are here:
          http://java.net/projects/jms-spec/sources/repository/content/jms2.0/target/jms-2.0-javadoc.jar

          The only changes are the two annotations javax.jms.JMSConnectionFactory and javax.jms.JMSSession.

          The updated draft spec is here:
          http://java.net/projects/jms-spec/sources/repository/content/jms2.0/specification/word/JMS20.pdf

          See particularly the new section 13.3 "Injection of MessagingContext objects" and a full set of examples in section 11.4 "Examples using the simplified API". The change log for the simplified API, section B.5.12 has also been updated.

          Show
          Nigel Deakin added a comment - I've now updated the API, javadocs and the draft spec in accordance with the proposals made above. The updated API and Javadocs are here: http://java.net/projects/jms-spec/sources/repository/content/jms2.0/target/jms-2.0-javadoc.jar The only changes are the two annotations javax.jms.JMSConnectionFactory and javax.jms.JMSSession. The updated draft spec is here: http://java.net/projects/jms-spec/sources/repository/content/jms2.0/specification/word/JMS20.pdf See particularly the new section 13.3 "Injection of MessagingContext objects" and a full set of examples in section 11.4 "Examples using the simplified API". The change log for the simplified API, section B.5.12 has also been updated.
          Nigel Deakin made changes -
          Tags eg pd20-planned eg
          Nigel Deakin made changes -
          Tags eg ed20-added eg
          Hide
          Nigel Deakin added a comment -

          I've updated the API, javadocs and the draft spec in accordance with the following changes.

          The updated API and Javadocs are here:
          http://java.net/projects/jms-spec/sources/repository/content/jms2.0/target/jms-2.0-javadoc.jar

          The updated draft spec is here:
          http://java.net/projects/jms-spec/sources/repository/content/jms2.0/specification/word/JMS20.pdf

          A new annotation has been added to allow the application to specify the user and password to be used when injecting a MessagingContext:

          @Inject
          @JMSConnectionFactory("jms/connectionFactory")
          @JMSPasswordCredential(userName="admin",password="mypassword")
          private MessagingContext context;
          

          A new annotation has been added to allow the application to configure whether the connection is automatically started when a consumer is created:

          @Inject
          @JMSConnectionFactory("jms/connectionFactory")
          @JMSSessionMode(MessagingContext.AUTO_ACKNOWLEDGE)
          @JMSAutoStart(false)
          private MessagingContext context;
          
          Show
          Nigel Deakin added a comment - I've updated the API, javadocs and the draft spec in accordance with the following changes. The updated API and Javadocs are here: http://java.net/projects/jms-spec/sources/repository/content/jms2.0/target/jms-2.0-javadoc.jar The updated draft spec is here: http://java.net/projects/jms-spec/sources/repository/content/jms2.0/specification/word/JMS20.pdf A new annotation has been added to allow the application to specify the user and password to be used when injecting a MessagingContext : @Inject @JMSConnectionFactory("jms/connectionFactory") @JMSPasswordCredential(userName="admin",password="mypassword") private MessagingContext context; A new annotation has been added to allow the application to configure whether the connection is automatically started when a consumer is created: @Inject @JMSConnectionFactory("jms/connectionFactory") @JMSSessionMode(MessagingContext.AUTO_ACKNOWLEDGE) @JMSAutoStart(false) private MessagingContext context;
          Nigel Deakin made changes -
          Tags ed20-added eg ed20-added
          Nigel Deakin made changes -
          Tags ed20-added ed20-added ed20-added-incomplete
          Nigel Deakin made changes -
          Tags ed20-added ed20-added-incomplete ed20-added-incomplete
          Nigel Deakin made changes -
          Link This issue blocks MQ-177 [ MQ-177 ]
          Nigel Deakin made changes -
          Tags ed20-added-incomplete
          Nigel Deakin made changes -
          Tags pd20-added
          Hide
          Nigel Deakin added a comment -

          This feature has been further revised: an up-to-date description may be found in section 11.3 "Injection of JMSContext objects" in the JMS 2.0 public draft.

          11.3. Injection of JMSContext objects

          Show
          Nigel Deakin added a comment - This feature has been further revised: an up-to-date description may be found in section 11.3 "Injection of JMSContext objects" in the JMS 2.0 public draft. 11.3. Injection of JMSContext objects
          Nigel Deakin made changes -
          Assignee Nigel Deakin [ nigeldeakin ]
          Hide
          Nigel Deakin added a comment -

          This issue is now closed as a full definition of how JMSContext objects may be injected will be included in the JMS 2.0 public draft.

          Show
          Nigel Deakin added a comment - This issue is now closed as a full definition of how JMSContext objects may be injected will be included in the JMS 2.0 public draft.
          Nigel Deakin made changes -
          Status Open [ 1 ] Closed [ 6 ]
          Fix Version/s 2.0PD [ 16049 ]
          Resolution Fixed [ 1 ]
          Nigel Deakin made changes -
          Resolution Fixed [ 1 ]
          Status Closed [ 6 ] Reopened [ 4 ]
          Nigel Deakin made changes -
          Status Reopened [ 4 ] Resolved [ 5 ]
          Fix Version/s 2.0 [ 14692 ]
          Resolution Fixed [ 1 ]

            People

            • Assignee:
              Nigel Deakin
              Reporter:
              Nigel Deakin
            • Votes:
              1 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: