org.xmlBlaster.client
Class XmlBlasterAccess

java.lang.Object
  org.xmlBlaster.client.protocol.AbstractCallbackExtended
      org.xmlBlaster.client.XmlBlasterAccess

All Implemented Interfaces:

I_Callback, I_CallbackExtended, I_CallbackRaw, I_ConnectionHandler, I_ConnectionStatusListener, I_PostSendListener, I_XmlBlaster, I_XmlBlasterAccess, XmlBlasterAccessMBean

public class XmlBlasterAccess

extends AbstractCallbackExtended

implements I_XmlBlasterAccess, I_ConnectionStatusListener, I_PostSendListener, XmlBlasterAccessMBean

This is the default implementation of the java client side remote access to xmlBlaster.

It hides a client side queue, the client side dispatcher framework for polling or pinging the server and some more features.

The interface I_CallbackRaw/I_Callback/I_CallbackExtenden are enforced by AbstractCallbackExtended.

Field Summary

Fields inherited from class org.xmlBlaster.client.protocol.AbstractCallbackExtended

glob, updateBulkAck

Constructor Summary

XmlBlasterAccess(Global glob)
Create an xmlBlaster accessor.

XmlBlasterAccess(java.lang.String[] args)
Create an xmlBlaster accessor.

Method Summary

