xmlBlaster 2.2.0 API

org.xmlBlaster.engine
Class TopicHandler

java.lang.Object
  extended by org.xmlBlaster.engine.TopicHandler
All Implemented Interfaces:
I_AdminTopic, TopicHandlerMBean, I_AdminUsage, I_Timeout

public final class TopicHandler
extends java.lang.Object
implements I_Timeout, TopicHandlerMBean

A topic handles all MsgUnit entries of same oid and its subscribers.

This handler has the state UNCONFIGURED | UNREFERENCED | ALIVE | DEAD, see the boolean state access methods for a description

The topicHandler access is only over TopicAccessor which assures that most one thread enters TopicHandler to avoid synchronization problems.

Author:
Marcel Ruff
See Also:
The engine.message.lifecylce requirement, TestTopicLifeCycle

Field Summary
private  boolean administrativeInitialize
           
static int ALIVE
           
private  boolean clientTagLog
           
private  ContextNode contextNode
           
private  SessionName creatorSessionName
           
static int DEAD
           
private  Timeout destroyTimer
          This topic is destroyed after given timeout The timer is activated on state change to UNREFERENCED and removed on change to ALIVE
private  I_MsgDistributor distributor
           
private  boolean dyingInProgress
           
private  boolean handlerIsNewCreated
           
private  I_Queue historyQueue
          MsgUnit references are stored in a persistent history queue.
private  java.lang.String id
          The unique identifier of this topic e.g.
private  boolean isHistoryHandling
           
private  boolean isRegisteredInBigXmlDom
           
private static java.util.logging.Logger log
           
private  JmxMBeanHandle mbeanHandle
          My JMX registration
private  java.lang.String ME
           
private  MsgKeyData msgKeyData
          This holds the quick parsed key information, if you need the DOM use xmlKey instead
private  I_Map msgUnitCache
           
private  MsgUnitWrapper msgUnitWrapperUnderConstruction
           
private  java.lang.Object msgUnitWrapperUnderConstructionMutex
           
private  QueueQueryPlugin queueQueryPlugin
          this is used for administrative gets (queries on callback queue)
private  RequestBroker requestBroker
          The broker which manages me
private  ServerScope serverScope
           
static int SOFT_ERASED
           
private  int state
           
private  java.util.Map subscriberMap
          This map knows all clients which have subscribed on this message content and knows all individual wishes of the subscription (QoS).
private  I_SubscriptionListener subscriptionListener
           
private  Timestamp timerKey
           
private  TopicEntry topicEntry
           
private  TopicProperty topicProperty
          The configuration for this TopicHandler
static int UNCONFIGURED
           
static int UNDEF
           
private  java.lang.String uniqueKey
          Attribute oid of key tag:
static int UNREFERENCED
           
private  XmlKey xmlKey
          The xmlKey with parsed DOM tree, is null in state=UNCONFIGURED
 
Constructor Summary
TopicHandler(ServerScope serverScope, SessionInfo publisherSessionInfo, java.lang.String uniqueKey)
          Use this constructor if a yet unknown object is fed by method publish().
 
Method Summary
 void addSubscriber(SubscriptionInfo sub, boolean calleeIsXPathMatchCheck)
          A client subscribed to this message, multiple subscriptions from the same client are OK.
private  void addToBigDom()
          Merge the message DOM tree into the big xmlBlaster DOM tree
private  void administrativeInitialize(MsgKeyData msgKeyData, MsgQosData publishQos, PublishQosServer publishQosServer)
          Initialize the messageUnit cache and the history queue for this topic
private  boolean allowedToReconfigureTopicAndFixWrongLimits(MsgQosData msgQosData)
          Currently we support growing and shrinking, note that shrinking is not thoroughly tested.
(package private)  void change(MsgUnitWrapper msgUnitWrapper)
           
 boolean checkFilter(SessionInfo publisherSessionInfo, SubscriptionInfo sub, MsgUnitWrapper msgUnitWrapper, boolean handleException)
          Checks if the filters allow this message to be sent to the specified session
private  boolean checkIfAllowedToSend(SessionInfo publisherSessionInfo, SubscriptionInfo sub)
          Checks if it is allowed to send the entry to the callback queue.
 long clearHistoryQueue()
           
private  void clearSubscribers()
          subscribers are not informed here
protected  java.lang.Object clone()
           
private  java.util.ArrayList collectNotifySubscribersAboutErase(SessionName sessionName, QueryKeyData eraseKey, EraseQosServer eraseQos)
          Collect erase events with volatile non persistent erase messages.
static MsgQueueUpdateEntry createEntryFromWrapper(MsgUnitWrapper msgUnitWrapper, SubscriptionInfo sub)
           
 void entryDestroyed(MsgUnitWrapper msgUnitWrapper)
          Event triggered by MsgUnitWrapper itself when it reaches destroy state.
 long eraseFromHistoryQueue(SessionInfo sessionInfo, HistoryQos historyQos)
          Erase message instances but not the topic itself.
