org.xmlBlaster.engine
Class SubscriptionInfo

java.lang.Object
  org.xmlBlaster.engine.SubscriptionInfo

All Implemented Interfaces:

I_AdminSubscription, SubscriptionInfoMBean, I_AdminUsage

public final class SubscriptionInfo
extends java.lang.Object
implements SubscriptionInfoMBean

This is a container to hold references on all interesting data concerning a subscription of exactly one topic from exactly one client.

Author:

Marcel Ruff

See Also:

The interface.subscribe requirement

Field Summary

private java.util.ArrayList	childrenList It it is a query subscription, we remember all subscriptions which resulted from this query
private ContextNode	contextNode
private long	creationTime
private ServerScope	glob The global handle
private boolean	isShutdown
private KeyData	keyData reference to keyData
private static java.util.logging.Logger	log Logging to channel "core"
private JmxMBeanHandle	mbeanHandle My JMX registration
private java.lang.String	ME
private long	persistenceId uniqueId used to store this in queue
private SubscriptionInfo	querySub A reference to the query subscription (XPATH), which created this subscription If the subscription was EXACT, querySub is null
private SessionInfo	sessionInfo The initiatior of this subscription
private int	subscribeCounter If duplicateUpdates=false is set we can check here how often this message is subscribed from the same client
private SubscribeQosServer	subscribeQos reference to 'Quality of Service' of subscribe() / unSubscribe()
private TopicHandler	topicHandler reference to my managing container
private java.lang.String	uniqueKey The unique key of a subscription (subscriptionId), which is a function of f(keyData,xmlQos).
private java.util.Map<java.lang.String,java.lang.Object>	userMap Map to store arbitrary info about the topic to client relation, is cleaned up automatically when unSubscribe happens Useful for example for plugins

Constructor Summary

SubscriptionInfo(ServerScope glob, SessionInfo sessionInfo, KeyData keyData, SubscribeQosServer qos)
Use this constructor for an exact subscription.

SubscriptionInfo(ServerScope glob, SessionInfo sessionInfo, SubscriptionInfo querySub, KeyData keyData)
Use this constructor it the subscription is a result of a XPath subscription

Method Summary