ConnectReturnQos	connect(ConnectQos qos, I_Callback updateListener) Login to xmlBlaster.
ConnectReturnQos	connect(ConnectQos qos, I_StreamingCallback streamingUpdateListener, boolean withQueue)
SynchronousCache	createSynchronousCache(int size) Setup the cache mode.
PublishReturnQos	createTemporaryTopic(long destroyDelay, int historyMaxMsg)
PublishReturnQos	createTemporaryTopic(TopicProperty topicProperty) Create a temporay topic.
boolean	disconnect(DisconnectQos disconnectQos) Logout from the server.
EraseReturnQos[]	erase(EraseKey eraseKey, EraseQos eraseQos)
EraseReturnQos[]	erase(java.lang.String xmlKey, java.lang.String qos)
MsgUnit[]	get(GetKey getKey, GetQos getQos) Get synchronous messages.
MsgUnit[]	get(java.lang.String xmlKey, java.lang.String qos)
java.lang.String	getBuildJavaVendor() The java vendor of the compiler.
java.lang.String	getBuildJavaVersion() The compiler java version.
java.lang.String	getBuildTimestamp() Returns the date when xmlBlaster client library was compiled.
MsgUnit[]	getCached(GetKey getKey, GetQos getQos) Access synchronously messages.
I_CallbackServer	getCbServer() Access the callback server.
java.lang.String	getConnectionQueueId() Access the unique id of my client side queue.
long	getConnectionQueueMaxMsgs() How many messages are max.
long	getConnectionQueueNumMsgs() How many messages are in this client side queue
java.lang.String	getConnectionState() Get the connection state.
ConnectQos	getConnectQos() Access the current ConnectQos
ConnectReturnQos	getConnectReturnQos() Access the returned QoS of a connect() call.
ContextNode	getContextNode() The unique name of this session instance.
boolean	getDispatcherActive() Access the dispatcher state.
DispatchStatistic	getDispatchStatistic() Access the statistic holder.
FileDumper	getFileDumper()
Global	getGlobal() Access the environment settings of this connection.
java.lang.String	getId() Create a descriptive ME, for logging only
java.lang.String	getLogId() Useful as a logging prefix.
java.lang.String	getLoginDate() Get date when client logged in.
java.lang.String	getLoginName() Access the login name.
long	getNumErase() How many subscribe requests where send by this clients login session
long	getNumGet() How many get requests where send by this clients login session
long	getNumPublish() How many messages where send by this clients login session
long	getNumSubscribe() How many subscribe requests where send by this clients login session
long	getNumUnSubscribe() How many unsubscribe requests where send by this clients login session
long	getNumUpdate() How many messages where received by this clients login session
long	getNumUpdateOneway() How many oneway messages where received by this clients login session
long	getPingRoundTripDelay() Measures the round trip for the last ping() invocation in milli seconds.
static java.lang.String	getPluginUsage(java.lang.String clazzName) Access plugin specific usage()
long	getPublicSessionId() Get the sessions public session id.
I_Queue	getQueue() Enforced by interface I_ConnectionHandler
java.lang.String	getRevisionNumber() Returns the xmlBlaster client library SVN version control revision number.
long	getRoundTripDelay() Measures the round trip for the last remote method invocation in milli seconds.
org.xmlBlaster.authentication.plugins.I_ClientPlugin	getSecurityPlugin() Access the client side security plugin.
java.lang.String	getServerNodeId() The cluster node id (name) to which we want to connect.
SessionName	getSessionName() The public session ID of this login session.
ConnectionStateEnum	getState() Enforced by interface I_ConnectionHandler
java.lang.String	getStorageIdStr()
I_Callback	getUpdateListener() The implementation which receives the callback messages.
long	getUptime() Uptime in seconds
java.lang.String	getVersion() Get the xmlBlaster client library version number.
I_CallbackServer	initCbServer(java.lang.String loginName, CallbackAddress callbackAddress) Create a new instance of the desired protocol driver like CORBA or RMI driver using the plugin loader.
java.lang.String[]	invokeErase(java.lang.String url, java.lang.String qos) JMX
java.lang.String[]	invokeGet(java.lang.String url, java.lang.String qos) JMX
java.lang.String	invokePublish(java.lang.String key, java.lang.String content, java.lang.String qos) JMX
java.lang.String	invokeSubscribe(java.lang.String url, java.lang.String qos) JMX
java.lang.String[]	invokeUnSubscribe(java.lang.String url, java.lang.String qos) JMX
boolean	isAlive() Enforced by interface I_ConnectionHandler
boolean	isCallbackConfigured() Check if a callback was configured, if client has passed a callback address on connect.
boolean	isCallbackDispatcherActive()
boolean	isConnected() Has the connect() method successfully passed?
boolean	isDead() Enforced by interface I_ConnectionHandler
boolean	isPolling() Enforced by interface I_ConnectionHandler
boolean	isShutdown()
void	leaveServer(java.util.Map map) Leaves the connection to the server and cleans up the client side resources without making a server side disconnect.
static void	main(java.lang.String[] args) For testing invoke: java org.xmlBlaster.client.XmlBlasterAccess
java.lang.String[]	peekClientMessages(int numOfEntries) Peek messages from client queue, they are not removed
java.lang.String[]	peekClientMessagesToFile(int numOfEntries, java.lang.String path) Peek messages from client queue and dump them to a file, they are not removed.
void	postSend(MsgQueueEntry[] entries) Called after a messages is send from the client side queue, but not for oneway messages.
PublishReturnQos	publish(MsgUnit msgUnit)
PublishReturnQos[]	publishArr(MsgUnit[] msgUnitArr)
void	publishOneway(MsgUnit[] msgUnitArr) Publish messages.
PublishReturnQos[]	publishStream(java.io.InputStream is, MsgKeyData keyData, MsgQosData qosData, int maxBufSize, I_ReplaceContent contentReplacer) Publishes one message in streaming manner, if the message content is too big to fit in one single chunk, the message is split in several smaller messages (called chunks) and these are published.
MsgUnit[]	receive(java.lang.String oid, int maxEntries, long timeout, boolean consumable) This method synchronously accesses maxEntries messages from any xmlBlaster server side queue.
void	refreshSession() Send an event to xmlBlaster to refresh the login session life time.
void	registerConnectionListener(I_ConnectionStateListener connectionListener) Register a listener to get events about connection status changes.
I_PostSendListener	registerPostSendListener(I_PostSendListener postSendListener) Register a listener to get notifications when a messages is successfully send from the client side tail back queue.
MsgUnit[]	request(MsgUnit msgUnit, long timeout, int maxEntries) Implements the blocking request/reply pattern.
java.lang.String	sendAdministrativeCommand(java.lang.String command) Convenience method to send an administrative command to xmlBlaster.
boolean	sendingFailed(MsgQueueEntry[] entries, XmlBlasterException exception) Called if an asynchronous message is rejected by the server.
void	setCallbackDispatcherActive(boolean activate) Switch callback dispatcher on/off.
void	setClientErrorHandler(I_MsgErrorHandler msgErrorHandler) Use a specific error handler instead of the default one.
void	setDispatcherActive(boolean dispatcherActive) Sets the DispachManager belonging to this session to active or inactive.
void	setServerNodeId(java.lang.String nodeId) Allows to set the node name for nicer logging.
void	setStorageIdStr(java.lang.String prefix) Allows to set a unique client side queue name (connection queue).
void	setUpdateListener(I_Callback updateListener) Register a listener to receive the callback messages.
SubscribeReturnQos	subscribe(java.lang.String xmlKey, java.lang.String qos)
SubscribeReturnQos	subscribe(java.lang.String xmlKey, java.lang.String qos, I_Callback cb) Subscribe to messages.
SubscribeReturnQos	subscribe(SubscribeKey subscribeKey, SubscribeQos subscribeQos) Subscribe to messages.
SubscribeReturnQos	subscribe(SubscribeKey subscribeKey, SubscribeQos subscribeQos, I_Callback cb) This subscribe variant allows to specify a specialized callback for updated messages.
void	toAlive(DispatchManager dispatchManager, ConnectionStateEnum oldState) Call by DispatchManager on connection state transition.
void	toDead(DispatchManager dispatchManager, ConnectionStateEnum oldState, java.lang.String errorText) Call by DispatchManager on connection state transition.
void	toPolling(DispatchManager dispatchManager, ConnectionStateEnum oldState) Call by DispatchManager on connection state transition.
java.lang.String	toXml() Dump state of this object into a XML ASCII string.
java.lang.String	toXml(java.lang.String extraOffset) Dump state of this object into a XML ASCII string.
UnSubscribeReturnQos[]	unSubscribe(java.lang.String xmlKey, java.lang.String qos)
UnSubscribeReturnQos[]	unSubscribe(UnSubscribeKey unSubscribeKey, UnSubscribeQos unSubscribeQos) Cancel subscription.
java.lang.String	update(java.lang.String cbSessionId, UpdateKey updateKey, byte[] content, UpdateQos updateQos) This is the callback method invoked from xmlBlaster delivering us a new asynchronous message.
static java.lang.String	usage(Global glob) Command line usage.

