XmlBlasterAccess (xmlBlaster 2.2.0 client API)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

xmlBlaster 2.2.0 client API

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.xmlBlaster.client
Class XmlBlasterAccess

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

All Implemented Interfaces:: I_Callback, I_CallbackRaw, I_ConnectionHandler, I_XmlBlasterAccess, I_CallbackExtended, I_XmlBlaster, XmlBlasterAccessMBean, I_ConnectionStatusListener, I_PostSendListener

public class XmlBlasterAccess
extends AbstractCallbackExtended
implements I_XmlBlasterAccess, I_ConnectionStatusListener, I_PostSendListener, XmlBlasterAccessMBean
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)`
`StorageId`	`createStorageId(java.lang.String relating)` The storageId must remain the same after a client restart
`SynchronousCache`	`createSynchronousCache(int size)` Setup the cache mode.
`PublishReturnQos`	`createTemporaryTopic(long destroyDelay, int historyMaxMsg)`
`PublishReturnQos`	`createTemporaryTopic(java.lang.String uniqueTopicId, long destroyDelay, int historyMaxMsg)`
`PublishReturnQos`	`createTemporaryTopic(TopicProperty topicProperty)` Create a temporay topic.
`boolean`	`disconnect(DisconnectQos disconnectQos)` Logout from the server.
`java.lang.String`	`disconnect(java.lang.String disconnectQos)`
`EraseReturnQos[]`	`erase(EraseKey eraseKey, EraseQos eraseQos)`
`EraseReturnQos[]`	`erase(java.lang.String xmlKey, java.lang.String qos)`
`boolean`	`forcePollingForTesting()`
`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()`
`XmlBlasterException`	`getToDeadXmlBlasterException()` Workaround to transport the reason for the toDead() transition as the interface {@link I_ConnectionStateListener#reachedDead(ConnectionStateEnum, I_XmlBlasterAccess) is missing to pass the exception to the client.
`I_Callback`	`getUpdateListener()` The implementation which receives the callback messages.
`long`	`getUptime()` Uptime in seconds
`java.lang.Object`	`getUserObject()` Can be freely used by client code to store an object and later retrieve it.
`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()`
`java.lang.String`	`leaveServer()`
`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.
`void`	`lostConnection(XmlBlasterException xmlBlasterException)` For example called by SOCKET layer (SocketCallbackImpl.java) on EOF.
`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`	`ping()` Force a async ping to re-check connection to server.
`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.
`void`	`setUserObject(java.lang.Object userObject)` Can be freely used by client code to store an object and later retrieve it.
`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(I_DispatchManager dispatchManager, ConnectionStateEnum oldState)` Call by DispatchManager on connection state transition.
`void`	`toAliveSync(I_DispatchManager dispatchManager, ConnectionStateEnum oldState)`
`void`	`toDead(I_DispatchManager dispatchManager, ConnectionStateEnum oldState, XmlBlasterException xmlBlasterException)` Call by DispatchManager on connection state transition.
`void`	`toPolling(I_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

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

Parameters:: msgQueueEntry, - includes the returned QoS (e.g. PublisReturnQos)

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"

forcePollingForTesting

public boolean forcePollingForTesting()

Specified by:: forcePollingForTesting in interface XmlBlasterAccessMBean

connect

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

Throws:: XmlBlasterException

createStorageId

public StorageId createStorageId(java.lang.String relating)

The storageId must remain the same after a client restart

Parameters:: relating - xbType like Constants.RELATING_CLIENT
Returns:

connect

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

Description copied from interface: I_XmlBlasterAccess

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
Specified by:: refreshSession in interface XmlBlasterAccessMBean

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

See Also:: security.introduction requirement, security.development.serverPlugin.howto requirement

disconnect

public java.lang.String disconnect(java.lang.String disconnectQos)

Specified by:: disconnect in interface XmlBlasterAccessMBean

See Also:: XmlBlasterAccessMBean.disconnect(String)

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 java.lang.String leaveServer()

Specified by:: leaveServer in interface XmlBlasterAccessMBean

See Also:: XmlBlasterAccessMBean.leaveServer()

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
Specified by:: getId in interface XmlBlasterAccessMBean

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:: serverNodeId - For example "/node/heron/instanceId/1233435" or "/node/heron"

getServerNodeId

public java.lang.String getServerNodeId()

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

Needed for client queue storage identifier. see: setStorageIdStr()

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
Specified by:: getServerNodeId in interface XmlBlasterAccessMBean

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

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)

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)

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)

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

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 - if createSynchronousCache() was not used to establish a cache first
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
Specified by:: publish in interface I_XmlBlaster

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
Specified by:: publishOneway in interface I_XmlBlaster

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)