(package private)  void eraseRequest(SessionInfo sessionInfo, QueryKeyData eraseKey, EraseQosServer eraseQos)
          Notify all Listeners that a topic is erased.
 java.lang.String eraseTopic()
          JMX
 SubscriptionInfo[] findSubscriber(SessionInfo sessionInfo)
          Returns SubscriptionInfo instances of this session (a session may subscribe the same message multiple times).
private  void forwardToDestinations(SessionInfo publisherSessionInfo, MsgUnitWrapper cacheEntry, PublishQosServer publishQos)
          Forward PtP messages.
 java.lang.String getContentMime()
          What is the MIME type of this message content?

 java.lang.String getContentMimeExtended()
          Access the topics content mime extended.
 ContextNode getContextNode()
          The unique name of this topic instance.
 long getDestroyDelay()
          JMX
 boolean getDomTreeExists()
          Check if this topic is query-able by XPath.
 boolean getExactSubscribersExist()
           
 MsgUnit[] getHistoryMsgUnitArr(int num, boolean newestFirst)
          Returns a snapshot of all entries in the history
 I_Queue getHistoryQueue()
           
 MsgUnit[] getHistoryQueueEntries(java.lang.String querySpec)
          Query the history queue, can be peeking or consuming.
 java.lang.String getId()
          The unique identifier of this topic e.g.
 I_MsgDistributor getMsgDistributorPlugin()
           
 MsgKeyData getMsgKeyData()
           
(package private)  I_Map getMsgUnitCache()
          Stores the message 'meat'.
 MsgUnitWrapper getMsgUnitWrapper(long uniqueId)
           
 MsgUnitWrapper[] getMsgUnitWrapperArr(int num, boolean newestFirst)
          Returns a snapshot of all entries in the history
 long getNumOfCacheEntries()
          The number of entries in the msgCache.
 long getNumOfHistoryEntries()
          Get the number of history message references we contain.
 int getNumSubscribers()
          Access the number of registered subscribers on this topic.
 RequestBroker getRequestBroker()
           
 org.w3c.dom.Node getRootNode()
           
 java.lang.String getStateStr()
          Get the life cycle status of this topic.
 java.lang.String[] getSubscribers()
          JMX
 SubscriptionInfo[] getSubscriptionInfoArr()
          Get a snapshot of all subscriptions
 java.lang.String getTopicXml()
          Access the topics xml key.
 boolean getTopicXmlExists()
           
 java.lang.String getUniqueKey()
          This is the unique key of the topic and MsgUnit

 java.lang.String getUsageUrl()
          JMX
 XmlKey getXmlKey()
          Accessing the DOM parsed key of this topic.
 void handleCallbackFailed(java.util.Set removeSet)
          If a callback fails, we remove it from the subscription.
 boolean hasCacheEntries()
          Do we contain at least one message?
 boolean hasDomTree()
           
 boolean hasExactSubscribers()
          Returns true if there are subscribers with exact query on oid or domain
 boolean hasHistoryEntries()
          Do we contain at least one message?
 boolean hasSubscribers()
           
 boolean hasXmlKey()
          Check if there is a valid DOM parsed XML key available
private  void initMsgDistributorPlugin()
          instantiates and initializes a MsgDistributorPlugin if the topic property requires so.
private  I_Queue initQueue(I_Queue queue, java.lang.String queueName)
          Creates a queue with the properties specified in the historyQueueProperty
private  int invokeCallback(SessionInfo publisherSessionInfo, SubscriptionInfo sub, MsgUnitWrapper msgUnitWrapper, boolean doErrorHandling)
          Put the message into the callback queue of the subscribed client (Pub/Sub mode only).
private  void invokeCallbackAndHandleFailure(SessionInfo publisherSessionInfo, MsgUnitWrapper msgUnitWrapper)
          Send updates to all subscribed clients.
 boolean isAlive()
          This state is defined if we are still referenced by subscriptions or if we contain some messages
 boolean isDead()
          true if the instance is ready for garbage collection
static boolean isDirtyRead(SubscriptionInfo sub, MsgUnitWrapper msgUnitWrapper)
          Checks if the subscriber is a cluster and the message has the 'dirtyRead' flag set.
(package private)  boolean isInMsgStore(MsgUnitWrapper msgUnitWrapper)
          Check if the MsgUnitWrapper is owned by the TopicHandler (during construction).
 boolean isSoftErased()
          This state is reached on an erase(forceDestroy==false) invocation if there are still message referenced from the callback queue.
 boolean isUnconfigured()
          This state is reached if the TopicHandler is initially created by a subscribe() and is not yet configured by an initial publish()
 boolean isUndef()
          The initial state at creation
 boolean isUnreferenced()
          This is a cleanup state (it is recoverable) This state is reached when we are configured but not referenced by any subscribes and without any messages.