Methods inherited from class org.xmlBlaster.client.protocol.AbstractCallbackExtended

update, update, updateOneway, updateOneway

Methods inherited from class java.lang.Object

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

Constructor Detail

XmlBlasterAccess

public XmlBlasterAccess(Global glob)

Create an xmlBlaster accessor. Please don't create directly but use the factory instead:

   import org.xmlBlaster.util.Global;
   ...
   final Global glob = new Global(args);
   final I_XmlBlasterAccess xmlBlasterAccess = glob.getXmlBlasterAccess();
 

Parameters:

glob - Your environment handle or null to use the default Global.instance() You must use a cloned Global for each XmlBlasterAccess created. engine.Global is not allowed here, only util.Global is supported

Throws:

java.lang.IllegalArgumentException - If engine.Global is used as parameter

XmlBlasterAccess

public XmlBlasterAccess(java.lang.String[] args)

Create an xmlBlaster accessor. Please don't create directly but use the factory instead:

   final Global glob = new Global(args);
   final I_XmlBlasterAccess xmlBlasterAccess = glob.getXmlBlasterAccess();
 

Parameters:

args - Your command line arguments

Method Detail

registerConnectionListener

public void registerConnectionListener(I_ConnectionStateListener connectionListener)

Description copied from interface: I_XmlBlasterAccess

Register a listener to get events about connection status changes.

Specified by:

registerConnectionListener in interface I_XmlBlasterAccess

Parameters:

connectionListener - null or your listener implementation on connection state changes (ALIVE | POLLING | DEAD)

See Also:

I_XmlBlasterAccess.registerConnectionListener(I_ConnectionStateListener)

registerPostSendListener

public final I_PostSendListener registerPostSendListener(I_PostSendListener postSendListener)

Register a listener to get notifications when a messages is successfully send from the client side tail back queue. Max one can be registered, any old one will be overwritten

Specified by:

registerPostSendListener in interface I_XmlBlasterAccess

Parameters:

postSendListener - The postSendListener to set.

Returns:

the old listener or null if no previous was registered

postSend

public final void postSend(MsgQueueEntry[] entries)

Called after a messages is send from the client side queue, but not for oneway messages. Enforced by I_PostSendListener

Specified by:

postSend in interface I_PostSendListener

sendingFailed

public boolean sendingFailed(MsgQueueEntry[] entries,
                             XmlBlasterException exception)

Description copied from interface: I_PostSendListener

Called if an asynchronous message is rejected by the server.

If the server e.g. throws an IllegalArgument back to the client the message will most probably never succeed and retrying to send the message makes no sense. You can intercept this case here and eliminate the message.

