javax.jms

Interface Topic

All Superinterfaces:

Destination

All Known Subinterfaces:

SolTopic, TemporaryTopic

public interface Topic
extends Destination

A Topic object encapsulates a provider-specific topic name. It is the way a client specifies the identity of a topic to JMS API methods. For those methods that use a Destination as a parameter, a Topic object may used as an argument . For example, a Topic can be used to create a MessageConsumer and a MessageProducer by calling:

• Session.CreateConsumer(Destination destination)
• Session.CreateProducer(Destination destination)

Many publish/subscribe (pub/sub) providers group topics into hierarchies and provide various options for subscribing to parts of the hierarchy. The JMS API places no restriction on what a Topic object represents. It may be a leaf in a topic hierarchy, or it may be a larger part of the hierarchy.

The organization of topics and the granularity of subscriptions to them is an important part of a pub/sub application's architecture. The JMS API does not specify a policy for how this should be done. If an application takes advantage of a provider-specific topic-grouping mechanism, it should document this. If the application is installed using a different provider, it is the job of the administrator to construct an equivalent topic architecture and create equivalent Topic objects.

Solace Topics

Generally, a Topic name represents a hierarchy of levels, separated by slashes. Topics are used by producers for publishing, or by consumers as Topic Subscriptions. Only Topic Subscriptions can be wildcarded.

The following rules define valid Topics and Topic Subscriptions (using the EBNF syntax from http://www.w3.org/TR/REC-xml/#sec-notation): slash ::= "/" wildcard ::= ">" digit ::= [0-9] letter ::= [a-z][A-Z] symbol ::= [~`!\@$\%|^()_+={}\:,?/] | "#" | "-" | ";" | "[" | "]" level-char ::= digit | letter | symbol level ::= level-char (level-char)* topic ::= level (slash level)* 1 <= length (topic) <= 250 topic-subscription ::= wildcard | topic [slash wildcard] 1 <= length (topic-subscription) <= 250 Examples:

enterprise-1/branch-15/frontdesk (Topic or Topic subscription)

enterprise-2/> (Wildcarded Topic subscription)

A Topic is considered wildcarded if it meets one of the following conditions:

• The Topic name is ">"
• The Topic subscription has at least one level and ends with "/>"

Wildcarded Topics can only be used as Topic Subscriptions.

Version:

1.1 - February 2, 2002

See Also:

Session.createConsumer(Destination), Session.createProducer(Destination), TopicSession.createTopic(String)

Method Summary

Methods

Modifier and Type	Method and Description
String	getTopicName() Gets the name of this topic.
String	toString() Returns a string representation of this object.

Method Detail

getTopicName

String getTopicName()
                    throws JMSException

Gets the name of this topic.

Clients that depend upon the name are not portable.

Returns:

the topic name

Throws:

JMSException - if the JMS provider implementation of Topic fails to return the topic name due to some internal error.

toString

String toString()

Returns a string representation of this object.

Overrides:

toString in class Object

Returns:

the provider-specific identity values for this topic