xmlBlaster 2.2.0 client API

org.xmlBlaster.client.qos
Class SubscribeQos

java.lang.Object
  extended by 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


xmlBlaster 2.2.0 client API

Copyright © 1999-2014 The xmlBlaster.org contributers.