ErrorCodes of type "communication.*" are not reported here as the dispatcher framework automatically handles reconnect and retry.

NOTE: For ErrorCodes of type "authentication.*" the connection will go to DEAD and the connection queue entries remain for pubSessionId>0. For pubSessionId<0 (none fail safe) the queue entries are removed (to be implemented TODO).

Specified by:

sendingFailed in interface I_PostSendListener

Parameters:

entries - Each MsgQueueEntry includes the returned QoS

exception - The cause

Returns:

false: We have not handled this case and the dispatcher framework does its default handling. For the client it is just a notification. true: We have processed some error handling and the dispatch framework will remove the message from the queue and continue with sending the next message. This is for example done internally by cluster client plugins inside cluster nodes which will propagate the message to the error handler which emits a dead message. 1. true: Remove msg from queue 2. false: DispatcherActive false 3. toDead (remove all messages) -> you call disconnect() 4. ErrorCode.authenticate.* -> leaveServer() for pubSessionId>0 and call I_ConnectionStateListener.toDead else toDead (removes all queue entries)

getFileDumper

public FileDumper getFileDumper()
                         throws XmlBlasterException

Throws:

XmlBlasterException

createSynchronousCache

public SynchronousCache createSynchronousCache(int size)

Description copied from interface: I_XmlBlasterAccess

Setup the cache mode.

This installs a cache. When you call get(), a subscribe() is done in the background that we always have a current value in our client side cache. Further get() calls retrieve the value from the client cache.

Only the first call is used to setup the cache, following calls are ignored silently (and return the original handle)

Specified by:

createSynchronousCache in interface I_XmlBlasterAccess

Parameters:

size - Size of the cache. This number specifies the count of subscriptions the cache can hold. It specifies NOT the number of messages.

Returns:

The cache handle, usually of no interest

See Also:

I_XmlBlasterAccess.getCached(GetKey, GetQos), client.cache requirement

setClientErrorHandler

public void setClientErrorHandler(I_MsgErrorHandler msgErrorHandler)

Description copied from interface: I_XmlBlasterAccess

Use a specific error handler instead of the default one.

Specified by:

setClientErrorHandler in interface I_XmlBlasterAccess

Parameters:

msgErrorHandler - Your implementation of the error handler.

See Also:

ClientErrorHandler

getConnectionQueueId

public java.lang.String getConnectionQueueId()

Description copied from interface: XmlBlasterAccessMBean

Access the unique id of my client side queue.

Specified by:

getConnectionQueueId in interface XmlBlasterAccessMBean

Returns:

For example "connection:SUB17692784598"

getContextNode

public final ContextNode getContextNode()

The unique name of this session instance.

Returns:

Never null, for example "/xmlBlaster/node/heron/client/joe/session/-2"

connect

public ConnectReturnQos connect(ConnectQos qos,
                                I_StreamingCallback streamingUpdateListener,
                                boolean withQueue)
                         throws XmlBlasterException

Throws:

XmlBlasterException

connect

public ConnectReturnQos connect(ConnectQos qos,
                                I_Callback updateListener)
                         throws XmlBlasterException

Description copied from interface: I_XmlBlasterAccess

Login to xmlBlaster.

Connecting with the default configuration (which checks xmlBlaster.properties and your command line arguments):

  import org.xmlBlaster.util.Global;
  ...
  I_XmlBlasterAccess xmlBlasterAccess = glob.getXmlBlasterAccess();
  xmlBlasterAccess.connect(null, null);
 

The default behavior is to poll automatically for the server if it is not found. As we have not specified a listener for returned messages from the server there is no callback server created.

This example shows how to configure different behavior:

  // Example how to configure fail safe settings
  ConnectQos connectQos = new ConnectQos(glob);

  Address address = new Address(glob);
  address.setDelay(4000L);      // retry connecting every 4 sec
  address.setRetries(-1);       // -1 == forever
  address.setPingInterval(0L);  // switched off
  addr.setType("SOCKET");       // don't use CORBA protocol, but use SOCKET instead

  connectQos.setAddress(address);

  CallbackAddress cbAddress = new CallbackAddress(glob);
  cbAddress.setDelay(4000L);      // retry connecting every 4 sec
  cbAddress.setRetries(-1);       // -1 == forever
  cbAddress.setPingInterval(4000L); // ping every 4 seconds
  connectQos.addCallbackAddress(cbAddress);

  xmlBlasterAccess.connect(connectQos, new I_Callback() {

     public String update(String cbSessionId, UpdateKey updateKey, byte[] content,
                          UpdateQos updateQos) {
        if (updateKey.isInternal()) {
           return "";
        }
        if (updateQos.isErased()) {
           return "";
        }
        log.info(ME, "Receiving asynchronous message '" + updateKey.getOid() +
                     "' state=" + updateQos.getState() + " in default handler");
        return "";
     }

  });  // Login to xmlBlaster, default handler for updates;
 