lostConnection

public void lostConnection(XmlBlasterException xmlBlasterException)

For example called by SOCKET layer (SocketCallbackImpl.java) on EOF. Does immediate ping to go to polling mode

Specified by:: lostConnection in interface I_CallbackExtended

Parameters:: xmlBlasterException -
See Also:: org.xmlBlaster.client.I_CallbackExtended#lostConnection(XmlBlasterException)

ping

public void ping()

Force a async ping to re-check connection to server. Status change can be got asynchronously via registerConnectionListener()

Specified by:: ping in interface I_XmlBlasterAccess

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(I_DispatchManager dispatchManager,
                    ConnectionStateEnum oldState)

Call by DispatchManager on connection state transition.

Enforced by interface I_ConnectionStatusListener

Specified by:: toAlive in interface I_ConnectionStatusListener

toAliveSync

public void toAliveSync(I_DispatchManager dispatchManager,
                        ConnectionStateEnum oldState)

Specified by:: toAliveSync in interface I_ConnectionStatusListener

toPolling

public void toPolling(I_DispatchManager dispatchManager,
                      ConnectionStateEnum oldState)

Call by DispatchManager on connection state transition.

Enforced by interface I_ConnectionStatusListener

Specified by:: toPolling in interface I_ConnectionStatusListener

getToDeadXmlBlasterException

public XmlBlasterException getToDeadXmlBlasterException()