private  void notifySubscribersAboutErase(java.util.ArrayList msgSet)
          Send erase event with a volatile non persistent erase message.
 int numSubscribers()
           
 java.lang.String[] peekHistoryMessages(int numOfEntries)
          Peek messages from history queue, they are not removed.
 java.lang.String[] peekHistoryMessagesToFile(int numOfEntries, java.lang.String path)
          Peek messages from history queue and dump them to a file, they are not removed.
private  boolean persistTopic(TopicEntry entry)
           
private  TopicEntry persistTopicEntry()
          Create or access the cached persistence storage entry of this topic.
 PublishReturnQos publish(SessionInfo publisherSessionInfo, MsgUnit msgUnit, PublishQosServer publishQosServer)
          A new publish event (PubSub or PtP) arrives.
private  void removeFromBigDom()
          Remove Node in big xml dom
private  void removeFromBigSubscriptionSet()
          Remove myself from big subscription set
(package private)  SubscriptionInfo removeSubscriber(java.lang.String subscriptionInfoUniqueKey)
          A client wants to unSubscribe from this topic.
private  void removeTopicPersistence()
           
 void setUsageUrl(java.lang.String url)
           
private  void shutdownMsgDistributorPlugin()
           
 void startDestroyTimer()
           
private  void startupHistoryQueue()
          Should be invoked delayed as soon as TopicHandler instance is created an registered everywhere as we ask the msgUnitStore for the real messages if some history entries existed.
private  void startupMsgstore()
          This cache stores the 'real meat' (the MsgUnit data struct)
static boolean subscriberMayReceiveIt(SubscriptionInfo sub, MsgUnitWrapper msgUnitWrapper)
           
private  java.util.ArrayList timeout()
           
 void timeout(java.lang.Object userData)
          This timeout occurs after a configured delay (destroyDelay) in UNREFERENCED state
private  void toAlive()
           
private  java.util.ArrayList toDead(SessionName sessionName, QueryKeyData eraseKey, EraseQosServer eraseQos)
           
private  java.util.ArrayList toSoftErased(SessionInfo sessionInfo, QueryKeyData eraseKey, EraseQosServer eraseQos)
           
private  void toUnconfigured()
           
private  java.util.ArrayList toUnreferenced(boolean onAdministrativeCreate, boolean fromPersistenceStore)
           
 java.lang.String toXml()
          Dump state of this object into XML.
 java.lang.String toXml(java.lang.String extraOffset)
          Dump state of this object into XML.
private  java.lang.String[] unSubscribe(SessionInfo sessionInfo, java.lang.String qos)
          private helper to unSubscribe
 java.lang.String[] unSubscribeAll(java.lang.String qos)
          Invoke operation to unSubscribe all clients.
 java.lang.String[] unSubscribeByIndex(int index, java.lang.String qos)
          Invoke operation to unSubscribe one client by index of getSubscribers() listed.
 java.lang.String[] unSubscribeBySessionName(java.lang.String sessionName, java.lang.String qos)
          Invoke operation to unSubscribe one client by index of getSubscribers() listed.
 java.lang.String usage()
          JMX
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ME

private java.lang.String ME

serverScope

private final ServerScope serverScope

log

private static java.util.logging.Logger log

contextNode

private final ContextNode contextNode

dyingInProgress

private boolean dyingInProgress

id

private final java.lang.String id
The unique identifier of this topic e.g. "/node/heron/topic/Hello"


requestBroker

private final RequestBroker requestBroker
The broker which manages me


topicEntry

private TopicEntry topicEntry

distributor

private I_MsgDistributor distributor

subscriberMap

private final java.util.Map subscriberMap
This map knows all clients which have subscribed on this message content and knows all individual wishes of the subscription (QoS). The map contains SubscriptionInfo objects. It is a TreeMap, that means it keeps order information. TODO: express order attribute so that the first client will be served first. key = a unique key identifying the subscription value = SubscriptionInfo object


historyQueue

private I_Queue historyQueue
MsgUnit references are stored in a persistent history queue.


creatorSessionName

private SessionName creatorSessionName

topicProperty

private TopicProperty topicProperty
The configuration for this TopicHandler


msgUnitCache

private I_Map msgUnitCache

xmlKey

private XmlKey xmlKey
The xmlKey with parsed DOM tree, is null in state=UNCONFIGURED


uniqueKey

private java.lang.String uniqueKey
Attribute oid of key tag:


msgKeyData

private MsgKeyData msgKeyData
This holds the quick parsed key information, if you need the DOM use xmlKey instead


handlerIsNewCreated

private boolean handlerIsNewCreated

isRegisteredInBigXmlDom

private boolean isRegisteredInBigXmlDom

isHistoryHandling

private boolean isHistoryHandling

destroyTimer

private Timeout destroyTimer
This topic is destroyed after given timeout The timer is activated on state change to UNREFERENCED and removed on change to ALIVE


timerKey

private Timestamp timerKey

UNDEF

public static final int UNDEF
See Also:
Constant Field Values

UNCONFIGURED

