|
Oracle® Streams Advanced Queuing Java API Reference 10g Release 2 (10.2) B14291-01 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Allows browsing of messages on a Topic.
A client uses a TopicBrowser to look at messages on a topic without removing them. This interface is an Oracle-specific extension to JMS.
The browse methods return a java.util.Enumeration
that is used to scan the topic's messages. It may be an enumeration of the entire content of a topic or it may only contain the messages matching a message selector.
Messages may be arriving and expiring while the scan is done. JMS does not require the content of an enumeration to be a static snapshot of topic content. Whether these changes are visible or not depends on the JMS provider.
Since unexpired messages on topics are never deleted unless explicitly received by subscribers (durable subscribers in the case of OJMS), topic browsers provide a way for clients to indicate that all messages that have been seen in the current browse should be received and discarded. This allows clients to manage (if needed) the content of the topic without consuming increasing amounts of resources.
In order to guarantee properly message deletion during cleanup, it may be necessary for the implementation of topic browsers to lock messages being browsed. This will affect the visibility of messages by other message consumers with the same durable consumer name.
TopicReceiver
Method Summary | |
void |
close() Since a provider may allocate some resources on behalf of a TopicBrowser outside the JVM, clients should close them when they are not needed. |
java.util.Enumeration |
getEnumeration() Get an enumeration for browsing the current topic messages in the order they would be received. |
java.lang.String |
getMessageSelector() Get this topic browser's message selector expression. |
Topic |
getTopic() Get the topic associated with this topic browser. |
void |
purgeSeen() Purge the topic of all messages that were seen in the current browse. |
Method Detail |
public Topic getTopic() throws JMSException
Get the topic associated with this topic browser.
JMSException
- if JMS fails to get the topic associated with this Browser due to some JMS error.public java.lang.String getMessageSelector() throws JMSException
Get this topic browser's message selector expression.
JMSException
- if JMS fails to get the message selector for this browser due to some JMS error.public java.util.Enumeration getEnumeration() throws JMSException
Get an enumeration for browsing the current topic messages in the order they would be received.
JMSException
- if JMS fails to get the enumeration for this browser due to some JMS error.public void purgeSeen() throws JMSException
Purge the topic of all messages that were seen in the current browse. A message is considered seen if it was returned to the client via a call to nextElement()
during the browse.
Thus is the possible for a client to create a topic browser, call purge immediately, and not change the state of the topic (since no messages were seen by the above definition).
Purging a topic also does not affect the state of messages yet to be seen by the client during a browse.
Purging is supported only on topic browsers that were created in the LOCKED
mode. Attempting to purge topics that were not created in the LOCKED
mode will result in an exception.
The purge operation will take effect only if the session for this topic browser is commit
ed. If the session is rolled back, the purge operation will be undone and the messages will become visible again.
JMSException
- if a JMS fails to close this Browser due to some JMS error.public void close() throws JMSException
Since a provider may allocate some resources on behalf of a TopicBrowser outside the JVM, clients should close them when they are not needed. Relying on garbage collection to eventually reclaim these resources may not be timely enough.
JMSException
- if a JMS fails to close this Browser due to some JMS error.
|
Oracle® Streams Advanced Queuing Java API Reference 10g Release 2 (10.2) B14291-01 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |