org.xmlBlaster.client.qos
Class SubscribeQos

java.lang.Object
  org.xmlBlaster.client.qos.SubscribeQos

public final class SubscribeQos
extends java.lang.Object

This class encapsulates the QoS (quality of service) of a subscribe() request.

A full specified subscribe qos could look like this:

<qos>
   <id>__subId:/node/heron/client/joe/3/34</id> < Force a subscription ID from client side -->
   <meta>false</meta>       <!-- Don't send me the xmlKey meta data on updates -->
   <content>false</content> <!-- Don't send me the content data on updates (notify only) -->
   <multiSubscribe>false</multiSubscribe> <!-- Ignore a second subscribe on same oid or XPATH -->
   <local>false</local>     <!-- Inhibit the delivery of messages to myself if i have published it -->
   <initialUpdate>false</initialUpdate>;
   <filter type='myPlugin' version='1.0'>a!=100</filter>
                                  <!-- Filters messages i have subscribed as implemented in your plugin -->
   <history numEntries='20'/>  <!-- Default is to deliver the current entry (numEntries='1'), '-1' deliver all -->
</qos>
 

see xmlBlaster/src/dtd/XmlQoS.xml

See Also:

QueryQosData, QueryQosSaxFactory, subscribe interface, MIME access filter requirement

Constructor Summary

SubscribeQos(Global glob)
Constructor for default qos (quality of service).

SubscribeQos(Global glob, QueryQosData queryQosData)
Constructor for internal use.

Method Summary

void	addAccessFilter(AccessFilterQos filter) Adds your supplied subscribe filter.
void	addClientProperty(java.lang.String key, java.lang.Object value) Sets a client property (an application specific property) to the given value
void	addQuerySpec(QuerySpecQos querySpec) Adds your supplied get querySpec.
java.lang.Object	clone() Returns a deep clone, you can change savely all basic or immutable types like boolean, String, int and also the ClientProperties and RouteInfo.
ClientProperty	getClientProperty(java.lang.String key) Read back a property.
QueryQosData	getData() Access the wrapped data holder.
boolean	getPersistent() Gets the persistent flag for this subscription.
static void	main(java.lang.String[] args) For testing: java org.xmlBlaster.client.qos.SubscribeQos
void	setHistoryQos(HistoryQos historyQos) Query historical messages.
void	setMultiSubscribe(boolean multiSubscribe) Are multiple subscribes allowed? Defaults to true.
void	setNewestOnly(boolean newestOnly) if __newestOnly client property is true remove older instances from callback queue of client
void	setPersistent(boolean persistent) Mark the subscription request to be persistent.
void	setSubscriptionId(java.lang.String subId) Force the identifier (unique handle) for this subscription.
void	setWantContent(boolean content) If false, the update contains not the content (it is a notify of change only) This may be useful if you have huge contents, and you only want to be informed about a change TODO: Implement in server!!!
void	setWantInitialUpdate(boolean initialUpdate) Do we want to have an initial update on subscribe if the message exists already? Defaults to true.
void	setWantLocal(boolean local) false Inhibit the delivery of messages to myself if i have published it.
void	setWantNotify(boolean notify) If set to true (which is default) an erase notification message is sent to the subscriber when the topic is erased.
void	setWantUpdateOneway(boolean updateOneway) Do we want the callback messages of this subscription as oneway with updateOneway() or with the acknowledged update().
java.lang.String	toString() Converts the data into a valid XML ASCII string.
java.lang.String	toXml() Converts the data into a valid XML ASCII string.

Methods inherited from class java.lang.Object

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

Constructor Detail

SubscribeQos

public SubscribeQos(Global glob)

Constructor for default qos (quality of service).

SubscribeQos

public SubscribeQos(Global glob,
                    QueryQosData queryQosData)

Constructor for internal use.

Parameters:

queryQosData - The struct holding the data

Method Detail

getData

public QueryQosData getData()

Access the wrapped data holder.

Returns:

is never null

setSubscriptionId

public void setSubscriptionId(java.lang.String subId)