public static final int UNCONFIGURED
See Also:
Constant Field Values

ALIVE

public static final int ALIVE
See Also:
Constant Field Values

UNREFERENCED

public static final int UNREFERENCED
See Also:
Constant Field Values

SOFT_ERASED

public static final int SOFT_ERASED
See Also:
Constant Field Values

DEAD

public static final int DEAD
See Also:
Constant Field Values

state

private int state

subscriptionListener

private I_SubscriptionListener subscriptionListener

msgUnitWrapperUnderConstructionMutex

private java.lang.Object msgUnitWrapperUnderConstructionMutex

msgUnitWrapperUnderConstruction

private MsgUnitWrapper msgUnitWrapperUnderConstruction

queueQueryPlugin

private QueueQueryPlugin queueQueryPlugin
this is used for administrative gets (queries on callback queue)


mbeanHandle

private JmxMBeanHandle mbeanHandle
My JMX registration


administrativeInitialize

private boolean administrativeInitialize

clientTagLog

private boolean clientTagLog
Constructor Detail

TopicHandler

public TopicHandler(ServerScope serverScope,
                    SessionInfo publisherSessionInfo,
                    java.lang.String uniqueKey)
             throws XmlBlasterException
Use this constructor if a yet unknown object is fed by method publish().

You should call publish() thereafter

Parameters:
requestBroker -
publisherSessionInfo - Is null if created by subscription
a - MsgUnitWrapper containing the CORBA MsgUnit data container
Throws:
XmlBlasterException
Method Detail

clone

protected java.lang.Object clone()
Overrides:
clone in class java.lang.Object

getId

public java.lang.String getId()
The unique identifier of this topic e.g. "/node/heron/topic/Hello"

Specified by:
getId in interface I_AdminTopic
Returns:
e.g. "/node/heron/topic/Hello"

getContextNode

public final ContextNode getContextNode()
The unique name of this topic instance.

Returns:
Never null, for example "/xmlBlaster/node/heron/topic/hello"

administrativeInitialize

private void administrativeInitialize(MsgKeyData msgKeyData,
                                      MsgQosData publishQos,
                                      PublishQosServer publishQosServer)
                               throws XmlBlasterException
Initialize the messageUnit cache and the history queue for this topic

Throws:
XmlBlasterException

startupMsgstore

private void startupMsgstore()
                      throws XmlBlasterException
This cache stores the 'real meat' (the MsgUnit data struct)

Throws:
XmlBlasterException

startupHistoryQueue

private void startupHistoryQueue()
                          throws XmlBlasterException
Should be invoked delayed as soon as TopicHandler instance is created an registered everywhere as we ask the msgUnitStore for the real messages if some history entries existed.

NOTE: queue can be null if maxEntries=0 is configured

This history queue entries hold weak references to the msgUnitCache entries

Throws:
XmlBlasterException

initQueue

private I_Queue initQueue(I_Queue queue,
                          java.lang.String queueName)
                   throws XmlBlasterException
Creates a queue with the properties specified in the historyQueueProperty

Parameters:
queue - the queue instance (if already existing or null otherwise)
queueName - The name to be given as Id to this queue
Returns:
returns the instance of the queue
Throws:
XmlBlasterException

getDomTreeExists

public boolean getDomTreeExists()
Description copied from interface: I_AdminTopic
Check if this topic is query-able by XPath.

Specified by:
getDomTreeExists in interface I_AdminTopic
Returns:
true if the DOM entry exists

hasDomTree

public boolean hasDomTree()
Returns:
false if topicProperty.isCreateDomEntry() was configured to false

getRequestBroker

public RequestBroker getRequestBroker()

hasXmlKey

public final boolean hasXmlKey()
Check if there is a valid DOM parsed XML key available

Returns:
false in state UNCONFIGURED

getTopicXmlExists

public final boolean getTopicXmlExists()
Specified by:
getTopicXmlExists in interface I_AdminTopic

getTopicXml

public final java.lang.String getTopicXml()
                                   throws XmlBlasterException
Description copied from interface: I_AdminTopic
Access the topics xml key.

Specified by:
getTopicXml in interface I_AdminTopic
Returns:
The XML string
Throws:
XmlBlasterException

getXmlKey

public final XmlKey getXmlKey()
                       throws XmlBlasterException
Accessing the DOM parsed key of this topic.

Returns:
Never null, the first publish freezes its key markup for this topic (immutable)
Throws:
XmlBlasterException - in state UNCONFIGURED or on DOM parse problems

persistTopicEntry

private TopicEntry persistTopicEntry()
                              throws XmlBlasterException
Create or access the cached persistence storage entry of this topic.

Returns:
null If no PublishQos is available to create persistent information
Throws:
XmlBlasterException

persistTopic

private boolean persistTopic(TopicEntry entry)
Returns:
true if this topicEntry was made persistent

allowedToReconfigureTopicAndFixWrongLimits

