org.xmlBlaster.client
Interface I_XmlBlasterAccess

All Superinterfaces:

I_ConnectionHandler, I_XmlBlaster

All Known Implementing Classes:

XmlBlasterAccess

public interface I_XmlBlasterAccess
extends I_XmlBlaster, I_ConnectionHandler

The Java client side access to xmlBlaster.
This interface hides a remote connection or a native connection to the server.

See Also:

interface requirement

Method Summary

ConnectReturnQos	connect(ConnectQos qos, I_Callback updateListener) Login to xmlBlaster.
SynchronousCache	createSynchronousCache(int size) Setup the cache mode.
boolean	disconnect(DisconnectQos disconnectQos) Logout from the server.
EraseReturnQos[]	erase(EraseKey eraseKey, EraseQos eraseQos)
MsgUnit[]	get(GetKey getKey, GetQos getQos) Get synchronous messages.
MsgUnit[]	getCached(GetKey getKey, GetQos getQos) Access synchronously messages.
I_CallbackServer	getCbServer() Access the callback server which is currently used in I_XmlBlasterAccess.
ConnectQos	getConnectQos() Access the current ConnectQos.
ConnectReturnQos	getConnectReturnQos() Access the returned QoS of a connect() call.
Global	getGlobal() Access the environment settings of this connection.
java.lang.String	getId() A unique name for this client, for logging only
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.
java.lang.String	getStorageIdStr()
java.lang.Object	getUserObject() Can be freely used by client code to store an object and later retrieve it.
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.
boolean	isConnected() Has the connect() method successfully passed?
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	ping() Force a async ping to re-check connection to server.
PublishReturnQos	publish(MsgUnit msgUnit)
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.
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	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	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 xmlQos, 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.
java.lang.String	toXml() Dump state of this client connection handler into an XML ASCII string.
UnSubscribeReturnQos[]	unSubscribe(UnSubscribeKey unSubscribeKey, UnSubscribeQos unSubscribeQos) Cancel subscription.

Methods inherited from interface org.xmlBlaster.client.protocol.I_XmlBlaster

erase, get, publishArr, subscribe, unSubscribe

Methods inherited from interface org.xmlBlaster.client.I_ConnectionHandler

getQueue, getState, isAlive, isDead, isPolling

Method Detail

registerConnectionListener

void registerConnectionListener(I_ConnectionStateListener connectionListener)

Register a listener to get events about connection status changes.

Parameters:

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

See Also:

client.failsafe requirement

registerPostSendListener

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.

A use case is that you want to get the ReturnQos when a message which was queued on client side is finally sent to the server.

Parameters:

postSendListener - The postSendListener to set, pass null to stop the listener

Returns:

the old listener or null if no previous was registered

createSynchronousCache

SynchronousCache createSynchronousCache(int size)

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)

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:

getCached(GetKey, GetQos), client.cache requirement

setClientErrorHandler

void setClientErrorHandler(I_MsgErrorHandler msgErrorHandler)

Use a specific error handler instead of the default one.

Parameters:

msgErrorHandler - Your implementation of the error handler.

See Also:

ClientErrorHandler

connect

ConnectReturnQos connect(ConnectQos qos,
                         I_Callback updateListener)
                         throws XmlBlasterException

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;
 

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:

interface.connect requirement

initCbServer

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

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.

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:

protocol requirement

setCallbackDispatcherActive

void setCallbackDispatcherActive(boolean activate)
                                 throws XmlBlasterException

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.

Parameters:

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

Throws:

XmlBlasterException

sendAdministrativeCommand

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

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.

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

getSecurityPlugin

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

Access the client side security plugin.

See Also:

security.introduction requirement, security.development.serverPlugin.howto requirement

disconnect

boolean disconnect(DisconnectQos disconnectQos)

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.

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:

interface.disconnect requirement

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. 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.

Parameters:

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

isConnected

boolean isConnected()

Has the connect() method successfully passed?

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

Returns:

true If the connection() method was invoked without exception

See Also:

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

refreshSession

void refreshSession()
                    throws XmlBlasterException

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

Throws:

XmlBlasterException - like ErrorCode.USER_NOT_CONNECTED and others

See Also:

session requirement

getConnectReturnQos

ConnectReturnQos getConnectReturnQos()

Access the returned QoS of a connect() call.

Returns:

is null if connect() was not called before

getConnectQos

ConnectQos getConnectQos()

Access the current ConnectQos.

Returns:

is null if connect() was not called before

getCbServer

I_CallbackServer getCbServer()

Access the callback server which is currently used in I_XmlBlasterAccess. The callback server is not null if you have passes a I_Callback handle on connect().

Returns:

null if no callback server is established

See Also:

protocol requirement, connect(ConnectQos, I_Callback)

getId

java.lang.String getId()

A unique name for this client, for logging only

Returns:

e.g. "/node/heron/client/joe/3"

getSessionName

SessionName getSessionName()

The public session ID of this login session. This is a convenience method only, the information is from ConnectReturnQos or if not available from ConnectQos.

Returns:

null if not known

See Also:

client.failsafe requirement

getStorageIdStr

java.lang.String getStorageIdStr()

setStorageIdStr

void setStorageIdStr(java.lang.String prefix)

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!

Parameters:

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

setServerNodeId

void setServerNodeId(java.lang.String nodeId)

Allows to set the node name for nicer logging. Used for clustering.

Parameters:

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

getServerNodeId

java.lang.String getServerNodeId()

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

Needed for creating the unique queue / DB-store name. Is essential if same client loginName and session is used to connect to more the one server.

Needed additionally for nicer logging when running in a cluster.
Is configurable with "-server.node.id golan"

Returns:

e.g. "golan", defaults to "xmlBlaster"

subscribe

SubscribeReturnQos subscribe(SubscribeKey subscribeKey,
                             SubscribeQos subscribeQos)
                             throws XmlBlasterException

Subscribe to messages.

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

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_Callback.update(String, org.xmlBlaster.client.key.UpdateKey, byte[], org.xmlBlaster.client.qos.UpdateQos), interface.subscribe requirement

subscribe

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

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.

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:

interface.subscribe requirement

subscribe

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

Subscribe to messages.

Parameters:

xmlKey - Which message topics to retrieve

xmlQos - 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:

subscribe(SubscribeKey, SubscribeQos, I_Callback)

getCached

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

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.

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

XmlBlasterException - like ErrorCode.USER_NOT_CONNECTED and others

See Also:

createSynchronousCache(int), client.cache requirement

get

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

Get synchronous messages.

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:

interface.get requirement

receive

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

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.

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()

unSubscribe

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

Cancel subscription.

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:

interface.unSubscribe requirement

publish

PublishReturnQos publish(MsgUnit msgUnit)
                         throws XmlBlasterException

Specified by:

publish in interface I_XmlBlaster

Throws:

XmlBlasterException

See Also:

interface.publish requirement

publishOneway

void publishOneway(MsgUnit[] msgUnitArr)
                   throws XmlBlasterException

Publish messages.

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:

interface.publish requirement

publishStream

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

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.

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

request

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

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 receive(String, int, long, boolean))

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:

HelloWorld8.java

erase

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

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:

interface.erase requirement

ping

void ping()

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

getGlobal

Global getGlobal()

Access the environment settings of this connection.

Enforced by interface I_ConnectionHandler

Returns:

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

toXml

java.lang.String toXml()

Dump state of this client connection handler into an XML ASCII string.

Returns:

internal state

getUserObject

java.lang.Object getUserObject()

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

Returns:

the object from setUserObject or null

setUserObject

void setUserObject(java.lang.Object userObject)

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

Parameters:

userObject - any user object