Specified by:

connect in interface I_XmlBlasterAccess

Parameters:

qos - Your configuration desire

updateListener - If not null a callback server will be created and callback messages will be routed to your updateListener.update() method.

Returns:

Can only be null if '-dispatch/connection/doSendConnect false' was set

Throws:

XmlBlasterException - only if connection state is DEAD, typically thrown on wrong configurations. You must call connect again with different settings.

See Also:

I_XmlBlasterAccess.connect(ConnectQos, I_Callback)

isConnected

public boolean isConnected()

Description copied from interface: I_XmlBlasterAccess

Has the connect() method successfully passed?

Note that this contains no information about the current connection state of the protocol layer.

Specified by:

isConnected in interface I_XmlBlasterAccess

Returns:

true If the connection() method was invoked without exception

See Also:

I_ConnectionHandler.isAlive(), I_ConnectionHandler.isPolling(), I_ConnectionHandler.isDead()

refreshSession

public void refreshSession()
                    throws XmlBlasterException

Description copied from interface: I_XmlBlasterAccess

Send an event to xmlBlaster to refresh the login session life time.

Specified by:

refreshSession in interface I_XmlBlasterAccess

Throws:

XmlBlasterException - like ErrorCode.USER_NOT_CONNECTED and others

See Also:

I_XmlBlasterAccess.refreshSession()

initCbServer

public I_CallbackServer initCbServer(java.lang.String loginName,
                                     CallbackAddress callbackAddress)
                              throws XmlBlasterException

Description copied from interface: I_XmlBlasterAccess

Create a new instance of the desired protocol driver like CORBA or RMI driver using the plugin loader.

Note that the returned instance is of your control only, we don't cache it in any way, this method is only a helper hiding the plugin loading.

Specified by:

initCbServer in interface I_XmlBlasterAccess

Parameters:

loginName - A nice name for logging purposes

callbackAddress - The callback address configuration, contains for example type like "IOR" or "RMI" and version of the driver, e.g. "1.0"

Throws:

XmlBlasterException

See Also:

I_XmlBlasterAccess.initCbServer(String, CallbackAddress)

getSecurityPlugin

public org.xmlBlaster.authentication.plugins.I_ClientPlugin getSecurityPlugin()

Description copied from interface: I_XmlBlasterAccess

Access the client side security plugin.

Specified by:

getSecurityPlugin in interface I_XmlBlasterAccess

Specified by:

getSecurityPlugin in class AbstractCallbackExtended

disconnect

public boolean disconnect(DisconnectQos disconnectQos)

Description copied from interface: I_XmlBlasterAccess

Logout from the server.

Behavior on client side:
Destroys pending tail back messages in the client queue and destroys low level connection and callback server. You can customize the behavior with disconnectQos.

Behavior on server side:
The server side session resources are destroyed, pending messages are deleted.

NOTE: If you want to keep all resources on server side for this login session but want to halt your client, shutdown the callback server with leaveServer(null) and throw the xmlBlasterAccess instance away. This is often the case if the client disappears and at a later point wants to reconnect. On server side the queue for this session remains alive and collects messages.

If '-dispatch/connection/doSendConnect false' was set call disconnect() nevertheless to cleanup client side resources.

Specified by:

disconnect in interface I_XmlBlasterAccess

Parameters:

disconnectQos - Describe the desired behavior on disconnect

Returns:

false if connect() wasn't called before or if you call disconnect() multiple times

See Also:

I_XmlBlasterAccess.disconnect(DisconnectQos), interface.disconnect requirement

leaveServer

public void leaveServer(java.util.Map map)

Description copied from interface: I_XmlBlasterAccess

Leaves the connection to the server and cleans up the client side resources without making a server side disconnect. This way the client side persistent messages are kept in queue while transient ones are lost. If you want to delete also the persistent messages you have to do it manually.