Workaround to transport the reason for the toDead() transition as the interface {@link I_ConnectionStateListener#reachedDead(ConnectionStateEnum, I_XmlBlasterAccess) is missing to pass the exception to the client.

Currently the client needs a downcast to XmlBlasterAccess (not in I_XmlBlasterAccess)

Returns:: Can be null

toDead

public void toDead(I_DispatchManager dispatchManager,
                   ConnectionStateEnum oldState,
                   XmlBlasterException xmlBlasterException)

Call by DispatchManager on connection state transition.

Enforced by interface I_ConnectionStatusListener

Specified by:: toDead in interface I_ConnectionStatusListener

xmlBlasterException - Can be null

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 I_ConnectionHandler

Returns:: The queue used to store tailback messages.

getState

public ConnectionStateEnum getState()

Enforced by interface I_ConnectionHandler

Specified by:: getState in interface I_ConnectionHandler

Returns:: The current state of the connection

getConnectionState

public java.lang.String getConnectionState()

Get the connection state. String version for JMX access.

Specified by:: getConnectionState in interface XmlBlasterAccessMBean

Returns:: "UNDEF", "ALIVE", "POLLING", "DEAD"

isAlive

public boolean isAlive()

Enforced by interface I_ConnectionHandler

Specified by:: isAlive in interface I_ConnectionHandler

Returns:: true if the connection to xmlBlaster is operational

isPolling

public boolean isPolling()

Enforced by interface I_ConnectionHandler

Specified by:: isPolling in interface I_ConnectionHandler

Returns:: true if we are polling for the server

isDead

public boolean isDead()

Enforced by interface I_ConnectionHandler

Specified by:: isDead in interface I_ConnectionHandler

Returns:: true if we have definitely lost the connection to xmlBlaster and gave up

getConnectReturnQos

public ConnectReturnQos getConnectReturnQos()

Access the returned QoS of a connect() call.

Enforced by interface I_XmlBlasterAccess

Specified by:: getConnectReturnQos in interface I_XmlBlasterAccess

Returns:: Can be null if not connected

getConnectQos

public ConnectQos getConnectQos()

Access the current ConnectQos

Enforced by interface I_XmlBlasterAccess

Specified by:: getConnectQos in interface I_XmlBlasterAccess

Returns:: Can be null if not connected

getDispatchStatistic

public final DispatchStatistic getDispatchStatistic()

Description copied from class: AbstractCallbackExtended

Access the statistic holder. Implementing classes should provide a valid statistic handle.

Overrides:: getDispatchStatistic in class AbstractCallbackExtended

Returns:: null if no callback is configured

getLoginName

public final java.lang.String getLoginName()

Access the login name.

Specified by:: getLoginName in interface XmlBlasterAccessMBean

Returns:: your login name or null if you are not logged in

isCallbackConfigured

public final boolean isCallbackConfigured()

Description copied from interface: XmlBlasterAccessMBean

Check if a callback was configured, if client has passed a callback address on connect.

Specified by:: isCallbackConfigured in interface XmlBlasterAccessMBean

Returns:: true if a callback is configured

getUptime

public final long getUptime()

Description copied from interface: XmlBlasterAccessMBean

Uptime in seconds

Specified by:: getUptime in interface XmlBlasterAccessMBean

getLoginDate

public final java.lang.String getLoginDate()

Description copied from interface: XmlBlasterAccessMBean

Get date when client logged in.

Specified by:: getLoginDate in interface XmlBlasterAccessMBean

Returns:: For example "2005-07-25 12:34:16.79"

getPublicSessionId

public final long getPublicSessionId()

Description copied from interface: XmlBlasterAccessMBean

Get the sessions public session id.

Specified by:: getPublicSessionId in interface XmlBlasterAccessMBean

Returns:: For example -1

getNumPublish

public final long getNumPublish()

Description copied from interface: XmlBlasterAccessMBean

How many messages where send by this clients login session

Specified by:: getNumPublish in interface XmlBlasterAccessMBean

getNumSubscribe

public final long getNumSubscribe()

Description copied from interface: XmlBlasterAccessMBean

How many subscribe requests where send by this clients login session

Specified by:: getNumSubscribe in interface XmlBlasterAccessMBean

getNumUnSubscribe

public final long getNumUnSubscribe()

Description copied from interface: XmlBlasterAccessMBean

How many unsubscribe requests where send by this clients login session

Specified by:: getNumUnSubscribe in interface XmlBlasterAccessMBean

getNumGet

public final long getNumGet()

Description copied from interface: XmlBlasterAccessMBean

How many get requests where send by this clients login session

Specified by:: getNumGet in interface XmlBlasterAccessMBean

getNumErase

public final long getNumErase()

Description copied from interface: XmlBlasterAccessMBean

How many subscribe requests where send by this clients login session

Specified by:: getNumErase in interface XmlBlasterAccessMBean

getNumUpdateOneway

public final long getNumUpdateOneway()

Description copied from interface: XmlBlasterAccessMBean

How many oneway messages where received by this clients login session

Specified by:: getNumUpdateOneway in interface XmlBlasterAccessMBean

getNumUpdate

public final long getNumUpdate()

Description copied from interface: XmlBlasterAccessMBean

How many messages where received by this clients login session

Specified by:: getNumUpdate in interface XmlBlasterAccessMBean

getConnectionQueueNumMsgs

public final long getConnectionQueueNumMsgs()

Description copied from interface: XmlBlasterAccessMBean

How many messages are in this client side queue

Specified by:: getConnectionQueueNumMsgs in interface XmlBlasterAccessMBean

getConnectionQueueMaxMsgs

public final long getConnectionQueueMaxMsgs()

Description copied from interface: XmlBlasterAccessMBean

How many messages are max. allowed in this client side queue

Specified by:: getConnectionQueueMaxMsgs in interface XmlBlasterAccessMBean

getPingRoundTripDelay

public final long getPingRoundTripDelay()

Description copied from interface: XmlBlasterAccessMBean

Measures the round trip for the last ping() invocation in milli seconds.

Specified by:: getPingRoundTripDelay in interface XmlBlasterAccessMBean

Returns:: Returns the pingRoundTripDelay.

getRoundTripDelay

public final long getRoundTripDelay()

Description copied from interface: XmlBlasterAccessMBean

Measures the round trip for the last remote method invocation in milli seconds. For example update(), publish(), subscribe()

Specified by:: getRoundTripDelay in interface XmlBlasterAccessMBean

Returns:: Returns the roundTripDelay.

invokePublish

public java.lang.String invokePublish(java.lang.String key,
                                      java.lang.String content,
                                      java.lang.String qos)
                               throws java.lang.Exception

JMX

Specified by:: invokePublish in interface XmlBlasterAccessMBean

Parameters:: key - The publish key (e.g. <key oid="Hello"><South/></key>); qos - The qos XML string (e.g. "" or "<qos><persistent/></qos>")
Returns:: The status string
Throws:: java.lang.Exception

invokeUnSubscribe

public java.lang.String[] invokeUnSubscribe(java.lang.String url,
                                            java.lang.String qos)
                                     throws java.lang.Exception

JMX

Specified by:: invokeUnSubscribe in interface XmlBlasterAccessMBean

Parameters:: url - The topic oid/xpath to unSubscribe (e.g. "Hello" or "xpath://key"); qos - The qos XML string (e.g. "" or "")
Returns:: The status string
Throws:: java.lang.Exception

invokeSubscribe

public java.lang.String invokeSubscribe(java.lang.String url,
                                        java.lang.String qos)
                                 throws java.lang.Exception

JMX

Specified by:: invokeSubscribe in interface XmlBlasterAccessMBean

Parameters:: url - The topic oid/xpath to subscribe (e.g. "Hello" or "xpath://key"); qos - The qos XML string (e.g. "" or "")
Returns:: The status string
Throws:: java.lang.Exception

invokeGet

public java.lang.String[] invokeGet(java.lang.String url,
                                    java.lang.String qos)
                             throws java.lang.Exception

JMX

Specified by:: invokeGet in interface XmlBlasterAccessMBean

Parameters:: url - The topic oid/xpath to retrieve (e.g. "Hello" or "xpath://key"); qos - The qos XML string (e.g. "" or "")
Returns:: The status string
Throws:: java.lang.Exception

invokeErase

public java.lang.String[] invokeErase(java.lang.String url,
                                      java.lang.String qos)
                               throws java.lang.Exception

JMX

Specified by:: invokeErase in interface XmlBlasterAccessMBean

Parameters:: url - The topic oid/xpath to erase (e.g. "Hello" or "xpath://key"); qos - The qos XML string (e.g. "" or "")
Returns:: The status string
Throws:: java.lang.Exception

setDispatcherActive

public void setDispatcherActive(boolean dispatcherActive)

Sets the DispachManager belonging to this session to active or inactive. It is initially active. Setting it to false temporarly inhibits dispatch of messages which are in the callback queue. Setting it to true starts the dispatch again.

Specified by:: setDispatcherActive in interface XmlBlasterAccessMBean

Parameters:: dispatchActive -

getDispatcherActive

public boolean getDispatcherActive()

Description copied from interface: XmlBlasterAccessMBean

Access the dispatcher state.

Specified by:: getDispatcherActive in interface XmlBlasterAccessMBean

Returns:: true if the dispatcher is currently able to dispatch asyncronously

setCallbackDispatcherActive

public void setCallbackDispatcherActive(boolean activate)
                                 throws XmlBlasterException

Description copied from interface: I_XmlBlasterAccess

Switch callback dispatcher on/off. This is a convenience function (see ConnectQos). It will update the client side ConnectQos as well so we don't loose the setting on reconnects after server maintenance.

Specified by:: setCallbackDispatcherActive in interface I_XmlBlasterAccess

Parameters:: activate - true: XmlBlaster server delivers callback messages false: XmlBlaster server keeps messages for this client in the callback queue
Throws:: XmlBlasterException

isCallbackDispatcherActive

public boolean isCallbackDispatcherActive()
                                   throws XmlBlasterException

Throws:: XmlBlasterException

sendAdministrativeCommand

public java.lang.String sendAdministrativeCommand(java.lang.String command)
                                           throws XmlBlasterException

Description copied from interface: I_XmlBlasterAccess

Convenience method to send an administrative command to xmlBlaster. If the command contains a '=' it is interpreted as a set() call, else it is used as a get() call.

Specified by:: sendAdministrativeCommand in interface I_XmlBlasterAccess

Parameters:: command - for example "client/joe/?dispatcherActive" (a getter) or "client/joe/?dispatcherActive=false" (a setter). The "__cmd:" is added by us To enforce a getter or setter you can write "get client/joe/?dispatcherActive" or "set client/joe/?dispatcherActive=false"
Returns:: When setting a value you get the returned state, else the retrieved data
Throws:: XmlBlasterException - on problems

peekClientMessages

public java.lang.String[] peekClientMessages(int numOfEntries)
                                      throws java.lang.Exception

Description copied from interface: XmlBlasterAccessMBean

Peek messages from client queue, they are not removed

Specified by:: peekClientMessages in interface XmlBlasterAccessMBean

Parameters:: numOfEntries - The number of messages to peek, taken from the front
Returns:: The dump of the messages
Throws:: java.lang.Exception

peekClientMessagesToFile

public java.lang.String[] peekClientMessagesToFile(int numOfEntries,
                                                   java.lang.String path)
                                            throws java.lang.Exception

Peek messages from client queue and dump them to a file, they are not removed.

Specified by:: peekClientMessagesToFile in interface XmlBlasterAccessMBean

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 file names of the dumped messages
Throws:: java.lang.Exception

usage

public static java.lang.String usage(Global glob)

Command line usage.

getPluginUsage

public static java.lang.String getPluginUsage(java.lang.String clazzName)

Access plugin specific usage()

Returns:: if plugin is not in CLASSPATH return empty string

toXml

public final java.lang.String toXml()

Dump state of this object into a XML ASCII string.

Specified by:: toXml in interface I_XmlBlasterAccess

Returns:: internal state of SubjectInfo as a XML ASCII string

toXml

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

Dump state of this object into a XML ASCII string.

Parameters:: extraOffset - indenting of tags for nice output
Returns:: internal state of SubjectInfo as a XML ASCII string

main

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

For testing invoke: java org.xmlBlaster.client.XmlBlasterAccess

getUpdateListener

public I_Callback getUpdateListener()

The implementation which receives the callback messages.

Returns:: Returns the updateListener or null if none was registered

setUpdateListener

public void setUpdateListener(I_Callback updateListener)

Register a listener to receive the callback messages.
Note: Usually you don't need to call this method directly as you should pass your callback listener with connect().

Parameters:: updateListener - The updateListener to set.

getVersion

public java.lang.String getVersion()

Description copied from interface: XmlBlasterAccessMBean

Get the xmlBlaster client library version number.

Specified by:: getVersion in interface XmlBlasterAccessMBean

Returns:: For example "1.0.4"

getRevisionNumber

public java.lang.String getRevisionNumber()

Description copied from interface: XmlBlasterAccessMBean

Returns the xmlBlaster client library SVN version control revision number.

Specified by:: getRevisionNumber in interface XmlBlasterAccessMBean

Returns:: The subversion revision number of the monitored instance, for example "13593"

getBuildTimestamp

public java.lang.String getBuildTimestamp()

Description copied from interface: XmlBlasterAccessMBean

Returns the date when xmlBlaster client library was compiled.

Specified by:: getBuildTimestamp in interface XmlBlasterAccessMBean

Returns:: For example "07/28/2005 03:47 PM"

getBuildJavaVendor

public java.lang.String getBuildJavaVendor()

Description copied from interface: XmlBlasterAccessMBean

The java vendor of the compiler.

Specified by:: getBuildJavaVendor in interface XmlBlasterAccessMBean

Returns:: For example "Sun Microsystems Inc."

getBuildJavaVersion

public java.lang.String getBuildJavaVersion()

Description copied from interface: XmlBlasterAccessMBean

The compiler java version.

Specified by:: getBuildJavaVersion in interface XmlBlasterAccessMBean

Returns:: For example "1.5.0"

createTemporaryTopic

public PublishReturnQos createTemporaryTopic(TopicProperty topicProperty)
                                      throws XmlBlasterException

Create a temporay topic. You need to erase it yourself when not needed anymore

Parameters:: topicProperty - Can be null (the default is no DOM entry)
Returns:: The details about the created, temporary topic
Throws:: XmlBlasterException

createTemporaryTopic

public PublishReturnQos createTemporaryTopic(long destroyDelay,
                                             int historyMaxMsg)
                                      throws XmlBlasterException

Throws:: XmlBlasterException

createTemporaryTopic

public PublishReturnQos createTemporaryTopic(java.lang.String uniqueTopicId,
                                             long destroyDelay,
                                             int historyMaxMsg)
                                      throws XmlBlasterException

Parameters:: uniqueTopicId - Usually null, can be used to force a topicId. e.g. topicIdPrefix="device.joe.request" -> the topic is something like "device.joe.request135823058558"; destroyDelay -; historyMaxMsg -
Returns:
Throws:: XmlBlasterException

request

public MsgUnit[] request(MsgUnit msgUnit,
                         long timeout,
                         int maxEntries)
                  throws XmlBlasterException

Description copied from interface: I_XmlBlasterAccess

Implements the blocking request/reply pattern.

The msgUnit should contain a PublishQos which routes the request to the desired client, for example sending it to client joe and its login session 1 or sending it to a topic which was subscribed by the destination client:

 import org.xmlBlaster.util.qos.address.Destination;
 import org.xmlBlaster.client.qos.PublishQos;
  ...
  Global glob = ...;
  ...
  PublishQos pq = new PublishQos(glob);
  Destination dest = new Destination(glob, new SessionName(glob, "joe/1"));
  dest.forceQueuing(true);
  pq.addDestination(dest);

This receiver needs to send the response to the topic oid as passed with the client property "__jms:JMSReplyTo":

  String tempTopicOid = updateQos.getClientProperty(Constants.JMS_REPLY_TO, "");
  // Send reply back ...
  PublishKey pk = new PublishKey(glob, tempTopicOid);
  ...

This approach is similar to the JMS approach for request/reply (TopicRequestor.java) but we have the choice to send the msgUnit directly to another client or to a topic (as JMS), and we can handle multiple replies for one request.

The feature is implemented on client side with a temporary response topic and a receive() call. The temporary response topic is erased after the response has arrived.
You can optionally add a clientProperty "__responseTopicIdPrefix", this topicId is used as a prefix for the temporary response topicId. the given prefix must be unique between clients. This is thread safe. A use case could be to simplify detecting the topic for an authorizer plugin.
You can optionally add a clientProperty "__responseTopicId" with a unique topicId to avoid the creation of temporary response topics, note that this feature is NOT thread safe, the client may only send one request() at a time. The response topic will live for one day after last usage. A reason to do so could be the better performance (avoid short living temporary response topics).

Please note the timeout limitation as described at I_XmlBlasterAccess.receive(String, int, long, boolean))

