01: /*
02: * @(#)Topic.java 1.17 02/04/09
03: *
04: * Copyright 1997-2002 Sun Microsystems, Inc. All Rights Reserved.
05: *
06: * SUN PROPRIETARY/CONFIDENTIAL.
07: * This software is the proprietary information of Sun Microsystems, Inc.
08: * Use is subject to license terms.
09: *
10: */
11:
12: package javax.jms;
13:
14: /** A <CODE>Topic</CODE> object encapsulates a provider-specific topic name.
15: * It is the way a client specifies the identity of a topic to JMS API methods.
16: * For those methods that use a <CODE>Destination</CODE> as a parameter, a
17: * <CODE>Topic</CODE> object may used as an argument . For
18: * example, a Topic can be used to create a <CODE>MessageConsumer</CODE>
19: * and a <CODE>MessageProducer</CODE>
20: * by calling:
21: *<UL>
22: *<LI> <CODE>Session.CreateConsumer(Destination destination)</CODE>
23: *<LI> <CODE>Session.CreateProducer(Destination destination)</CODE>
24: *
25: *</UL>
26: *
27: * <P>Many publish/subscribe (pub/sub) providers group topics into hierarchies
28: * and provide various options for subscribing to parts of the hierarchy. The
29: * JMS API places no restriction on what a <CODE>Topic</CODE> object
30: * represents. It may be a leaf in a topic hierarchy, or it may be a larger
31: * part of the hierarchy.
32: *
33: * <P>The organization of topics and the granularity of subscriptions to
34: * them is an important part of a pub/sub application's architecture. The JMS
35: * API
36: * does not specify a policy for how this should be done. If an application
37: * takes advantage of a provider-specific topic-grouping mechanism, it
38: * should document this. If the application is installed using a different
39: * provider, it is the job of the administrator to construct an equivalent
40: * topic architecture and create equivalent <CODE>Topic</CODE> objects.
41: *
42: * @version 1.1 - February 2, 2002
43: * @author Mark Hapner
44: * @author Rich Burridge
45: * @author Kate Stout
46: *
47: * @see Session#createConsumer(Destination)
48: * @see Session#createProducer(Destination)
49: * @see javax.jms.TopicSession#createTopic(String)
50: */
51:
52: public interface Topic extends Destination {
53:
54: /** Gets the name of this topic.
55: *
56: * <P>Clients that depend upon the name are not portable.
57: *
58: * @return the topic name
59: *
60: * @exception JMSException if the JMS provider implementation of
61: * <CODE>Topic</CODE> fails to return the topic
62: * name due to some internal
63: * error.
64: */
65:
66: String getTopicName() throws JMSException;
67:
68: /** Returns a string representation of this object.
69: *
70: * @return the provider-specific identity values for this topic
71: */
72:
73: String toString();
74: }
|