private final boolean allowedToReconfigureTopicAndFixWrongLimits(MsgQosData msgQosData)
Currently we support growing and shrinking, note that shrinking is not thoroughly tested.

Parameters:
msgQosData - The new configuration, can be adjusted by this method if limits are reached
Returns:
true if the change is accepted

publish

public PublishReturnQos publish(SessionInfo publisherSessionInfo,
                                MsgUnit msgUnit,
                                PublishQosServer publishQosServer)
                         throws XmlBlasterException
A new publish event (PubSub or PtP) arrives.
Publish filter plugin checks are done already
Cluster forwards are done already.

Parameters:
publisherSessionInfo - The publisher
msgUnit - The new message
publishQosServer - The decorator for msgUnit.getQosData()
Returns:
not null for PtP messages
Throws:
XmlBlasterException

isInMsgStore

boolean isInMsgStore(MsgUnitWrapper msgUnitWrapper)
Check if the MsgUnitWrapper is owned by the TopicHandler (during construction). NOTE: You need to synchronize this call over msgUnitCache


forwardToDestinations

private void forwardToDestinations(SessionInfo publisherSessionInfo,
                                   MsgUnitWrapper cacheEntry,
                                   PublishQosServer publishQos)
                            throws XmlBlasterException
Forward PtP messages. TODO: On exception continue to other destinations and return the successful/not-successful destinations in PublishReturnQos!!!

Throws:
XmlBlasterException

getMsgUnitCache

I_Map getMsgUnitCache()
Stores the message 'meat'.

If accessed from outside take care about deadlock.

Returns:
The storage containing the 'meat' of a message

change

void change(MsgUnitWrapper msgUnitWrapper)
      throws XmlBlasterException
Throws:
XmlBlasterException

getMsgUnitWrapper

public MsgUnitWrapper getMsgUnitWrapper(long uniqueId)
                                 throws XmlBlasterException
Throws:
XmlBlasterException

entryDestroyed

public void entryDestroyed(MsgUnitWrapper msgUnitWrapper)
Event triggered by MsgUnitWrapper itself when it reaches destroy state. This is an important entry point, and may not be called from a concurrent thread


getRootNode

public final org.w3c.dom.Node getRootNode()
                                   throws XmlBlasterException
Throws:
XmlBlasterException

addSubscriber

public void addSubscriber(SubscriptionInfo sub,
                          boolean calleeIsXPathMatchCheck)
                   throws XmlBlasterException
A client subscribed to this message, multiple subscriptions from the same client are OK.

Parameters:
calleeIsXPathMatchCheck - true The calling thread is internally to check if a Query matches a new published topic false The callee is a subscribe() thread from a client
Throws:
XmlBlasterException

handleCallbackFailed

public void handleCallbackFailed(java.util.Set removeSet)
                          throws XmlBlasterException
If a callback fails, we remove it from the subscription.

Generating dead letter and auto-logout to release all resources is done by DispatchWorker.

Throws:
XmlBlasterException

removeSubscriber

SubscriptionInfo removeSubscriber(java.lang.String subscriptionInfoUniqueKey)
A client wants to unSubscribe from this topic.

Returns:
the removed SubscriptionInfo object or null if not found

getUniqueKey

public java.lang.String getUniqueKey()
This is the unique key of the topic and MsgUnit

Specified by:
getUniqueKey in interface I_AdminTopic
Returns:
the <key oid='...'>

getMsgKeyData

public MsgKeyData getMsgKeyData()
Returns:
The key data of this topic (not DOM parsed) or null of not yet known

getContentMime

public java.lang.String getContentMime()
What is the MIME type of this message content?

Specified by:
getContentMime in interface I_AdminTopic
Returns:
the MIME type of the MsgUnit.content or null if not known

getContentMimeExtended

public java.lang.String getContentMimeExtended()
Description copied from interface: I_AdminTopic
Access the topics content mime extended.

Specified by:
getContentMimeExtended in interface I_AdminTopic
Returns:
Value of <key contentMimeExtended=''/>

invokeCallbackAndHandleFailure

private final void invokeCallbackAndHandleFailure(SessionInfo publisherSessionInfo,
                                                  MsgUnitWrapper msgUnitWrapper)
                                           throws XmlBlasterException
Send updates to all subscribed clients.

Parameters:
publisherSessionInfo - The sessionInfo of the publisher or null if not known or not online
Throws:
XmlBlasterException

checkIfAllowedToSend

private boolean checkIfAllowedToSend(SessionInfo publisherSessionInfo,
                                     SubscriptionInfo sub)
Checks if it is allowed to send the entry to the callback queue.

Parameters:
publisherSessionInfo -
sub -
Returns:
true if it is configured, there is a callback, and the topic is referenced

checkFilter

public final boolean checkFilter(SessionInfo publisherSessionInfo,
                                 SubscriptionInfo sub,
                                 MsgUnitWrapper msgUnitWrapper,
                                 boolean handleException)
                          throws XmlBlasterException
