TopicSubscriber (Java EE 5)

Java EE API

previous page next page

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

javax.jms Interface TopicSubscriber

All Superinterfaces:: MessageConsumer

public interface TopicSubscriber
extends MessageConsumer

Implements: MessageConsumer

客户端使用 TopicSubscriber 对象接收已发布到某个主题的消息。TopicSubscriber 对象是消息使用方的发布/订阅形式。MessageConsumer 可以使用 Session.createConsumer 创建。

TopicSession 允许为每个主题创建多个 TopicSubscriber 对象。它会将主题的每个消息传送给每个有资格接收它的订阅者。消息的每个副本都被视为完全不同的消息。对一个副本所做的工作不会影响其他副本；确认一个副本不等于确认其他副本；一个消息可能会立即传送，而另一个会等待其订阅者处理在它之前的消息。

常规 TopicSubscriber 对象不是持久的。它们仅接收在其活动状态下发布的消息。

订阅者的消息选择器过滤掉的消息将绝不会传送给订阅者。从订阅者的角度来看，这些消息不存在。

在某些情况下，连接可以既发布又订阅主题。订阅者 NoLocal 属性允许订阅者禁止传送由其自己的连接发布的消息。

如果客户端需要接收所有在主题上发布的消息，包括订阅者处于非活动状态时发布的消息，它使用持久 TopicSubscriber。JMS 提供者保留此持久订阅的记录并确保来自该主题发布者的所有消息能够一直保留，直到它们得到此持久订阅者的确认或消息过期。

具有持久订阅者的会话必须总是提供相同的客户端标识符。此外，每个客户端必须指定一个名称，该名称能够唯一地标识（在客户端标识符内）它所创建的每个持久订阅。一次只有一个会话可以拥有特定持久订阅的 TopicSubscriber。

客户端可以通过创建具有相同名称和新主题和/或消息选择器的持久 TopicSubscriber 来更改现有持久订阅。更改持久订阅等效于取消订阅（删除）旧的持久订阅，并创建一个新的持久订阅。

unsubscribe 方法用于删除持久订阅。unsubscribe 方法可以在 Session 或 TopicSession 级使用。此方法删除其提供者代表订阅者维持的状态。

创建 MessageConsumer 所提供的功能与创建 TopicSubscriber 所提供的功能相同。要创建持久订阅者，建议使用 Session.CreateDurableSubscriber。提供 TopicSubscriber 的目的是支持现有代码。

version

1.1 - February 2, 2002

英文文档：

A client uses a TopicSubscriber object to receive messages that have been published to a topic. A TopicSubscriber object is the publish/subscribe form of a message consumer. A MessageConsumer can be created by using Session.createConsumer.

A TopicSession allows the creation of multiple TopicSubscriber objects per topic. It will deliver each message for a topic to each subscriber eligible to receive it. Each copy of the message is treated as a completely separate message. Work done on one copy has no effect on the others; acknowledging one does not acknowledge the others; one message may be delivered immediately, while another waits for its subscriber to process messages ahead of it.

Regular TopicSubscriber objects are not durable. They receive only messages that are published while they are active.

Messages filtered out by a subscriber's message selector will never be delivered to the subscriber. From the subscriber's perspective, they do not exist.

In some cases, a connection may both publish and subscribe to a topic. The subscriber NoLocal attribute allows a subscriber to inhibit the delivery of messages published by its own connection.

If a client needs to receive all the messages published on a topic, including the ones published while the subscriber is inactive, it uses a durable TopicSubscriber. The JMS provider retains a record of this durable subscription and insures that all messages from the topic's publishers are retained until they are acknowledged by this durable subscriber or they have expired.

Sessions with durable subscribers must always provide the same client identifier. In addition, each client must specify a name that uniquely identifies (within client identifier) each durable subscription it creates. Only one session at a time can have a TopicSubscriber for a particular durable subscription.

A client can change an existing durable subscription by creating a durable TopicSubscriber with the same name and a new topic and/or message selector. Changing a durable subscription is equivalent to unsubscribing (deleting) the old one and creating a new one.

The unsubscribe method is used to delete a durable subscription. The unsubscribe method can be used at the Session or TopicSession level. This method deletes the state being maintained on behalf of the subscriber by its provider.

Creating a MessageConsumer provides the same features as creating a TopicSubscriber. To create a durable subscriber, use of Session.CreateDurableSubscriber is recommended. The TopicSubscriber is provided to support existing code.

Version:: 1.1 - February 2, 2002
Author:: Mark Hapner, Rich Burridge, Kate Stout
See Also:: Session.createConsumer(javax.jms.Destination), Session.createDurableSubscriber(javax.jms.Topic, java.lang.String), TopicSession, TopicSession.createSubscriber(javax.jms.Topic), MessageConsumer

Method Summary
`boolean`	`getNoLocal()` Gets the `NoLocal` attribute for this subscriber.
`Topic`	`getTopic()` Gets the `Topic` associated with this subscriber.

Methods inherited from interface javax.jms.MessageConsumer
`close, getMessageListener, getMessageSelector, receive, receive, receiveNoWait, setMessageListener`

Method Detail

public Topic getTopic() throws JMSException
获取与此订阅者相关的 `Topic`。

return 此订阅者的 `Topic`

Throws JMSException: 如果 JMS 提供者由于某个内部错误无法获取此主题订阅者的主题。

英文文档：
getTopic

Topic getTopic()
               throws JMSException

Gets the Topic associated with this subscriber.

Returns:: this subscriber's Topic
Throws:: JMSException - if the JMS provider fails to get the topic for this topic subscriber due to some internal error.

public boolean getNoLocal() throws JMSException
获取此订阅者的 `NoLocal` 属性。此属性的默认值为 false。

return 如果禁止传送本地发布的消息，则返回 true

Throws JMSException: 如果 JMS 提供者由于某个内部错误无法获取此主题订阅者的 `NoLocal` 属性。

英文文档：
getNoLocal

boolean getNoLocal()
                   throws JMSException

Gets the NoLocal attribute for this subscriber. The default value for this attribute is false.

Returns:: true if locally published messages are being inhibited
Throws:: JMSException - if the JMS provider fails to get the NoLocal attribute for this topic subscriber due to some internal error.