As the login session on server side stays alive, all subscriptions stay valid and callback messages are queued by the server. If you connect at a later time the server sends us all queued messages.

Once you have called this method the I_XmlBlasterAccess becomes invalid and any further invocation results in an XmlBlasterException to be thrown.

Specified by:

leaveServer in interface I_XmlBlasterAccess

Parameters:

map - The properties to pass while leaving server. Currently this argument has no effect. You can pass null as a parameter.

See Also:

I_XmlBlasterAccess.leaveServer(Map)

isShutdown

public boolean isShutdown()

Returns:

true if shutdown was called, typically by disconnect()

getCbServer

public I_CallbackServer getCbServer()

Access the callback server.

Specified by:

getCbServer in interface I_XmlBlasterAccess

Returns:

null if no callback server is established

See Also:

protocol requirement, I_XmlBlasterAccess.connect(ConnectQos, I_Callback)

getId

public java.lang.String getId()

Create a descriptive ME, for logging only

Specified by:

getId in interface I_XmlBlasterAccess

Returns:

e.g. "/node/heron/client/joe/3" or "UNKNOWN_SESSION" if connect() was not successful

getLogId

public java.lang.String getLogId()

Useful as a logging prefix.

Returns:

For example "client/TheDesperate/-6: "

getSessionName

public SessionName getSessionName()

The public session ID of this login session.

Specified by:

getSessionName in interface I_XmlBlasterAccess

Returns:

null if not known

See Also:

client.failsafe requirement

getStorageIdStr

public java.lang.String getStorageIdStr()

Specified by:

getStorageIdStr in interface I_XmlBlasterAccess

See Also:

I_XmlBlasterAccess.getStorageIdStr()

setStorageIdStr

public void setStorageIdStr(java.lang.String prefix)

Description copied from interface: I_XmlBlasterAccess

Allows to set a unique client side queue name (connection queue). Useful only if you code connects to multiple servers with the same login name. Use with very caution to be unique in complete database!

Specified by:

setStorageIdStr in interface I_XmlBlasterAccess

Parameters:

prefix - For example "toserver1"+sessionName.getRelativeName()

See Also:

I_XmlBlasterAccess.setStorageIdStr(String)

setServerNodeId

public void setServerNodeId(java.lang.String nodeId)

Allows to set the node name for nicer logging. Typically used by cluster clients and not by ordinary clients

Specified by:

setServerNodeId in interface I_XmlBlasterAccess

Parameters:

nodeId - For example "/xmlBlaster/node/heron"

getServerNodeId

public java.lang.String getServerNodeId()

The cluster node id (name) to which we want to connect.

Needed only for nicer logging when running in a cluster.
Is configurable with "-server.node.id golan" until a successful connect

Specified by:

getServerNodeId in interface I_XmlBlasterAccess

Returns:

e.g. "/node/golan" or /xmlBlaster/node/heron"

subscribe

public SubscribeReturnQos subscribe(java.lang.String xmlKey,
                                    java.lang.String qos)
                             throws XmlBlasterException

Specified by:

subscribe in interface I_XmlBlaster

Throws:

XmlBlasterException

See Also:

I_XmlBlasterAccess.subscribe(SubscribeKey, SubscribeQos)

subscribe

public SubscribeReturnQos subscribe(SubscribeKey subscribeKey,
                                    SubscribeQos subscribeQos)
                             throws XmlBlasterException

Description copied from interface: I_XmlBlasterAccess

Subscribe to messages.

The messages are delivered asynchronous with the update() method.

Specified by:

subscribe in interface I_XmlBlasterAccess

Parameters:

subscribeKey - Which message topics to retrieve

subscribeQos - Control the behavior and further filter messages with mime based filter plugins

Returns:

Is never null

Throws:

XmlBlasterException - like ErrorCode.USER_NOT_CONNECTED and others

See Also:

I_XmlBlasterAccess.subscribe(SubscribeKey, SubscribeQos)

subscribe

public SubscribeReturnQos subscribe(java.lang.String xmlKey,
                                    java.lang.String qos,
                                    I_Callback cb)
                             throws XmlBlasterException

Description copied from interface: I_XmlBlasterAccess

Subscribe to messages.

Specified by:

subscribe in interface I_XmlBlasterAccess

Parameters:

xmlKey - Which message topics to retrieve

qos - Control the behavior and further filter messages with mime based filter plugins

Returns:

is never null

Throws:

XmlBlasterException - like ErrorCode.USER_NOT_CONNECTED and others

See Also:

I_XmlBlasterAccess.subscribe(SubscribeKey, SubscribeQos, I_Callback)

subscribe

public SubscribeReturnQos subscribe(SubscribeKey subscribeKey,
                                    SubscribeQos subscribeQos,
                                    I_Callback cb)
                             throws XmlBlasterException

Description copied from interface: I_XmlBlasterAccess

This subscribe variant allows to specify a specialized callback for updated messages.

This way you can implement for every subscription a specific callback, so you don't need to dispatch updates when they are received in only one central update method.

Example:

   XmlBlasterAccess con = ...   // login etc.
   ...
   SubscribeKey key = new SubscribeKey(glob, "//stock", "XPATH");
   SubscribeQos qos = new SubscribeQos(glob);
   try {
      con.subscribe(key, qos, new I_Callback() {
            public String update(String name, UpdateKey updateKey, byte[] content, UpdateQos updateQos) {
               System.out.println("Receiving message for '//stock' subscription ...");
               return "";
            }
         });
   } catch(XmlBlasterException e) {
      System.out.println(e.getMessage());
   }
 

NOTE: You need to pass a callback handle on login as well (even if you never use it). It allows to setup the callback server and is the default callback deliver channel for PtP messages.

NOTE: On logout we automatically unSubscribe() this subscription if not done before.

Specified by:

subscribe in interface I_XmlBlasterAccess

Parameters:

cb - Your callback handling implementation

Returns:

SubscribeReturnQos with the unique subscriptionId
If you subscribed using a query, the subscription ID of this
query handling object (SubscriptionInfo.getUniqueKey()) is returned.
You should use this ID if you wish to unSubscribe() Is never null

Throws:

XmlBlasterException - like ErrorCode.USER_NOT_CONNECTED and others

See Also:

I_XmlBlasterAccess.subscribe(SubscribeKey, SubscribeQos, I_Callback)

get

public MsgUnit[] get(java.lang.String xmlKey,
                     java.lang.String qos)
              throws XmlBlasterException

Specified by:

get in interface I_XmlBlaster

Throws:

XmlBlasterException

See Also:

I_XmlBlasterAccess.get(GetKey, GetQos)

getCached

public MsgUnit[] getCached(GetKey getKey,
                           GetQos getQos)
                    throws XmlBlasterException

Description copied from interface: I_XmlBlasterAccess

Access synchronously messages. They are on first request subscribed and cached on client side.

A typical use case is a servlet which receives many HTML requests and usually the message has not changed. This way we avoid asking xmlBlaster every time for the information but take it directly from the cache.

The cache is always up to date as it has subscribed on this topic

You need to call createSynchronousCache() before using getCached().

NOTE: Passing two similar getKey but with different getQos filters is currently not supported.

NOTE: GetKey requests with EXACT oid are automatically removed from cache when the topic with this oid is erased. XPATH queries are removed from cache when the last topic oid which matched the XPATH disappears.

Specified by:

getCached in interface I_XmlBlasterAccess

Parameters:

getKey - Which message topics to retrieve

getQos - Control the behavior and further filter messages with mime based filter plugins

Returns:

An array of messages, the sequence is arbitrary, never null

Throws:

XmlBlasterException - like ErrorCode.USER_NOT_CONNECTED and others

See Also:

I_XmlBlasterAccess.getCached(GetKey, GetQos)

get

public MsgUnit[] get(GetKey getKey,
                     GetQos getQos)
              throws XmlBlasterException

Description copied from interface: I_XmlBlasterAccess

Get synchronous messages.

Specified by:

get in interface I_XmlBlasterAccess

Parameters:

getKey - Which message topics to retrieve

getQos - Control the behavior and further filter messages with mime based filter plugins

Returns:

never null

Throws:

XmlBlasterException - like ErrorCode.USER_NOT_CONNECTED and others

See Also:

I_XmlBlasterAccess.get(GetKey, GetQos)

unSubscribe

public UnSubscribeReturnQos[] unSubscribe(UnSubscribeKey unSubscribeKey,
                                          UnSubscribeQos unSubscribeQos)
                                   throws XmlBlasterException

Description copied from interface: I_XmlBlasterAccess

Cancel subscription.

Specified by:

unSubscribe in interface I_XmlBlasterAccess

Parameters:

unSubscribeKey - Which messages to cancel