Checks if the filters allow this message to be sent to the specified session

Parameters:
publisherSessionInfo -
sub -
msgUnitWrapper -
Returns:
true if the message is approved to be sent, false otherwise
Throws:
XmlBlasterException - in case an exception happened when checking the filters. This method handles internally the publishing of dead letters in case of a throwable and after that it throws this XmlBlasterException to notify the invoked about the abnormal flow.

isDirtyRead

public static boolean isDirtyRead(SubscriptionInfo sub,
                                  MsgUnitWrapper msgUnitWrapper)
                           throws XmlBlasterException
Checks if the subscriber is a cluster and the message has the 'dirtyRead' flag set.

Parameters:
sub -
msgQosData -
Returns:
true if dirtyRead is set, false otherwise.
Throws:
XmlBlasterException

createEntryFromWrapper

public static final MsgQueueUpdateEntry createEntryFromWrapper(MsgUnitWrapper msgUnitWrapper,
                                                               SubscriptionInfo sub)
                                                        throws XmlBlasterException
Throws:
XmlBlasterException

invokeCallback

private final int invokeCallback(SessionInfo publisherSessionInfo,
                                 SubscriptionInfo sub,
                                 MsgUnitWrapper msgUnitWrapper,
                                 boolean doErrorHandling)
Put the message into the callback queue of the subscribed client (Pub/Sub mode only).

Parameters:
publisherSessionInfo - The sessionInfo of the publisher or null if not known or not online
sub - The subscription handle of the client
Returns:
-1 in case it was not able to complete the invocation due to an incorrect status (for example if it is unconfigured, unreferenced or if the session has no callback). Returns 0 if it was not able to complete the request even if the status was OK, 1 if successful. Never throws an exception. Returning -1 tells the invoker not to continue with these invocations (performance)

getNumSubscribers

public final int getNumSubscribers()
Description copied from interface: I_AdminTopic
Access the number of registered subscribers on this topic.

Specified by:
getNumSubscribers in interface I_AdminTopic
Returns:
Number of subscriptions

numSubscribers

public final int numSubscribers()

hasSubscribers

public final boolean hasSubscribers()

getSubscriptionInfoArr

public final SubscriptionInfo[] getSubscriptionInfoArr()
Get a snapshot of all subscriptions


getExactSubscribersExist

public final boolean getExactSubscribersExist()
Specified by:
getExactSubscribersExist in interface I_AdminTopic

hasExactSubscribers

public final boolean hasExactSubscribers()
Returns true if there are subscribers with exact query on oid or domain

Returns:
false If no subscriber exists or all subscribers are through XPath query

findSubscriber

public final SubscriptionInfo[] findSubscriber(SessionInfo sessionInfo)
Returns SubscriptionInfo instances of this session (a session may subscribe the same message multiple times).

This searches from a given SessionInfo.

Returns:
never null but can be of length==0

clearSubscribers

private void clearSubscribers()
subscribers are not informed here


hasHistoryEntries

public boolean hasHistoryEntries()
Do we contain at least one message?


getNumOfHistoryEntries

public long getNumOfHistoryEntries()
Get the number of history message references we contain.

Specified by:
getNumOfHistoryEntries in interface I_AdminTopic
Returns:
Number of messages

hasCacheEntries

public boolean hasCacheEntries()
Do we contain at least one message?


getNumOfCacheEntries

public long getNumOfCacheEntries()
The number of entries in the msgCache.

Specified by:
getNumOfCacheEntries in interface I_AdminTopic
Returns:
Number of cached messages

getMsgUnitWrapperArr

public MsgUnitWrapper[] getMsgUnitWrapperArr(int num,
                                             boolean newestFirst)
                                      throws XmlBlasterException
Returns a snapshot of all entries in the history

Parameters:
num - Number of entries wanted, not more than size of history queue are returned.
If -1 all entries in history queue are returned
newestFirst - true is the normal case (the latest message is returned first)
Returns:
Checked MsgUnitWrapper entries (destroyed and expired ones are removed), never null
Throws:
XmlBlasterException

getHistoryMsgUnitArr

public MsgUnit[] getHistoryMsgUnitArr(int num,
                                      boolean newestFirst)
                               throws XmlBlasterException
Returns a snapshot of all entries in the history

Parameters:
num - Number of entries wanted, not more than size of history queue are returned.
If -1 all entries in history queue are returned
newestFirst - true is the normal case (the latest message is returned first)
Returns:
Checked entries (destroyed and expired ones are removed), never null
Throws:
XmlBlasterException

eraseFromHistoryQueue

public long eraseFromHistoryQueue(SessionInfo sessionInfo,
                                  HistoryQos historyQos)
                           throws XmlBlasterException
Erase message instances but not the topic itself.

Parameters:
sessionInfo - The user which has called erase()
historyQos - Describes which message instances
Throws:
XmlBlasterException - Currently only all history entries can be destroyed

isUndef

public boolean isUndef()
The initial state at creation


