1 /* 2 * The contents of this file are subject to the terms 3 * of the Common Development and Distribution License 4 * (the License). You may not use this file except in 5 * compliance with the License. 6 * 7 * You can obtain a copy of the license at 8 * https://glassfish.dev.java.net/public/CDDLv1.0.html or 9 * glassfish/bootstrap/legal/CDDLv1.0.txt. 10 * See the License for the specific language governing 11 * permissions and limitations under the License. 12 * 13 * When distributing Covered Code, include this CDDL 14 * Header Notice in each file and include the License file 15 * at glassfish/bootstrap/legal/CDDLv1.0.txt. 16 * If applicable, add the following below the CDDL Header, 17 * with the fields enclosed by brackets [] replaced by 18 * you own identifying information: 19 * "Portions Copyrighted [year] [name of copyright owner]" 20 * 21 * Copyright 2006 Sun Microsystems, Inc. All rights reserved. 22 */ 23 24 package javax.jms; 25 26 27 /** A <CODE>Topic</CODE> object encapsulates a provider-specific topic name. 28 * It is the way a client specifies the identity of a topic to JMS API methods. 29 * For those methods that use a <CODE>Destination</CODE> as a parameter, a 30 * <CODE>Topic</CODE> object may used as an argument . For 31 * example, a Topic can be used to create a <CODE>MessageConsumer</CODE> 32 * and a <CODE>MessageProducer</CODE> 33 * by calling: 34 *<UL> 35 *<LI> <CODE>Session.CreateConsumer(Destination destination)</CODE> 36 *<LI> <CODE>Session.CreateProducer(Destination destination)</CODE> 37 * 38 *</UL> 39 * 40 * <P>Many publish/subscribe (pub/sub) providers group topics into hierarchies 41 * and provide various options for subscribing to parts of the hierarchy. The 42 * JMS API places no restriction on what a <CODE>Topic</CODE> object 43 * represents. It may be a leaf in a topic hierarchy, or it may be a larger 44 * part of the hierarchy. 45 * 46 * <P>The organization of topics and the granularity of subscriptions to 47 * them is an important part of a pub/sub application's architecture. The JMS 48 * API 49 * does not specify a policy for how this should be done. If an application 50 * takes advantage of a provider-specific topic-grouping mechanism, it 51 * should document this. If the application is installed using a different 52 * provider, it is the job of the administrator to construct an equivalent 53 * topic architecture and create equivalent <CODE>Topic</CODE> objects. 54 * 55 * @version 1.1 - February 2, 2002 56 * @author Mark Hapner 57 * @author Rich Burridge 58 * @author Kate Stout 59 * 60 * @see Session#createConsumer(Destination) 61 * @see Session#createProducer(Destination) 62 * @see javax.jms.TopicSession#createTopic(String) 63 */ 64 65 public interface Topic extends Destination { 66 67 /** Gets the name of this topic. 68 * 69 * <P>Clients that depend upon the name are not portable. 70 * 71 * @return the topic name 72 * 73 * @exception JMSException if the JMS provider implementation of 74 * <CODE>Topic</CODE> fails to return the topic 75 * name due to some internal 76 * error. 77 */ 78 79 String 80 getTopicName() throws JMSException; 81 82 83 /** Returns a string representation of this object. 84 * 85 * @return the provider-specific identity values for this topic 86 */ 87 88 String 89 toString(); 90 } 91