unSubscribeQos - Control the behavior

Returns:

The status of the unSubscribe request, is never null

Throws:

XmlBlasterException - like ErrorCode.USER_NOT_CONNECTED and others

See Also:

I_XmlBlasterAccess.unSubscribe(UnSubscribeKey, UnSubscribeQos)

unSubscribe

public UnSubscribeReturnQos[] unSubscribe(java.lang.String xmlKey,
                                          java.lang.String qos)
                                   throws XmlBlasterException

Specified by:

unSubscribe in interface I_XmlBlaster

Throws:

XmlBlasterException

See Also:

I_XmlBlasterAccess.unSubscribe(UnSubscribeKey, UnSubscribeQos)

publish

public PublishReturnQos publish(MsgUnit msgUnit)
                         throws XmlBlasterException

Specified by:

publish in interface I_XmlBlasterAccess

Throws:

XmlBlasterException

See Also:

I_XmlBlasterAccess.publish(MsgUnit)

publishOneway

public void publishOneway(MsgUnit[] msgUnitArr)
                   throws XmlBlasterException

Description copied from interface: I_XmlBlasterAccess

Publish messages.

Specified by:

publishOneway in interface I_XmlBlasterAccess

Parameters:

msgUnitArr - The messages to send to the server

Throws:

XmlBlasterException - like ErrorCode.USER_NOT_CONNECTED and others

See Also:

I_XmlBlasterAccess.publishOneway(MsgUnit[])

publishArr

public PublishReturnQos[] publishArr(MsgUnit[] msgUnitArr)
                              throws XmlBlasterException

Specified by:

publishArr in interface I_XmlBlaster

Throws:

XmlBlasterException

erase

public EraseReturnQos[] erase(EraseKey eraseKey,
                              EraseQos eraseQos)
                       throws XmlBlasterException

Specified by:

erase in interface I_XmlBlasterAccess

Parameters:

eraseKey - The topics to erase

eraseQos - Control the erase behavior

Returns:

The status of the erase request, is never null

Throws:

XmlBlasterException - like ErrorCode.USER_NOT_CONNECTED and others

See Also:

I_XmlBlasterAccess.erase(EraseKey, EraseQos)

erase

public EraseReturnQos[] erase(java.lang.String xmlKey,
                              java.lang.String qos)
                       throws XmlBlasterException

Specified by:

erase in interface I_XmlBlaster

Throws:

XmlBlasterException

See Also:

I_XmlBlasterAccess.erase(EraseKey, EraseQos)

update

public java.lang.String update(java.lang.String cbSessionId,
                               UpdateKey updateKey,
                               byte[] content,
                               UpdateQos updateQos)
                        throws XmlBlasterException

This is the callback method invoked from xmlBlaster delivering us a new asynchronous message.

Specified by:

update in interface I_Callback

Specified by:

update in class AbstractCallbackExtended

Parameters:

cbSessionId - The session ID specified by the client which registered the callback

updateKey - The arrived key (as an xml-string)

content - The arrived message content

updateQos - Quality of Service of the MsgUnitRaw as an xml-string

Throws:

XmlBlasterException

See Also:

I_Callback.update(String, UpdateKey, byte[], UpdateQos)

toAlive

public void toAlive(DispatchManager dispatchManager,
                    ConnectionStateEnum oldState)

Call by DispatchManager on connection state transition.

Enforced by interface I_ConnectionStatusListener

Specified by:

toAlive in interface I_ConnectionStatusListener

toPolling

public void toPolling(DispatchManager dispatchManager,
                      ConnectionStateEnum oldState)

Call by DispatchManager on connection state transition.

Enforced by interface I_ConnectionStatusListener

Specified by:

toPolling in interface I_ConnectionStatusListener

toDead

public void toDead(DispatchManager dispatchManager,
                   ConnectionStateEnum oldState,
                   java.lang.String errorText)

Call by DispatchManager on connection state transition.

Enforced by interface I_ConnectionStatusListener

Specified by:

toDead in interface I_ConnectionStatusListener

getGlobal

public Global getGlobal()

Access the environment settings of this connection.

Enforced by interface I_XmlBlasterAccess

Specified by:

getGlobal in interface I_XmlBlasterAccess

Returns:

The global handle (like a stack with local variables for this connection)

getQueue

public I_Queue getQueue()

Enforced by interface I_ConnectionHandler

Specified by:

getQueue in interface