jms-spec
  1. jms-spec
  2. JMS_SPEC-133

Update javadoc comments for QueueConnection#createQueueSession and TopicConnection#createTopicSession

    Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 2.0
    • Fix Version/s: JMS 2.0 rev A
    • Labels:
      None

      Description

      The javadoc comments for QueueConnection#createQueueSession and TopicConnection#createTopicSession should be updated to match those for Connection#createSession (mutatis mutandis), by describing the required behaviour in the various Java EE containers etc.

        Activity

        Hide
        Nigel Deakin added a comment -

        Fixed in the JMS 2.0 rev A maintenance release

        Show
        Nigel Deakin added a comment - Fixed in the JMS 2.0 rev A maintenance release
        Show
        Nigel Deakin added a comment - Updated source for javax.jms.QueueConnection can be viewed at, and downloaded from, https://java.net/projects/jms-spec/sources/repository/content/jms2.0a/src/main/java/javax/jms/QueueConnection.java?rev=316 Diffs can be viewed at https://java.net/projects/jms-spec/sources/repository/diff/jms2.0a/src/main/java/javax/jms/QueueConnection.java?rev1=315&rev2=316 Updated source for javax.jms.TopicConnection can be viewed at, and downloaded from, https://java.net/projects/jms-spec/sources/repository/content/jms2.0a/src/main/java/javax/jms/TopicConnection.java?rev=316 Diffs can be viewed at https://java.net/projects/jms-spec/sources/repository/diff/jms2.0a/src/main/java/javax/jms/TopicConnection.java?rev1=315&rev2=316
        Hide
        Nigel Deakin added a comment - - edited

        Here are the proposed changes.

        javadoc for QueueConnection#createQueueSession

        It is proposed the existing javadoc for this method is replaced by a copy of the javadoc for Connection#createSession (after applying the changes for JMS_SPEC-155 and JMS_SPEC-157), with the following modifications

        • The first paragraph "This method has been superseded by...instead of this one" is omitted.
        • "Creates a Session object" is changed to "Creates a QueueSession object"
        • "Returns: a newly created queue session" is changed to "Returns: a newly created QueueSession"
        • "if the Connection object fails to create a session" is changed to "if the QueueConnection object fails to create a QueueSession"
        • In the section "See Also:", the references to createSession(int), createSession() are omitted.

        Existing text:

        Creates a QueueSession object.

        Parameters:

        transacted - indicates whether the session is transacted

        acknowledgeMode - indicates whether the consumer or the client will acknowledge any messages it receives; ignored if the session is transacted. Legal values are Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, and Session.DUPS_OK_ACKNOWLEDGE.

        Returns:

        a newly created queue session

        Throws:

        JMSException - if the QueueConnection object fails to create a session due to some internal error or lack of support for the specific transaction and acknowledgement mode.

        See Also:

        Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, Session.DUPS_OK_ACKNOWLEDGE

        Replacement text:

        Creates a QueueSession object, specifying transacted and acknowledgeMode.

        The effect of setting the transacted and acknowledgeMode arguments depends on whether this method is called in a Java SE environment, in the Java EE application client container, or in the Java EE web or EJB container. If this method is called in the Java EE web or EJB container then the effect of setting the transacted} and acknowledgeMode arguments also depends on whether or not there is an active JTA transaction in progress.

        In a Java SE environment or in the Java EE application client container:

        • If transacted is set to true then the session will use a local transaction which may subsequently be committed or rolled back by calling the session's commit or rollback methods. The argument acknowledgeMode is ignored.
        • If transacted is set to false then the session will be non-transacted. In this case the argument acknowledgeMode is used to specify how messages received by this session will be acknowledged. The permitted values are Session.CLIENT_ACKNOWLEDGE, Session.AUTO_ACKNOWLEDGE and Session.DUPS_OK_ACKNOWLEDGE. For a definition of the meaning of these acknowledgement modes see the links below.

        In a Java EE web or EJB container, when there is an active JTA transaction in progress:

        • Both arguments transacted and acknowledgeMode are ignored. The session will participate in the JTA transaction and will be committed or rolled back when that transaction is committed or rolled back, not by calling the session's commit or rollback methods. Since both arguments are ignored, developers are recommended to use createSession(), which has no arguments, instead of this method.

        In the Java EE web or EJB container, when there is no active JTA transaction in progress:

        • If transacted is set to false and acknowledgeMode is set to JMSContext.AUTO_ACKNOWLEDGE or Session.DUPS_OK_ACKNOWLEDGE then the session will be non-transacted and messages will be acknowledged according to the value of acknowledgeMode.
        • If transacted is set to false and acknowledgeMode is set to JMSContext.CLIENT_ACKNOWLEDGE then the JMS provider is recommended to ignore the specified parameters and instead provide a non-transacted, auto-acknowledged session. However the JMS provider may alternatively provide a non-transacted session with client acknowledgement.
        • If transacted is set to true, then the JMS provider is recommended to ignore the specified parameters and instead provide a non-transacted, auto-acknowledged session. However the JMS provider may alternatively provide a local transacted session.
        • Applications are recommended to set transacted to false and acknowledgeMode to JMSContext.AUTO_ACKNOWLEDGE or Session.DUPS_OK_ACKNOWLEDGE since since applications which set transacted to false and set acknowledgeMode to JMSContext.CLIENT_ACKNOWLEDGE, or which set transacted to true, may not be portable.

        Applications running in the Java EE web and EJB containers must not attempt to create more than one active (not closed) Session object per connection. If this method is called in a Java EE web or EJB container when an active Session object already exists for this connection then a JMSException may be thrown.

        Parameters:

        transacted - indicates whether the session will use a local transaction, except in the cases described above when this value is ignored.

        acknowledgeMode - when transacted is false, indicates how messages received by the session will be acknowledged, except in the cases described above when this value is ignored.

        Returns:

        a newly created QueueSession

        Throws:

        JMSException - if the QueueConnection object fails to create a QueueSession due to some internal error, lack of support for the specific transaction and acknowledgement mode, or because this method is being called in a Java EE web or EJB application and an active session already exists for this connection.

        Since:

        JMS 1.1

        See Also:

        Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, Session.DUPS_OK_ACKNOWLEDGE

        javadoc for TopicConnection#createTopicSession

        It is proposed the existing javadoc for this method is replaced by a copy of the javadoc for Connection#createSession (after applying the changes for JMS_SPEC-155 and JMS_SPEC-157), with the following modifications

        • The first paragraph "This method has been superseded by...instead of this one" is omitted.
        • "Creates a Session object" is changed to "Creates a TopicSession object"
        • "Returns: a newly created topic session" is changed to "Returns: a newly created TopicSession "
        • "if the Connection object fails to create a session" is changed to "if the TopicConnection object fails to create a TopicSession"
        • In the section "See Also:", the references to createSession(int), createSession() are omitted.

        Existing text:

        Creates a TopicSession object.

        Parameters:

        transacted - indicates whether the session is transacted

        acknowledgeMode - indicates whether the consumer or the client will acknowledge any messages it receives; ignored if the session is transacted. Legal values are Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, and Session.DUPS_OK_ACKNOWLEDGE.

        Returns:

        a newly created topic session

        Throws:

        JMSException - if the TopicConnection object fails to create a session due to some internal error or lack of support for the specific transaction and acknowledgement mode.

        See Also:

        Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, Session.DUPS_OK_ACKNOWLEDGE

        Replacement text:

        Creates a TopicSession object, specifying transacted and acknowledgeMode.

        The effect of setting the transacted and acknowledgeMode arguments depends on whether this method is called in a Java SE environment, in the Java EE application client container, or in the Java EE web or EJB container. If this method is called in the Java EE web or EJB container then the effect of setting the transacted} and acknowledgeMode arguments also depends on whether or not there is an active JTA transaction in progress.

        In a Java SE environment or in the Java EE application client container:

        • If transacted is set to true then the session will use a local transaction which may subsequently be committed or rolled back by calling the session's commit or rollback methods. The argument acknowledgeMode is ignored.
        • If transacted is set to false then the session will be non-transacted. In this case the argument acknowledgeMode is used to specify how messages received by this session will be acknowledged. The permitted values are Session.CLIENT_ACKNOWLEDGE, Session.AUTO_ACKNOWLEDGE and Session.DUPS_OK_ACKNOWLEDGE. For a definition of the meaning of these acknowledgement modes see the links below.

        In a Java EE web or EJB container, when there is an active JTA transaction in progress:

        • Both arguments transacted and acknowledgeMode are ignored. The session will participate in the JTA transaction and will be committed or rolled back when that transaction is committed or rolled back, not by calling the session's commit or rollback methods. Since both arguments are ignored, developers are recommended to use createSession(), which has no arguments, instead of this method.

        In the Java EE web or EJB container, when there is no active JTA transaction in progress:

        • If transacted is set to false and acknowledgeMode is set to JMSContext.AUTO_ACKNOWLEDGE or Session.DUPS_OK_ACKNOWLEDGE then the session will be non-transacted and messages will be acknowledged according to the value of acknowledgeMode.
        • If transacted is set to false and acknowledgeMode is set to JMSContext.CLIENT_ACKNOWLEDGE then the JMS provider is recommended to ignore the specified parameters and instead provide a non-transacted, auto-acknowledged session. However the JMS provider may alternatively provide a non-transacted session with client acknowledgement.
        • If transacted is set to true, then the JMS provider is recommended to ignore the specified parameters and instead provide a non-transacted, auto-acknowledged session. However the JMS provider may alternatively provide a local transacted session.
        • Applications are recommended to set transacted to false and acknowledgeMode to JMSContext.AUTO_ACKNOWLEDGE or Session.DUPS_OK_ACKNOWLEDGE since since applications which set transacted to false and set acknowledgeMode to JMSContext.CLIENT_ACKNOWLEDGE, or which set transacted to true, may not be portable.

        Applications running in the Java EE web and EJB containers must not attempt to create more than one active (not closed) Session object per connection. If this method is called in a Java EE web or EJB container when an active Session object already exists for this connection then a JMSException may be thrown.

        Parameters:

        transacted - indicates whether the session will use a local transaction, except in the cases described above when this value is ignored.

        acknowledgeMode - when transacted is false, indicates how messages received by the session will be acknowledged, except in the cases described above when this value is ignored.

        Returns:

        a newly created TopicSession

        Throws:

        JMSException - if the TopicConnection object fails to create a TopicSession due to some internal error, lack of support for the specific transaction and acknowledgement mode, or because this method is being called in a Java EE web or EJB application and an active session already exists for this connection.

        Since:

        JMS 1.1

        See Also:

        Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, Session.DUPS_OK_ACKNOWLEDGE

        Show
        Nigel Deakin added a comment - - edited Here are the proposed changes. javadoc for QueueConnection#createQueueSession It is proposed the existing javadoc for this method is replaced by a copy of the javadoc for Connection#createSession (after applying the changes for JMS_SPEC-155 and JMS_SPEC-157 ), with the following modifications The first paragraph "This method has been superseded by...instead of this one" is omitted. "Creates a Session object" is changed to "Creates a QueueSession object" "Returns: a newly created queue session" is changed to "Returns: a newly created QueueSession" "if the Connection object fails to create a session" is changed to "if the QueueConnection object fails to create a QueueSession" In the section "See Also:", the references to createSession(int), createSession() are omitted. Existing text: Creates a QueueSession object. Parameters: transacted - indicates whether the session is transacted acknowledgeMode - indicates whether the consumer or the client will acknowledge any messages it receives; ignored if the session is transacted. Legal values are Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, and Session.DUPS_OK_ACKNOWLEDGE. Returns: a newly created queue session Throws: JMSException - if the QueueConnection object fails to create a session due to some internal error or lack of support for the specific transaction and acknowledgement mode. See Also: Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, Session.DUPS_OK_ACKNOWLEDGE Replacement text: Creates a QueueSession object, specifying transacted and acknowledgeMode. The effect of setting the transacted and acknowledgeMode arguments depends on whether this method is called in a Java SE environment, in the Java EE application client container, or in the Java EE web or EJB container. If this method is called in the Java EE web or EJB container then the effect of setting the transacted} and acknowledgeMode arguments also depends on whether or not there is an active JTA transaction in progress. In a Java SE environment or in the Java EE application client container: If transacted is set to true then the session will use a local transaction which may subsequently be committed or rolled back by calling the session's commit or rollback methods. The argument acknowledgeMode is ignored. If transacted is set to false then the session will be non-transacted. In this case the argument acknowledgeMode is used to specify how messages received by this session will be acknowledged. The permitted values are Session.CLIENT_ACKNOWLEDGE, Session.AUTO_ACKNOWLEDGE and Session.DUPS_OK_ACKNOWLEDGE. For a definition of the meaning of these acknowledgement modes see the links below. In a Java EE web or EJB container, when there is an active JTA transaction in progress: Both arguments transacted and acknowledgeMode are ignored. The session will participate in the JTA transaction and will be committed or rolled back when that transaction is committed or rolled back, not by calling the session's commit or rollback methods. Since both arguments are ignored, developers are recommended to use createSession(), which has no arguments, instead of this method. In the Java EE web or EJB container, when there is no active JTA transaction in progress: If transacted is set to false and acknowledgeMode is set to JMSContext.AUTO_ACKNOWLEDGE or Session.DUPS_OK_ACKNOWLEDGE then the session will be non-transacted and messages will be acknowledged according to the value of acknowledgeMode. If transacted is set to false and acknowledgeMode is set to JMSContext.CLIENT_ACKNOWLEDGE then the JMS provider is recommended to ignore the specified parameters and instead provide a non-transacted, auto-acknowledged session. However the JMS provider may alternatively provide a non-transacted session with client acknowledgement. If transacted is set to true, then the JMS provider is recommended to ignore the specified parameters and instead provide a non-transacted, auto-acknowledged session. However the JMS provider may alternatively provide a local transacted session. Applications are recommended to set transacted to false and acknowledgeMode to JMSContext.AUTO_ACKNOWLEDGE or Session.DUPS_OK_ACKNOWLEDGE since since applications which set transacted to false and set acknowledgeMode to JMSContext.CLIENT_ACKNOWLEDGE, or which set transacted to true, may not be portable. Applications running in the Java EE web and EJB containers must not attempt to create more than one active (not closed) Session object per connection. If this method is called in a Java EE web or EJB container when an active Session object already exists for this connection then a JMSException may be thrown. Parameters: transacted - indicates whether the session will use a local transaction, except in the cases described above when this value is ignored. acknowledgeMode - when transacted is false, indicates how messages received by the session will be acknowledged, except in the cases described above when this value is ignored. Returns: a newly created QueueSession Throws: JMSException - if the QueueConnection object fails to create a QueueSession due to some internal error, lack of support for the specific transaction and acknowledgement mode, or because this method is being called in a Java EE web or EJB application and an active session already exists for this connection. Since: JMS 1.1 See Also: Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, Session.DUPS_OK_ACKNOWLEDGE javadoc for TopicConnection#createTopicSession It is proposed the existing javadoc for this method is replaced by a copy of the javadoc for Connection#createSession (after applying the changes for JMS_SPEC-155 and JMS_SPEC-157 ), with the following modifications The first paragraph "This method has been superseded by...instead of this one" is omitted. "Creates a Session object" is changed to "Creates a TopicSession object" "Returns: a newly created topic session" is changed to "Returns: a newly created TopicSession " "if the Connection object fails to create a session" is changed to "if the TopicConnection object fails to create a TopicSession" In the section "See Also:", the references to createSession(int), createSession() are omitted. Existing text: Creates a TopicSession object. Parameters: transacted - indicates whether the session is transacted acknowledgeMode - indicates whether the consumer or the client will acknowledge any messages it receives; ignored if the session is transacted. Legal values are Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, and Session.DUPS_OK_ACKNOWLEDGE. Returns: a newly created topic session Throws: JMSException - if the TopicConnection object fails to create a session due to some internal error or lack of support for the specific transaction and acknowledgement mode. See Also: Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, Session.DUPS_OK_ACKNOWLEDGE Replacement text: Creates a TopicSession object, specifying transacted and acknowledgeMode. The effect of setting the transacted and acknowledgeMode arguments depends on whether this method is called in a Java SE environment, in the Java EE application client container, or in the Java EE web or EJB container. If this method is called in the Java EE web or EJB container then the effect of setting the transacted} and acknowledgeMode arguments also depends on whether or not there is an active JTA transaction in progress. In a Java SE environment or in the Java EE application client container: If transacted is set to true then the session will use a local transaction which may subsequently be committed or rolled back by calling the session's commit or rollback methods. The argument acknowledgeMode is ignored. If transacted is set to false then the session will be non-transacted. In this case the argument acknowledgeMode is used to specify how messages received by this session will be acknowledged. The permitted values are Session.CLIENT_ACKNOWLEDGE, Session.AUTO_ACKNOWLEDGE and Session.DUPS_OK_ACKNOWLEDGE. For a definition of the meaning of these acknowledgement modes see the links below. In a Java EE web or EJB container, when there is an active JTA transaction in progress: Both arguments transacted and acknowledgeMode are ignored. The session will participate in the JTA transaction and will be committed or rolled back when that transaction is committed or rolled back, not by calling the session's commit or rollback methods. Since both arguments are ignored, developers are recommended to use createSession(), which has no arguments, instead of this method. In the Java EE web or EJB container, when there is no active JTA transaction in progress: If transacted is set to false and acknowledgeMode is set to JMSContext.AUTO_ACKNOWLEDGE or Session.DUPS_OK_ACKNOWLEDGE then the session will be non-transacted and messages will be acknowledged according to the value of acknowledgeMode. If transacted is set to false and acknowledgeMode is set to JMSContext.CLIENT_ACKNOWLEDGE then the JMS provider is recommended to ignore the specified parameters and instead provide a non-transacted, auto-acknowledged session. However the JMS provider may alternatively provide a non-transacted session with client acknowledgement. If transacted is set to true, then the JMS provider is recommended to ignore the specified parameters and instead provide a non-transacted, auto-acknowledged session. However the JMS provider may alternatively provide a local transacted session. Applications are recommended to set transacted to false and acknowledgeMode to JMSContext.AUTO_ACKNOWLEDGE or Session.DUPS_OK_ACKNOWLEDGE since since applications which set transacted to false and set acknowledgeMode to JMSContext.CLIENT_ACKNOWLEDGE, or which set transacted to true, may not be portable. Applications running in the Java EE web and EJB containers must not attempt to create more than one active (not closed) Session object per connection. If this method is called in a Java EE web or EJB container when an active Session object already exists for this connection then a JMSException may be thrown. Parameters: transacted - indicates whether the session will use a local transaction, except in the cases described above when this value is ignored. acknowledgeMode - when transacted is false, indicates how messages received by the session will be acknowledged, except in the cases described above when this value is ignored. Returns: a newly created TopicSession Throws: JMSException - if the TopicConnection object fails to create a TopicSession due to some internal error, lack of support for the specific transaction and acknowledgement mode, or because this method is being called in a Java EE web or EJB application and an active session already exists for this connection. Since: JMS 1.1 See Also: Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, Session.DUPS_OK_ACKNOWLEDGE

          People

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

            Dates

            • Created:
              Updated:
              Resolved: