* 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;
*
* @param qos Your configuration desire
* @param updateListener If not null a callback server will be created and
* callback messages will be routed to your updateListener.update() method.
* @return 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 interface.connect requirement
*/
ConnectReturnQos connect(ConnectQos qos, I_Callback updateListener) 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. *
* @param loginName A nice name for logging purposes * @param callbackAddress The callback address configuration, contains for example * type like "IOR" or "RMI" and version of the driver, e.g. "1.0" * @see protocol requirement */ I_CallbackServer initCbServer(String loginName, CallbackAddress callbackAddress) 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. * @param activate true: XmlBlaster server delivers callback messages * false: XmlBlaster server keeps messages for this client in the callback queue */ void setCallbackDispatcherActive(boolean activate) 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. * @param 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" * @return When setting a value you get the returned state, else the retrieved data * @throws XmlBlasterException on problems */ String sendAdministrativeCommand(String command) throws XmlBlasterException; /** * Access the client side security plugin. * @see security.introduction requirement * @see security.development.serverPlugin.howto requirement */ I_ClientPlugin getSecurityPlugin(); /** * Logout from the server. * * Behavior on client side: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.
* @param disconnectQos Describe the desired behavior on disconnect
* @return false if connect() wasn't called before or if you call disconnect() multiple times
* @see interface.disconnect requirement
*/
boolean disconnect(DisconnectQos disconnectQos);
/**
* 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. *
* * @param map The properties to pass while leaving server. * Currently this argument has no effect. You can * pass null as a parameter. */ void leaveServer(Map map); /** * Has the connect() method successfully passed? ** Note that this contains no information about the current connection state * of the protocol layer. *
* @return true If the connection() method was invoked without exception * @see I_ConnectionHandler#isAlive() * @see I_ConnectionHandler#isPolling() * @see I_ConnectionHandler#isDead() */ boolean isConnected(); /** * Send an event to xmlBlaster to refresh the login session life time. * @see session requirement * @throws XmlBlasterException like ErrorCode.USER_NOT_CONNECTED and others */ void refreshSession() throws XmlBlasterException; /** * Access the returned QoS of a connect() call. * @return is null if connect() was not called before */ ConnectReturnQos getConnectReturnQos(); /** * Access the current ConnectQos. * @return is null if connect() was not called before */ ConnectQos getConnectQos(); /** * 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(). * @return null if no callback server is established * @see protocol requirement * @see #connect(ConnectQos, I_Callback) */ I_CallbackServer getCbServer(); /** * A unique name for this client, for logging only * @return e.g. "/node/heron/client/joe/3" */ String getId(); /** * 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. * @return null if not known * @see client.failsafe requirement */ SessionName getSessionName(); String getStorageIdStr(); /** * 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! * @param prefix For example "toserver1"+sessionName.getRelativeName() */ void setStorageIdStr(String prefix); /** * Allows to set the node name for nicer logging. * Used for clustering. * @param nodeId For example "/xmlBlaster/node/heron" */ void setServerNodeId(String nodeId); /** * 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.* The messages are delivered asynchronous with the update() method. *
* @param subscribeKey Which message topics to retrieve * @param subscribeQos Control the behavior and further filter messages with mime based filter plugins * @return Is never null * @see org.xmlBlaster.client.I_Callback#update(String, org.xmlBlaster.client.key.UpdateKey, byte[], org.xmlBlaster.client.qos.UpdateQos) * @see interface.subscribe requirement * @throws XmlBlasterException like ErrorCode.USER_NOT_CONNECTED and others */ SubscribeReturnQos subscribe(SubscribeKey subscribeKey, SubscribeQos subscribeQos) 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.
* @param cb Your callback handling implementation
* @return SubscribeReturnQos with the unique subscriptionId* 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. *
* @param getKey Which message topics to retrieve * @param getQos Control the behavior and further filter messages with mime based filter plugins * @return An array of messages, the sequence is arbitrary, never null * @throws XmlBlasterException if createSynchronousCache() was not used to establish a cache first * @see #createSynchronousCache(int) * @see client.cache requirement * @throws XmlBlasterException like ErrorCode.USER_NOT_CONNECTED and others */ public MsgUnit[] getCached(GetKey getKey, GetQos getQos) throws XmlBlasterException; //MsgUnit[] get(java.lang.String xmlKey, java.lang.String qos) throws XmlBlasterException; /** * Get synchronous messages. * @param getKey Which message topics to retrieve * @param getQos Control the behavior and further filter messages with mime based filter plugins * @return never null * @see interface.get requirement * @throws XmlBlasterException like ErrorCode.USER_NOT_CONNECTED and others */ MsgUnit[] get(GetKey getKey, GetQos getQos) throws XmlBlasterException; // @param maxBytes The total size of all returned messages together must not exceed this value. // This is not implemented yet since the size of the entries in the queue is not guaranteed // to be related to the size of the MsgUnits //RELATING_CALLBACK = "callback"; //RELATING_SUBJECT = "subject"; //RELATING_HISTORY = "history"; /** * 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.
*
* 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 * {@link #receive(String, int, long, boolean)}) * * @param 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). * @param timeout The milliseconds to block, 0 is none blocking, -1 blocks forever * @param maxEntries The maximum number of entries to deliver or return with less after timeout * @return The response messages, typically one, never null, has 0 entries on timeout * @see HelloWorld8.java */ MsgUnit[] request(MsgUnit msgUnit, long timeout, int maxEntries) throws XmlBlasterException; //EraseReturnQos[] erase(java.lang.String xmlKey, java.lang.String qos) throws XmlBlasterException; /** * @param eraseKey The topics to erase * @param eraseQos Control the erase behavior * @return The status of the erase request, is never null * @see interface.erase requirement * @throws XmlBlasterException like ErrorCode.USER_NOT_CONNECTED and others */ EraseReturnQos[] erase(EraseKey eraseKey, EraseQos eraseQos) throws XmlBlasterException; /** * Force a async ping to re-check connection to server. Status change can be * got asynchronously via registerConnectionListener() */ public void ping(); /** * Access the environment settings of this connection. *
* Enforced by interface I_ConnectionHandler *
* * @return The global handle (like a stack with local variables for this * connection) */ Global getGlobal(); /** * Dump state of this client connection handler into an XML ASCII string. * @return internal state */ String toXml(); /** * Can be freely used by client code to store an object and later retrieve * it. * * @return the object from setUserObject or null */ public Object getUserObject(); /** * Can be freely used by client code to store an object and later retrieve * it. * * @param userObject * any user object */ public void setUserObject(Object userObject); }