Home » jboss-javaee-sources » javax » jms » [javadoc | source]

    1   /*
    2    * JBoss, Home of Professional Open Source
    3    * Copyright 2005, JBoss Inc., and individual contributors as indicated
    4    * by the @authors tag. See the copyright.txt in the distribution for a
    5    * full listing of individual contributors.
    6    *
    7    * This is free software; you can redistribute it and/or modify it
    8    * under the terms of the GNU Lesser General Public License as
    9    * published by the Free Software Foundation; either version 2.1 of
   10    * the License, or (at your option) any later version.
   11    *
   12    * This software is distributed in the hope that it will be useful,
   13    * but WITHOUT ANY WARRANTY; without even the implied warranty of
   14    * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
   15    * Lesser General Public License for more details.
   16    *
   17    * You should have received a copy of the GNU Lesser General Public
   18    * License along with this software; if not, write to the Free
   19    * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
   20    * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
   21    */
   22   package javax.jms;
   23   
   24   /** A client uses a <CODE>TopicPublisher</CODE> object to publish messages on a 
   25    * topic. A <CODE>TopicPublisher</CODE> object is the publish-subscribe form
   26    * of a message producer.
   27    *
   28    * <P>Normally, the <CODE>Topic</CODE> is specified when a 
   29    * <CODE>TopicPublisher</CODE> is created.  In this case, an attempt to use 
   30    * the <CODE>publish</CODE> methods for an unidentified 
   31    * <CODE>TopicPublisher</CODE> will throw a 
   32    * <CODE>java.lang.UnsupportedOperationException</CODE>.
   33    *
   34    * <P>If the <CODE>TopicPublisher</CODE> is created with an unidentified 
   35    * <CODE>Topic</CODE>, an attempt to use the <CODE>publish</CODE> methods that 
   36    * assume that the <CODE>Topic</CODE> has been identified will throw a 
   37    * <CODE>java.lang.UnsupportedOperationException</CODE>.
   38    *
   39    * <P>During the execution of its <CODE>publish</CODE> method,
   40    * a message must not be changed by other threads within the client. 
   41    * If the message is modified, the result of the <CODE>publish</CODE> is 
   42    * undefined.
   43    * 
   44    * <P>After publishing a message, a client may retain and modify it
   45    * without affecting the message that has been published. The same message
   46    * object may be published multiple times.
   47    * 
   48    * <P>The following message headers are set as part of publishing a 
   49    * message: <code>JMSDestination</code>, <code>JMSDeliveryMode</code>, 
   50    * <code>JMSExpiration</code>, <code>JMSPriority</code>, 
   51    * <code>JMSMessageID</code> and <code>JMSTimeStamp</code>.
   52    * When the message is published, the values of these headers are ignored. 
   53    * After completion of the <CODE>publish</CODE>, the headers hold the values 
   54    * specified by the method publishing the message. It is possible for the 
   55    * <CODE>publish</CODE> method not to set <code>JMSMessageID</code> and 
   56    * <code>JMSTimeStamp</code> if the 
   57    * setting of these headers is explicitly disabled by the 
   58    * <code>MessageProducer.setDisableMessageID</code> or
   59    * <code>MessageProducer.setDisableMessageTimestamp</code> method.
   60    *
   61    *<P>Creating a <CODE>MessageProducer</CODE> provides the same features as
   62    * creating a <CODE>TopicPublisher</CODE>. A <CODE>MessageProducer</CODE> object is 
   63    * recommended when creating new code. The  <CODE>TopicPublisher</CODE> is
   64    * provided to support existing code.
   65   
   66    *
   67    *<P>Because <CODE>TopicPublisher</CODE> inherits from 
   68    * <CODE>MessageProducer</CODE>, it inherits the
   69    * <CODE>send</CODE> methods that are a part of the <CODE>MessageProducer</CODE> 
   70    * interface. Using the <CODE>send</CODE> methods will have the same
   71    * effect as using the
   72    * <CODE>publish</CODE> methods: they are functionally the same.
   73    * 
   74    * @see Session#createProducer(Destination) 
   75    * @see TopicSession#createPublisher(Topic)
   76    */
   77   
   78   public interface TopicPublisher extends MessageProducer
   79   {
   80   
   81      /** Gets the topic associated with this <CODE>TopicPublisher</CODE>.
   82       *
   83       * @return this publisher's topic
   84       *  
   85       * @exception JMSException if the JMS provider fails to get the topic for
   86       *                         this <CODE>TopicPublisher</CODE>
   87       *                         due to some internal error.
   88       */
   89   
   90      Topic getTopic() throws JMSException;
   91   
   92      /** Publishes a message to the topic.
   93       * Uses the <CODE>TopicPublisher</CODE>'s default delivery mode, priority,
   94       * and time to live.
   95       *
   96       * @param message the message to publish
   97       *
   98       * @exception JMSException if the JMS provider fails to publish the message
   99       *                         due to some internal error.
  100       * @exception MessageFormatException if an invalid message is specified.
  101       * @exception InvalidDestinationException if a client uses this method
  102       *                         with a <CODE>TopicPublisher</CODE> with
  103       *                         an invalid topic.
  104       * @exception java.lang.UnsupportedOperationException if a client uses this
  105       *                         method with a <CODE>TopicPublisher</CODE> that
  106       *                         did not specify a topic at creation time.
  107       * 
  108       * @see javax.jms.MessageProducer#getDeliveryMode()
  109       * @see javax.jms.MessageProducer#getTimeToLive()
  110       * @see javax.jms.MessageProducer#getPriority()
  111       */
  112   
  113      void publish(Message message) throws JMSException;
  114   
  115      /** Publishes a message to the topic, specifying delivery mode,
  116       * priority, and time to live.
  117       *
  118       * @param message the message to publish
  119       * @param deliveryMode the delivery mode to use
  120       * @param priority the priority for this message
  121       * @param timeToLive the message's lifetime (in milliseconds)
  122       *
  123       * @exception JMSException if the JMS provider fails to publish the message
  124       *                         due to some internal error.
  125       * @exception MessageFormatException if an invalid message is specified.
  126       * @exception InvalidDestinationException if a client uses this method
  127       *                         with a <CODE>TopicPublisher</CODE> with
  128       *                         an invalid topic.
  129       * @exception java.lang.UnsupportedOperationException if a client uses this
  130       *                         method with a <CODE>TopicPublisher</CODE> that
  131       *                         did not specify a topic at creation time.
  132       */
  133   
  134      void publish(Message message, int deliveryMode, int priority, long timeToLive) throws JMSException;
  135   
  136      /** Publishes a message to a topic for an unidentified message producer. 
  137       * Uses the <CODE>TopicPublisher</CODE>'s default delivery mode, 
  138       * priority, and time to live.
  139       *  
  140       * <P>Typically, a message producer is assigned a topic at creation 
  141       * time; however, the JMS API also supports unidentified message producers,
  142       * which require that the topic be supplied every time a message is
  143       * published.
  144       *
  145       * @param topic the topic to publish this message to
  146       * @param message the message to publish
  147       *  
  148       * @exception JMSException if the JMS provider fails to publish the message
  149       *                         due to some internal error.
  150       * @exception MessageFormatException if an invalid message is specified.
  151       * @exception InvalidDestinationException if a client uses
  152       *                         this method with an invalid topic.
  153       * 
  154       * @see javax.jms.MessageProducer#getDeliveryMode()
  155       * @see javax.jms.MessageProducer#getTimeToLive()
  156       * @see javax.jms.MessageProducer#getPriority()
  157       */
  158   
  159      void publish(Topic topic, Message message) throws JMSException;
  160   
  161      /** Publishes a message to a topic for an unidentified message 
  162       * producer, specifying delivery mode, priority and time to live.
  163       *  
  164       * <P>Typically, a message producer is assigned a topic at creation
  165       * time; however, the JMS API also supports unidentified message producers,
  166       * which require that the topic be supplied every time a message is
  167       * published.
  168       *
  169       * @param topic the topic to publish this message to
  170       * @param message the message to publish
  171       * @param deliveryMode the delivery mode to use
  172       * @param priority the priority for this message
  173       * @param timeToLive the message's lifetime (in milliseconds)
  174       *  
  175       * @exception JMSException if the JMS provider fails to publish the message
  176       *                         due to some internal error.
  177       * @exception MessageFormatException if an invalid message is specified.
  178       * @exception InvalidDestinationException if a client uses
  179       *                         this method with an invalid topic.
  180       */
  181   
  182      void publish(Topic topic, Message message, int deliveryMode, int priority, long timeToLive) throws JMSException;
  183   }

Home » jboss-javaee-sources » javax » jms » [javadoc | source]