Force the identifier (unique handle) for this subscription. Usually you let the identifier be generated by xmlBlaster, it is done automatically for clients with publicSessionId > 0 and multiSubscribe=false, example: '__subId:client/subscriber/session/1-exact:PublishToSlave.RUGBY_NEWS' This is routed properly in cluster environment.

Parameters:

subId - Must follow the syntax "__subId:" followed by your relative sessionName followed by a unique postfix token for example "__subId:client/joe/session/1-[your-unqiue-postfix]"

See Also:

The engine.qos.subscribe.id requirement, QueryQosData.setSubscriptionId(String)

setMultiSubscribe

public void setMultiSubscribe(boolean multiSubscribe)

Are multiple subscribes allowed? Defaults to true.

setWantInitialUpdate

public void setWantInitialUpdate(boolean initialUpdate)

Do we want to have an initial update on subscribe if the message exists already? Defaults to true.

Parameters:

initialUpdate - true if initial update wanted false if only updates on new publishes are sent

See Also:

The engine.qos.subscribe.initialUpdate requirement, QueryQosData.setWantInitialUpdate(boolean)

setWantUpdateOneway

public void setWantUpdateOneway(boolean updateOneway)

Do we want the callback messages of this subscription as oneway with updateOneway() or with the acknowledged update().

Parameters:

updateOneway - Defaults to false.

See Also:

The interface.subscribe requirement, QueryQosData.setWantUpdateOneway(boolean)

setWantLocal

public void setWantLocal(boolean local)

false Inhibit the delivery of messages to myself if i have published it. Defaults to true.

See Also:

QueryQosData.setWantLocal(boolean)

setWantContent

public void setWantContent(boolean content)

If false, the update contains not the content (it is a notify of change only)

This may be useful if you have huge contents, and you only want to be informed about a change TODO: Implement in server!!!

See Also:

QueryQosData.setWantContent(boolean)

setWantNotify

public void setWantNotify(boolean notify)

If set to true (which is default) an erase notification message is sent to the subscriber when the topic is erased.
Note: For exact subscriptions this subscription gets invalid when the topic is erased and you need to subscribe again. For XPath subscriptions the subscription remains, if the same topic is created again the Xpath will match and renew the subscription.
The state in the message QoS is set to Constants.STATE_ERASED="ERASED"

Parameters:

notify - true - notify subscriber when the topic is erased (default is true)

addAccessFilter

public void addAccessFilter(AccessFilterQos filter)

Adds your supplied subscribe filter. The access filter plugin requirement

addQuerySpec

public void addQuerySpec(QuerySpecQos querySpec)

Adds your supplied get querySpec. The query plugin requirement

setHistoryQos

public void setHistoryQos(HistoryQos historyQos)

Query historical messages.

addClientProperty

public void addClientProperty(java.lang.String key,
                              java.lang.Object value)

Sets a client property (an application specific property) to the given value

Parameters:

key -

value -

getClientProperty

public ClientProperty getClientProperty(java.lang.String key)

Read back a property.

Returns:

The client property or null if not found

setPersistent

public void setPersistent(boolean persistent)

Mark the subscription request to be persistent.

Sets the persistent flag for this subscription. If this flag is set, the subscription will persist a server crash.

Parameters:

persistent -

getPersistent

public boolean getPersistent()

Gets the persistent flag for this subscription. If this flag is set, the subscription will persist a server crash.

Returns:

true if persistent false otherwise.

setNewestOnly

public void setNewestOnly(boolean newestOnly)

if __newestOnly client property is true remove older instances from callback queue of client

toString

public java.lang.String toString()

Converts the data into a valid XML ASCII string.

Overrides:

toString in class java.lang.Object

Returns:

An XML ASCII string

toXml

public java.lang.String toXml()

Converts the data into a valid XML ASCII string.

Returns:

An XML ASCII string

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Returns a deep clone, you can change savely all basic or immutable types like boolean, String, int and also the ClientProperties and RouteInfo.

Overrides:

clone in class java.lang.Object

Throws:

java.lang.CloneNotSupportedException

main

public static void main(java.lang.String[] args)

For testing: java org.xmlBlaster.client.qos.SubscribeQos