Specified by:: request in interface I_XmlBlasterAccess

Parameters:: msgUnit - The request to send. The topicId may be any you wish for the receiver to recognize. If the receiver has not subsribed on this topicId you need to send it PtP (add the Destination client).; timeout - The milliseconds to block, 0 is none blocking, -1 blocks forever; maxEntries - The maximum number of entries to deliver or return with less after timeout
Returns:: The response messages, typically one, never null, has 0 entries on timeout
Throws:: XmlBlasterException
See Also:: org.xmlBlaster.test.client.TestRequestResponse

receive

public MsgUnit[] receive(java.lang.String oid,
                         int maxEntries,
                         long timeout,
                         boolean consumable)
                  throws XmlBlasterException

Description copied from interface: I_XmlBlasterAccess

This method synchronously accesses maxEntries messages from any xmlBlaster server side queue.

This is a convenience method which uses get() with a specific Qos.

Important note:
Currently you shouldn't use unlimited timeout==-1 as this could lead to a server side thread leak on client disconnect. As a workaround please use a loop and a timeout of for example 60000 and just ignore returned arrays of length 0.

Specified by:: receive in interface I_XmlBlasterAccess

Parameters:: oid - The identifier like "topic/hello" to access a history queue, "client/joe" to access a subject queue or "client/joe/session/1" to access a callback queue. The string must follow the formatting rule of ContextNode.java; maxEntries - The maximum number of entries to retrieve; timeout - The time to wait until return. If you choose a negative value it will block until the maxEntries has been reached. If the value is '0' (i.e. zero) it will not wait and will correspond to a non-blocking get. If the value is positive it will block until the specified amount in milliseconds has elapsed or when the maxEntries has been reached (whichever comes first).; consumable - Expressed with 'true' or 'false'. If true the entries returned are deleted from the queue
Returns:: An array of messages, is never null but may be an array of length=0 if no message is delivered
Throws:: XmlBlasterException
See Also:: ContextNode, engine.qos.queryspec.QueueQuery requirement, MessageConsumer.receive()

publishStream

public PublishReturnQos[] publishStream(java.io.InputStream is,
                                        MsgKeyData keyData,
                                        MsgQosData qosData,
                                        int maxBufSize,
                                        I_ReplaceContent contentReplacer)
                                 throws XmlBlasterException

Description copied from interface: I_XmlBlasterAccess

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. During the publishing of these messages, the method blocks.

Specified by:: publishStream in interface I_XmlBlasterAccess

Parameters:: is - The input stream from which to read the input data.; keyData - The key for the message (same for all chunks); qosData - The qos for all messages (same for all chunks besides internal stuff added in this method); maxBufSize - The maximum content size of each chunk.; contentReplacer - an optional content replacer (i.e. a modifier of the content) can be null.
Returns:: an array containing the return qos. Currently an array of length 1 is returned containing the return qos for the first message.
Throws:: XmlBlasterException

getUserObject

public java.lang.Object getUserObject()

Description copied from interface: I_XmlBlasterAccess

Can be freely used by client code to store an object and later retrieve it.

Specified by:: getUserObject in interface I_XmlBlasterAccess

Returns:: the object from setUserObject or null

setUserObject

public void setUserObject(java.lang.Object userObject)

Description copied from interface: I_XmlBlasterAccess

Can be freely used by client code to store an object and later retrieve it.

