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 <CODE>Topic</CODE> object encapsulates a provider-specific topic name. 
   25    * It is the way a client specifies the identity of a topic to JMS API methods.
   26    * For those methods that use a <CODE>Destination</CODE> as a parameter, a 
   27    * <CODE>Topic</CODE> object may used as an argument . For 
   28    * example, a Topic can be used to create a <CODE>MessageConsumer</CODE>
   29    * and a <CODE>MessageProducer</CODE>
   30    * by calling:
   31    *<UL>
   32    *<LI> <CODE>Session.CreateConsumer(Destination destination)</CODE>
   33    *<LI> <CODE>Session.CreateProducer(Destination destination)</CODE>
   34    *
   35    *</UL>
   36    *
   37    * <P>Many publish/subscribe (pub/sub) providers group topics into hierarchies 
   38    * and provide various options for subscribing to parts of the hierarchy. The 
   39    * JMS API places no restriction on what a <CODE>Topic</CODE> object 
   40    * represents. It may be a leaf in a topic hierarchy, or it may be a larger 
   41    * part of the hierarchy.
   42    *
   43    * <P>The organization of topics and the granularity of subscriptions to 
   44    * them is an important part of a pub/sub application's architecture. The JMS 
   45    * API 
   46    * does not specify a policy for how this should be done. If an application 
   47    * takes advantage of a provider-specific topic-grouping mechanism, it 
   48    * should document this. If the application is installed using a different 
   49    * provider, it is the job of the administrator to construct an equivalent 
   50    * topic architecture and create equivalent <CODE>Topic</CODE> objects.
   51    *
   52    * @see        Session#createConsumer(Destination)
   53    * @see        Session#createProducer(Destination)
   54    * @see        javax.jms.TopicSession#createTopic(String)
   55    */
   56   
   57   public interface Topic extends Destination
   58   {
   59   
   60      /** Gets the name of this topic.
   61       *  
   62       * <P>Clients that depend upon the name are not portable.
   63       *  
   64       * @return the topic name
   65       *  
   66       * @exception JMSException if the JMS provider implementation of 
   67       *                         <CODE>Topic</CODE> fails to return the topic
   68       *                         name due to some internal
   69       *                         error.
   70       */
   71   
   72      String getTopicName() throws JMSException;
   73   
   74      /** Returns a string representation of this object.
   75       *
   76       * @return the provider-specific identity values for this topic
   77       */
   78   
   79      String toString();
   80   }