isUnconfigured

public boolean isUnconfigured()
This state is reached if the TopicHandler is initially created by a subscribe() and is not yet configured by an initial publish()


isAlive

public boolean isAlive()
This state is defined if we are still referenced by subscriptions or if we contain some messages


isUnreferenced

public boolean isUnreferenced()
This is a cleanup state (it is recoverable) This state is reached when we are configured but not referenced by any subscribes and without any messages. We are still in registered in the BigDom tree for XPath queries etc.


isSoftErased

public boolean isSoftErased()
This state is reached on an erase(forceDestroy==false) invocation if there are still message referenced from the callback queue.


isDead

public boolean isDead()
true if the instance is ready for garbage collection


toUnconfigured

private void toUnconfigured()

toAlive

private void toAlive()
              throws XmlBlasterException
Throws:
XmlBlasterException

removeTopicPersistence

private void removeTopicPersistence()

toUnreferenced

private java.util.ArrayList toUnreferenced(boolean onAdministrativeCreate,
                                           boolean fromPersistenceStore)
                                    throws XmlBlasterException
Throws:
XmlBlasterException

startDestroyTimer

public void startDestroyTimer()

toSoftErased

private java.util.ArrayList toSoftErased(SessionInfo sessionInfo,
                                         QueryKeyData eraseKey,
                                         EraseQosServer eraseQos)
Parameters:
sessionInfo - The session which triggered the erase
eraseKey - The erase request
eraseQos - The erase request

toDead

private java.util.ArrayList toDead(SessionName sessionName,
                                   QueryKeyData eraseKey,
                                   EraseQosServer eraseQos)
Parameters:
sessionName - The session which triggered this event
eraseKey - The erase request
eraseQos - The erase request

addToBigDom

private void addToBigDom()
                  throws XmlBlasterException
Merge the message DOM tree into the big xmlBlaster DOM tree

Throws:
XmlBlasterException

removeFromBigDom

private void removeFromBigDom()
Remove Node in big xml dom


notifySubscribersAboutErase

private void notifySubscribersAboutErase(java.util.ArrayList msgSet)
Send erase event with a volatile non persistent erase message. The oid of the PtP message is temporary "__sys__ErasedTopic" and later the oid of the erased topic, the state is set to STATE_ERASED

This method may NOT be called from inside a synchronized((TopicHandler)this): The CB worker thread which empties the callback queue may call this TopicHandler.entryDestroyed() which could cause a dead lock.

Parameters:
sessionName - The session which triggered the erase

collectNotifySubscribersAboutErase

private java.util.ArrayList collectNotifySubscribersAboutErase(SessionName sessionName,
                                                               QueryKeyData eraseKey,
                                                               EraseQosServer eraseQos)
Collect erase events with volatile non persistent erase messages. The oid of the PtP message is temporary "__sys__ErasedTopic" and later the oid of the erased topic, the state is set to STATE_ERASED

Parameters:
sessionName - The session which triggered the erase
eraseKey - Can be null if not known (e.g. for implicit erase after unSubscribe or last message is expired)
eraseQos - Can be null if not known
Returns:
A set containing MsgUnit instances to send to the various clients

removeFromBigSubscriptionSet

private void removeFromBigSubscriptionSet()
Remove myself from big subscription set


eraseRequest

final void eraseRequest(SessionInfo sessionInfo,
                        QueryKeyData eraseKey,
                        EraseQosServer eraseQos)
                 throws XmlBlasterException
Notify all Listeners that a topic is erased.

Parameters:
sessionInfo - The session which wants to erase
eraseKey - The original EraseKey
eraseQos -
Throws:
XmlBlasterException

timeout

public final void timeout(java.lang.Object userData)
This timeout occurs after a configured delay (destroyDelay) in UNREFERENCED state

Specified by:
timeout in interface I_Timeout
Parameters:
userData - You get bounced back your userData which you passed with Timeout.addTimeoutListener()

timeout

private java.util.ArrayList timeout()

getStateStr

public java.lang.String getStateStr()
Description copied from interface: I_AdminTopic
Get the life cycle status of this topic.

Specified by:
getStateStr in interface I_AdminTopic
Returns:
"ALIVE" or "DEAD" etc.

toXml

public final java.lang.String toXml()
Dump state of this object into XML.

Specified by:
toXml in interface I_AdminTopic
Returns:
XML state of TopicHandler

toXml

public final java.lang.String toXml(java.lang.String extraOffset)
Dump state of this object into XML.

Is implemented for dirty reads

Parameters:
extraOffset - indenting of tags
Returns:
XML state of TopicHandler

getHistoryQueue

public I_Queue getHistoryQueue()

getHistoryQueueEntries

public MsgUnit[] getHistoryQueueEntries(java.lang.String querySpec)
                                 throws XmlBlasterException
Query the history queue, can be peeking or consuming.

