session.java

JAVA 消息服务(JMS)定义了Java 中访问消息中间件的接口,里边有实现消息服务的基础源码,可以开发高级应用

      * @exception JMSException if the JMS provider fails to return the 
      *                         transaction mode due to some internal error.
      */ 

    boolean
    getTransacted() throws JMSException;
    
    /** Returns the acknowledgement mode of the session. The acknowledgement
     * mode is set at the time that the session is created. If the session is
     * transacted, the acknowledgement mode is ignored.
     *
     *@return            If the session is not transacted, returns the 
     *                  current acknowledgement mode for the session.
     *                  If the session
     *                  is transacted, returns SESSION_TRANSACTED.
     *
     *@exception JMSException   if the JMS provider fails to return the 
     *                         acknowledgment mode due to some internal error.
     *
     *@see Connection#createSession
     *@since 1.1
     */
    int 
    getAcknowledgeMode() throws JMSException;


    /** Commits all messages done in this transaction and releases any locks
      * currently held.
      *
      * @exception JMSException if the JMS provider fails to commit the
      *                         transaction due to some internal error.
      * @exception TransactionRolledBackException if the transaction
      *                         is rolled back due to some internal error
      *                         during commit.
      * @exception IllegalStateException if the method is not called by a 
      *                         transacted session.
      */

    void
    commit() throws JMSException;


    /** Rolls back any messages done in this transaction and releases any locks 
      * currently held.
      *
      * @exception JMSException if the JMS provider fails to roll back the
      *                         transaction due to some internal error.
      * @exception IllegalStateException if the method is not called by a 
      *                         transacted session.
      *                                     
      */

    void
    rollback() throws JMSException;


    /** Closes the session.
      *
      * <P>Since a provider may allocate some resources on behalf of a session 
      * outside the JVM, clients should close the resources when they are not 
      * needed. 
      * Relying on garbage collection to eventually reclaim these resources 
      * may not be timely enough.
      *
      * <P>There is no need to close the producers and consumers
      * of a closed session. 
      *
      * <P> This call will block until a <CODE>receive</CODE> call or message 
      * listener in progress has completed. A blocked message consumer
      * <CODE>receive</CODE> call returns <CODE>null</CODE> when this session 
      * is closed.
      *
      * <P>Closing a transacted session must roll back the transaction
      * in progress.
      * 
      * <P>This method is the only <CODE>Session</CODE> method that can 
      * be called concurrently. 
      *
      * <P>Invoking any other <CODE>Session</CODE> method on a closed session 
      * must throw a <CODE>JMSException.IllegalStateException</CODE>. Closing a 
      * closed session must <I>not</I> throw an exception.
      * 
      * @exception JMSException if the JMS provider fails to close the
      *                         session due to some internal error.
      */

    void
    close() throws JMSException;


    /** Stops message delivery in this session, and restarts message delivery
      * with the oldest unacknowledged message.
      *  
      * <P>All consumers deliver messages in a serial order.
      * Acknowledging a received message automatically acknowledges all 
      * messages that have been delivered to the client.
      *
      * <P>Restarting a session causes it to take the following actions:
      *
      * <UL>
      *   <LI>Stop message delivery
      *   <LI>Mark all messages that might have been delivered but not 
      *       acknowledged as "redelivered"
      *   <LI>Restart the delivery sequence including all unacknowledged 
      *       messages that had been previously delivered. Redelivered messages
      *       do not have to be delivered in 
      *       exactly their original delivery order.
      * </UL>
      *
      * @exception JMSException if the JMS provider fails to stop and restart
      *                         message delivery due to some internal error.
      * @exception IllegalStateException if the method is called by a 
      *                         transacted session.
      */ 

    void
    recover() throws JMSException;


    /** Returns the session's distinguished message listener (optional).
      *
      * @return the message listener associated with this session
      *
      * @exception JMSException if the JMS provider fails to get the message 
      *                         listener due to an internal error.
      *
      * @see javax.jms.Session#setMessageListener
      * @see javax.jms.ServerSessionPool
      * @see javax.jms.ServerSession
      */

    MessageListener
    getMessageListener() throws JMSException;


    /** Sets the session's distinguished message listener (optional).
      *
      * <P>When the distinguished message listener is set, no other form of 
      * message receipt in the session can 
      * be used; however, all forms of sending messages are still supported.
      * 
      * <P>This is an expert facility not used by regular JMS clients.
      *
      * @param listener the message listener to associate with this session
      *
      * @exception JMSException if the JMS provider fails to set the message 
      *                         listener due to an internal error.
      *
      * @see javax.jms.Session#getMessageListener
      * @see javax.jms.ServerSessionPool
      * @see javax.jms.ServerSession
      */

    void
    setMessageListener(MessageListener listener) throws JMSException;

    /**
     * Optional operation, intended to be used only by Application Servers,
     * not by ordinary JMS clients.
     *
     * @see javax.jms.ServerSession
     */
    public void run();
    
    /** Creates a <CODE>MessageProducer</CODE> to send messages to the specified 
      * destination.
      *
      * <P>A client uses a <CODE>MessageProducer</CODE> object to send 
      * messages to a destination. Since <CODE>Queue</CODE> and <CODE>Topic</CODE> 
      * both inherit from <CODE>Destination</CODE>, they can be used in
      * the destination parameter to create a <CODE>MessageProducer</CODE> object.
      * 
      * @param destination the <CODE>Destination</CODE> to send to, 
      * or null if this is a producer which does not have a specified 
      * destination.
      *
      * @exception JMSException if the session fails to create a MessageProducer
      *                         due to some internal error.
      * @exception InvalidDestinationException if an invalid destination
      * is specified.
      *
      * @since 1.1 
      * 
     */

    MessageProducer
    createProducer(Destination destination) throws JMSException;
    
    
       /** Creates a <CODE>MessageConsumer</CODE> for the specified destination.
      * Since <CODE>Queue</CODE> and <CODE>Topic</CODE> 
      * both inherit from <CODE>Destination</CODE>, they can be used in
      * the destination parameter to create a <CODE>MessageConsumer</CODE>.
      *
      * @param destination the <CODE>Destination</CODE> to access. 
      *
      * @exception JMSException if the session fails to create a consumer
      *                         due to some internal error.
      * @exception InvalidDestinationException if an invalid destination 
      *                         is specified.
      *
      * @since 1.1 
      */

    MessageConsumer
    createConsumer(Destination destination) throws JMSException;

       /** Creates a <CODE>MessageConsumer</CODE> for the specified destination, 
      * using a message selector. 
      * Since <CODE>Queue</CODE> and <CODE>Topic</CODE> 
      * both inherit from <CODE>Destination</CODE>, they can be used in
      * the destination parameter to create a <CODE>MessageConsumer</CODE>.
      *
      * <P>A client uses a <CODE>MessageConsumer</CODE> object to receive 
      * messages that have been sent to a destination.
      *  
      *       
      * @param destination the <CODE>Destination</CODE> to access
      * @param messageSelector only messages with properties matching the
      * message selector expression are delivered. A value of null or
      * an empty string indicates that there is no message selector 
      * for the message consumer. 
      * 
      *  
      * @exception JMSException if the session fails to create a MessageConsumer
      *                         due to some internal error.
      * @exception InvalidDestinationException if an invalid destination
       * is specified.
     
      * @exception InvalidSelectorException if the message selector is invalid.
      *
      * @since 1.1 
      */
    MessageConsumer     
    createConsumer(Destination destination, java.lang.String messageSelector) 
    throws JMSException;
    
    
     /** Creates <CODE>MessageConsumer</CODE> for the specified destination, using a
      * message selector. This method can specify whether messages published by 
      * its own connection should be delivered to it, if the destination is a 
      * topic. 
      *<P> Since <CODE>Queue</CODE> and <CODE>Topic</CODE> 
      * both inherit from <CODE>Destination</CODE>, they can be used in
      * the destination parameter to create a <CODE>MessageConsumer</CODE>.
      * <P>A client uses a <CODE>MessageConsumer</CODE> object to receive 
      * messages that have been published to a destination. 
      *               
      * <P>In some cases, a connection may both publish and subscribe to a 
      * topic. The consumer <CODE>NoLocal</CODE> attribute allows a consumer
      * to inhibit the delivery of messages published by its own connection.
      * The default value for this attribute is False. The <CODE>noLocal</CODE> 
      * value must be supported by destinations that are topics. 
      *
      * @param destination the <CODE>Destination</CODE> to access 
      * @param messageSelector only messages with properties matching the
      * message selector expression are delivered. A value of null or
      * an empty string indicates that there is no message selector 
      * for the message consumer.
      * @param NoLocal  - if true, and the destination is a topic,
      *                   inhibits the delivery of messages published
      *                   by its own connection.  The behavior for
      *                   <CODE>NoLocal</CODE> is 
      *                   not specified if the destination is a queue.
      * 
      * @exception JMSException if the session fails to create a MessageConsumer