Specified by:: setUserObject in interface I_XmlBlasterAccess

Parameters:: userObject - any user object

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

xmlBlaster 2.2.0 client API

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.xmlBlaster.client Class XmlBlasterAccess

XmlBlasterAccess

XmlBlasterAccess

registerConnectionListener

registerPostSendListener

postSend

sendingFailed

getFileDumper

createSynchronousCache

setClientErrorHandler

getConnectionQueueId

getContextNode

forcePollingForTesting

connect

createStorageId

connect

isConnected

refreshSession

initCbServer

getSecurityPlugin

disconnect

disconnect

leaveServer

leaveServer

isShutdown

getCbServer

getId

getLogId

getSessionName

getStorageIdStr

setStorageIdStr

setServerNodeId

getServerNodeId

subscribe

subscribe

subscribe

subscribe

get

getCached

get

unSubscribe

unSubscribe

publish

publishOneway

publishArr

erase

erase

lostConnection

ping

update

toAlive

toAliveSync

toPolling

getToDeadXmlBlasterException

toDead

getGlobal

getQueue

getState

getConnectionState

isAlive

isPolling

isDead

getConnectReturnQos

getConnectQos

getDispatchStatistic

getLoginName

isCallbackConfigured

getUptime

getLoginDate

getPublicSessionId

getNumPublish

getNumSubscribe

getNumUnSubscribe

getNumGet

getNumErase

getNumUpdateOneway

getNumUpdate

getConnectionQueueNumMsgs

getConnectionQueueMaxMsgs

getPingRoundTripDelay

org.xmlBlaster.client
Class XmlBlasterAccess