void	addSubscription(SubscriptionInfo subs) For this query subscription remember all resulted child subscriptions
void	addTopicHandler(TopicHandler topicHandler) This must be called as soon as my TopicHandler handles me.
void	decrSubscribeCounter() If same client subscribes multiple times on same topic but wants to suppress multi-updates (e.g.
private static java.lang.String	generateUniqueKey(KeyData keyData, QueryQosData xmlQos, boolean clusterWideUnique) This static method may be used from external objects to get the unique key of a subscription.
AccessFilterQos[]	getAccessFilterArr()
java.lang.String[]	getAccessFilters() Access the filter QoS of this subscription.
SubscriptionInfo[]	getChildrenSubscriptions() For this query subscription return all resulted subscriptions
long	getCreationTime() Time when this Subscription is invoked.
java.lang.String	getCreationTimestamp() Get the human readable timestamp when this subscription was established.
java.lang.String[]	getDependingSubscriptions() Get my depending subscriptions (childrens), usually caused by an XPATH subscription.
java.lang.String	getId() Access the unique identifier of this subscription.
KeyData	getKeyData() Access on KeyData object
java.lang.String	getKeyOid() The oid of the message we belong to
I_Queue	getMsgQueue() My destination queue.
java.lang.String	getParentSubscription() Get the parent subscription ID.
long	getPersistenceId() Gets the uniqueId for the persistence of this session.
QueryQosData	getQueryQosData() Access on SubscribeQosServer object
java.util.Map	getQueryQosDataClientProperties()
SessionInfo	getSessionInfo() The session info of the client who initiated this subscription
java.lang.String	getSessionName() Get the session name of the subscriber.
int	getSubscribeCounter() If same client subscribes multiple times on same topic but wants to suppress multi-updates (e.g.
java.lang.String	getSubscribeKeyStr() Get the subscription key.
SubscribeQosServer	getSubscribeQosServer()
java.lang.String	getSubscribeQosStr() Get the configuration for this subscription.
java.lang.String	getSubscriptionId() Accessing a unique subscription id generated for this SubscriptionInfo.
java.lang.String	getSubSourceSubscriptionId() Accessing the unique subscription id from method subscribe(), which was the reason for this SubscriptionInfo
TopicHandler	getTopicHandler()
java.lang.String	getTopicId() Get the subscribed topic.
java.lang.String	getUsageUrl() JMX
java.lang.Object	getUserObject(java.lang.String key, java.lang.Object defaultValue) Map to store arbitrary info about the topic to client relation, is cleaned up automatically when unSubscribe happens Useful for example for plugins
java.util.Map<java.lang.String,java.lang.Object>	getUserObjectMap() Use carefully to not harm other plugins.
boolean	hasUserObject(java.lang.String key)
void	incrSubscribeCounter() If same client subscribes multiple times on same topic but wants to suppress multi-updates (e.g.
private void	init(ServerScope glob, SessionInfo sessionInfo, KeyData keyData, SubscribeQosServer qos)
private void	initSubscriptionId() For JMX the uniqueKey may not contain commas ','.
boolean	isCreatedByQuerySubscription() If true this is a child.
boolean	isExact()
boolean	isQuery()
boolean	isShutdown()
(package private) static boolean	isSubscribeId(java.lang.String id) Test if this id is a subscribeId (starts with "__subId:")
void	removeChildSubscription(SubscriptionInfo subs) For this query subscription remember all resulted subscriptions
(package private) void	removeSubscribe() Telling my container that i am not subscribing any more.
void	setPersistenceId(long persistenceId) Sets the uniqueId used to retrieve this session from the persistence
void	setUsageUrl(java.lang.String url)
java.lang.Object	setUserObject(java.lang.String key, java.lang.Object value) The key should use a prefix to not collide with other users / plugins.
void	shutdown() Cleanup subscription.
java.lang.String	toString()
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.
java.lang.String	toXmlSmall(java.lang.String extraOffset) Dump state of this object into XML.
void	update(SubscribeQosServer newQos) Supports limited reconfiguration with the given newQos.
java.lang.String	usage() JMX
static void	verifySubscriptionId(boolean isClusterNode, SessionName sessionName, QueryKeyData xmlKey, SubscribeQosServer subscribeQos)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

ME

private java.lang.String ME

contextNode

private ContextNode contextNode

glob

private ServerScope glob

The global handle

log

private static java.util.logging.Logger log

Logging to channel "core"

sessionInfo

private SessionInfo sessionInfo

The initiatior of this subscription

keyData

private KeyData keyData

reference to keyData

subscribeQos

private SubscribeQosServer subscribeQos

reference to 'Quality of Service' of subscribe() / unSubscribe()

uniqueKey

private java.lang.String uniqueKey

The unique key of a subscription (subscriptionId), which is a function of f(keyData,xmlQos).
This is the returned id of a subscribe() invocation

topicHandler

private TopicHandler topicHandler

reference to my managing container

querySub

private SubscriptionInfo querySub

A reference to the query subscription (XPATH), which created this subscription If the subscription was EXACT, querySub is null

childrenList

private java.util.ArrayList childrenList

It it is a query subscription, we remember all subscriptions which resulted from this query

userMap

private java.util.Map<java.lang.String,java.lang.Object> userMap

Map to store arbitrary info about the topic to client relation, is cleaned up automatically when unSubscribe happens Useful for example for plugins

subscribeCounter

private int subscribeCounter

If duplicateUpdates=false is set we can check here how often this message is subscribed from the same client

creationTime

private long creationTime

persistenceId

private long persistenceId

uniqueId used to store this in queue

mbeanHandle

private JmxMBeanHandle mbeanHandle

My JMX registration

isShutdown

private boolean isShutdown

Constructor Detail

SubscriptionInfo

public SubscriptionInfo(ServerScope glob,
                        SessionInfo sessionInfo,
                        KeyData keyData,
                        SubscribeQosServer qos)
                 throws XmlBlasterException

Use this constructor for an exact subscription.

Parameters:

sessionInfo - The session which initiated this subscription

keyData - The message meta info

qos - This may be a SubscribeQosServer or a UnSubscribeQosServer instance

Throws:

XmlBlasterException

SubscriptionInfo

public SubscriptionInfo(ServerScope glob,
                        SessionInfo sessionInfo,
                        SubscriptionInfo querySub,
                        KeyData keyData)
                 throws XmlBlasterException

Use this constructor it the subscription is a result of a XPath subscription

Parameters:

sessionInfo - The session which initiated this subscription

querySub - The XPATH query subscription which is has us as a child

keyData - The matching key for the above querySub

Throws:

XmlBlasterException

Method Detail

init

private void init(ServerScope glob,
                  SessionInfo sessionInfo,
                  KeyData keyData,
                  SubscribeQosServer qos)
           throws XmlBlasterException

Throws:

XmlBlasterException

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

incrSubscribeCounter

public void incrSubscribeCounter()

If same client subscribes multiple times on same topic but wants to suppress multi-updates (e.g. cluster node clients).

decrSubscribeCounter

public void decrSubscribeCounter()

If same client subscribes multiple times on same topic but wants to suppress multi-updates (e.g. cluster node clients).

getSubscribeCounter

public int getSubscribeCounter()

If same client subscribes multiple times on same topic but wants to suppress multi-updates (e.g. cluster node clients).

getSessionInfo

public SessionInfo getSessionInfo()

The session info of the client who initiated this subscription

Returns:

Never null, but the sessionInfo instance may be meanwhile shutdown

getMsgQueue

public I_Queue getMsgQueue()

My destination queue.

addSubscription

public void addSubscription(SubscriptionInfo subs)

For this query subscription remember all resulted child subscriptions

removeChildSubscription

public void removeChildSubscription(SubscriptionInfo subs)

For this query subscription remember all resulted subscriptions

getChildrenSubscriptions

public SubscriptionInfo[] getChildrenSubscriptions()

For this query subscription return all resulted subscriptions

Returns:

null if not a query subscription with children

isQuery

public boolean isQuery()

isExact

public boolean isExact()

Returns:

true if it is an exact subscription. Not a query nor a domain subscriptions.

isCreatedByQuerySubscription

public boolean isCreatedByQuerySubscription()

If true this is a child. It is automatically generated by a query subscription.

Returns:

getAccessFilterArr

public AccessFilterQos[] getAccessFilterArr()

Returns:

Null if none configured

addTopicHandler

public void addTopicHandler(TopicHandler topicHandler)

This must be called as soon as my TopicHandler handles me.

Parameters:

topicHandler - I'm handled (lifetime) by this handler

getTopicHandler

public TopicHandler getTopicHandler()

getCreationTime

public long getCreationTime()

Time when this Subscription is invoked.

Returns:

the creation time of this subscription (in millis)

removeSubscribe

void removeSubscribe()

Telling my container that i am not subscribing any more.

getKeyData

public KeyData getKeyData()

Access on KeyData object

Returns:

KeyData object

getKeyOid

public java.lang.String getKeyOid()

The oid of the message we belong to

getQueryQosData

public QueryQosData getQueryQosData()

Access on SubscribeQosServer object

Returns:

SubscribeQosServer object or null

getQueryQosDataClientProperties

public java.util.Map getQueryQosDataClientProperties()

Returns:

null if none found

update

public void update(SubscribeQosServer newQos)

Supports limited reconfiguration with the given newQos.

Parameters:

newQos - The new QueryQosData to use

getSubscribeQosServer

public SubscribeQosServer getSubscribeQosServer()

Returns:

Can be null

getSubscriptionId

public java.lang.String getSubscriptionId()

Accessing a unique subscription id generated for this SubscriptionInfo.

The key will be generated on first invocation

Returns:

A unique key for this particular subscription

initSubscriptionId

private void initSubscriptionId()
                         throws XmlBlasterException

For JMX the uniqueKey may not contain commas ','.

Throws:

XmlBlasterException

getSubSourceSubscriptionId

public java.lang.String getSubSourceSubscriptionId()
                                            throws XmlBlasterException

Accessing the unique subscription id from method subscribe(), which was the reason for this SubscriptionInfo

Returns:

The subscription id which is used in updateQos - $lt;subscritpionId>

Throws:

XmlBlasterException

shutdown

public void shutdown()

Cleanup subscription.

isShutdown

public boolean isShutdown()

isSubscribeId

static boolean isSubscribeId(java.lang.String id)

Test if this id is a subscribeId (starts with "__subId:")

generateUniqueKey

private static java.lang.String generateUniqueKey(KeyData keyData,
                                                  QueryQosData xmlQos,
                                                  boolean clusterWideUnique)
                                           throws XmlBlasterException

This static method may be used from external objects to get the unique key of a subscription.

For JMX the uniqueKey may not contain commas ','.

Parameters:

clusterWideUnique - If false the key is unique for this xmlBlaster instance only

Returns:

A unique key for this particular subscription, for example:
__subId:heron-53

Throws:

XmlBlasterException

See Also:

org.xmlBlaster.util.qos.QueryQosData#generateSubscriptionId(String)

verifySubscriptionId

public static void verifySubscriptionId(boolean isClusterNode,
                                        SessionName sessionName,
                                        QueryKeyData xmlKey,
                                        SubscribeQosServer subscribeQos)
                                 throws XmlBlasterException

Parameters:

sessionName -

xmlKey -

subscribeQos -

Throws:

XmlBlasterException

See Also:

org.xmlBlaster.util.qos.QueryQosData#generateSubscriptionId(String), generateUniqueKey

toXml

public java.lang.String toXml()

Dump state of this object into XML.

Returns:

XML state of SubscriptionInfo

toXml

public java.lang.String toXml(java.lang.String extraOffset)

Dump state of this object into XML.

Parameters:

extraOffset - indenting of tags

Returns:

XML state of SubscriptionInfo

toXmlSmall

public java.lang.String toXmlSmall(java.lang.String extraOffset)

Dump state of this object into XML.

 <subscribe id='_subId:1' sessionName='/node/heron/client/joe/-2' oid='HelloWorld' parent='_sub:XPATH-2'/>
 

Parameters:

extraOffset - indenting of tags

Returns:

XML state of SubscriptionInfo

getPersistenceId

public final long getPersistenceId()

Gets the uniqueId for the persistence of this session.

Specified by:

getPersistenceId in interface I_AdminSubscription

Returns:

the uniqueId used to identify this session as an entry in the queue where it is stored (for persistent subscriptions). If the session is not persistent it returns -1L.

setPersistenceId

public final void setPersistenceId(long persistenceId)

Sets the uniqueId used to retrieve this session from the persistence

Parameters:

persistenceId -

getId

public java.lang.String getId()

Description copied from interface: I_AdminSubscription

Access the unique identifier of this subscription.

Specified by:

getId in interface I_AdminSubscription

Returns:

For example "__subId:heron-12334550000"

getSessionName

public java.lang.String getSessionName()

Description copied from interface: I_AdminSubscription

Get the session name of the subscriber.

Specified by:

getSessionName in interface I_AdminSubscription

Returns:

The session name

getTopicId

public java.lang.String getTopicId()

Description copied from interface: I_AdminSubscription

Get the subscribed topic.

Specified by:

getTopicId in interface I_AdminSubscription

Returns:

The topic identifier

getParentSubscription

public java.lang.String getParentSubscription()

Description copied from interface: I_AdminSubscription

Get the parent subscription ID. For example if this subscription is a result of a XPath subscription

Specified by:

getParentSubscription in interface I_AdminSubscription

Returns:

Can be null

getCreationTimestamp

public java.lang.String getCreationTimestamp()

Description copied from interface: I_AdminSubscription

Get the human readable timestamp when this subscription was established.

Specified by:

getCreationTimestamp in interface I_AdminSubscription

Returns:

The date and time of creation

getSubscribeQosStr

public java.lang.String getSubscribeQosStr()

Description copied from interface: I_AdminSubscription

Get the configuration for this subscription.

Specified by:

getSubscribeQosStr in interface I_AdminSubscription

Returns:

The XML dump of the QoS

getSubscribeKeyStr

public java.lang.String getSubscribeKeyStr()

Description copied from interface: I_AdminSubscription

Get the subscription key.

Specified by:

getSubscribeKeyStr in interface I_AdminSubscription

Returns:

The XML dump of the Key

getAccessFilters

public java.lang.String[] getAccessFilters()

Description copied from interface: I_AdminSubscription

Access the filter QoS of this subscription.

Specified by:

getAccessFilters in interface I_AdminSubscription

getDependingSubscriptions

public java.lang.String[] getDependingSubscriptions()

Description copied from interface: I_AdminSubscription

Get my depending subscriptions (childrens), usually caused by an XPATH subscription.

Specified by:

getDependingSubscriptions in interface I_AdminSubscription

Returns:

Array of subscriptionIds

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

getUserObject

public java.lang.Object getUserObject(java.lang.String key,
                                      java.lang.Object defaultValue)

Map to store arbitrary info about the topic to client relation, is cleaned up automatically when unSubscribe happens Useful for example for plugins

hasUserObject

public boolean hasUserObject(java.lang.String key)

setUserObject

public java.lang.Object setUserObject(java.lang.String key,
                                      java.lang.Object value)

The key should use a prefix to not collide with other users / plugins.

Parameters:

key -

value -

Returns:

the previous or null

getUserObjectMap

public java.util.Map<java.lang.String,java.lang.Object> getUserObjectMap()

Use carefully to not harm other plugins.

Returns:

of type Collections.synchronizedMap(new HashMap()