Specified by:
getHistoryQueueEntries in interface I_AdminTopic
Parameters:
querySpec - Can be configured to be consuming
Throws:
XmlBlasterException
See Also:
The engine.qos.queryspec.QueueQuery requirement

initMsgDistributorPlugin

private void initMsgDistributorPlugin()
                               throws XmlBlasterException
instantiates and initializes a MsgDistributorPlugin if the topic property requires so. If such a plugin exists already it is left untouched.

Throws:
XmlBlasterException

shutdownMsgDistributorPlugin

private void shutdownMsgDistributorPlugin()

subscriberMayReceiveIt

public static final boolean subscriberMayReceiveIt(SubscriptionInfo sub,
                                                   MsgUnitWrapper msgUnitWrapper)

getMsgDistributorPlugin

public final I_MsgDistributor getMsgDistributorPlugin()
Returns:
The configure plugin or null

getSubscribers

public final java.lang.String[] getSubscribers()
JMX

Specified by:
getSubscribers in interface I_AdminTopic
Returns:
array with absolute session names

unSubscribeByIndex

public final java.lang.String[] unSubscribeByIndex(int index,
                                                   java.lang.String qos)
                                            throws XmlBlasterException
Description copied from interface: I_AdminTopic
Invoke operation to unSubscribe one client by index of getSubscribers() listed. Note: The subscriber does not get any notification that his subscription is lost.

Specified by:
unSubscribeByIndex in interface I_AdminTopic
Parameters:
index - 0 will kill the first listed subscribing client, 1 the second and so forth
qos - The qos XML string (e.g. "" or "")
Returns:
The status string
Throws:
XmlBlasterException

unSubscribeBySessionName

public final java.lang.String[] unSubscribeBySessionName(java.lang.String sessionName,
                                                         java.lang.String qos)
                                                  throws XmlBlasterException
Description copied from interface: I_AdminTopic
Invoke operation to unSubscribe one client by index of getSubscribers() listed. Note: The subscriber does not get any notification that his subscription is lost.

Specified by:
unSubscribeBySessionName in interface I_AdminTopic
Parameters:
sessionName - You can specify a relative name "client/joe/1" or an absolute name "/node/heron/client/joe/1"
qos - The qos XML string (e.g. "" or "")
Returns:
The status string
Throws:
XmlBlasterException

unSubscribe

private java.lang.String[] unSubscribe(SessionInfo sessionInfo,
                                       java.lang.String qos)
                                throws XmlBlasterException
private helper to unSubscribe

Throws:
XmlBlasterException

unSubscribeAll

public final java.lang.String[] unSubscribeAll(java.lang.String qos)
                                        throws XmlBlasterException
Description copied from interface: I_AdminTopic
Invoke operation to unSubscribe all clients. Note: The subscribers don't get any notification that their subscription is lost.

Specified by:
unSubscribeAll in interface I_AdminTopic
Parameters:
qos - The qos XML string (e.g. "" or "")
Returns:
The status string
Throws:
XmlBlasterException

peekHistoryMessages

public java.lang.String[] peekHistoryMessages(int numOfEntries)
                                       throws XmlBlasterException
Description copied from interface: I_AdminTopic
Peek messages from history queue, they are not removed.

Specified by:
peekHistoryMessages in interface I_AdminTopic
Parameters:
numOfEntries - The number of messages to peek, the newest first
Returns:
The dump of the messages
Throws:
XmlBlasterException

clearHistoryQueue

public long clearHistoryQueue()
Specified by:
clearHistoryQueue in interface I_AdminTopic

peekHistoryMessagesToFile

public java.lang.String[] peekHistoryMessagesToFile(int numOfEntries,
                                                    java.lang.String path)
                                             throws java.lang.Exception
Description copied from interface: I_AdminTopic
Peek messages from history queue and dump them to a file, they are not removed.

Specified by:
peekHistoryMessagesToFile in interface I_AdminTopic
Parameters:
numOfEntries - The number of messages to peek, taken from the front
path - The path to dump the messages to, it is automatically created if missing.
Returns:
The absolute file names dumped
Throws:
java.lang.Exception

eraseTopic

public final java.lang.String eraseTopic()
                                  throws XmlBlasterException
JMX

Specified by:
eraseTopic in interface I_AdminTopic
Returns:
A status message
Throws:
XmlBlasterException

getDestroyDelay

public long getDestroyDelay()
JMX

Specified by:
getDestroyDelay in interface I_AdminTopic
Returns:
milli seconds

usage

public java.lang.String usage()
JMX

Specified by:
usage in interface I_AdminUsage
Returns:
a human readable usage help string

getUsageUrl

public java.lang.String getUsageUrl()
JMX

Specified by:
getUsageUrl in interface I_AdminUsage
Returns:
A link on javadoc for JMX usage

setUsageUrl

public void setUsageUrl(java.lang.String url)
Specified by:
setUsageUrl in interface I_AdminUsage

xmlBlaster 2.2.0 API

Copyright © 1999-2014 The xmlBlaster.org contributers.