XmlBlaster Logo

REQUIREMENT

interface.connect

XmlBlaster Logo


Type NEW
Priority HIGH
Status CLOSED
Topic Connecting to xmlBlaster
Des
cription

The connect() method allows to login to xmlBlaster.

Method detail (CORBA IDL notation): 

typedef string XmlType;

serverIdl::XmlType connect(in serverIdl::XmlType qos)
                           raises (serverIdl::XmlBlasterException);
ParameterTypeDescription
qosstringThe XML encoded Quality of Service (QoS), see ConnectQos link below.
returnstringAn XML based return string containing status and other informations, see ConnectReturnQos link below.
XmlBlasterExceptionexceptionThrown on error.
Example
XML

Here is an example connect QoS which is send when a client connects to xmlBlaster: 

<qos>

   <securityService type='htpasswd' version='1.0'>
     <![CDATA[
     <user>michele</user>
     <passwd>secret</passwd>
     ]]>
   </securityService>

   <session name='joe/3' timeout='3600000' maxSessions='10'
               clearSessions='false' reconnectSameClientOnly='false'/>

   <!-- Recoverable session after server crash / restart -->
   <persistent/>

   <ptp>true</ptp>

   <duplicateUpdates>false</duplicateUpdates>

   <!-- Setting to control client side behavior, used for cluster configuration -->
   <queue relating='connection' maxEntries='10000000' maxEntriesCache='1000'>
      <address type='IOR' bootstrapPort='7600' dispatchPlugin='undef'/>
   </queue>

   <!-- Configure the server side subject queue (one for each login name) -->
   <queue relating='subject' type='CACHE' version='1.0'
             maxEntries='5000' maxBytes='1000000'
             maxEntriesCache='100' maxBytesCache='100000'
             onOverflow='deadMessage'/>

   <!-- Configure the server side callback queue (one for each login session) -->
   <queue relating='callback' maxEntries='1000' maxBytes='4000000'
                                                   onOverflow='deadMessage'>
      <callback type='IOR' sessionId='4e56890ghdFzj0' pingInterval='10000'
          retries='-1' delay='10000' oneway='false' dispatcherActive='true' dispatchPlugin='undef'>
         IOR:10000010033200000099000010....
         <burstMode collectTime='400' maxEntries='20' maxBytes='-1' />
         <compress type='gzip' minSize='3000'/> <!-- only implemented for SOCKET protocol -->
         <ptp>true</ptp>
         <attribute name='key1' type='int'>2005</attribute>
      </callback>
   </queue>

   <!-- a client specific property: here it could be the bean to invoke on updates -->
   <clientProperty name='onMessageDefault'>beanName</clientProperty>

</qos>
ParameterDescription
<securityService>

The <securityService> allows to choose the authentication plugin and delivers the credentials as expected by the plugin. Here it is a simple password based approach.

<session>

In the above example we use the <session> tag to configure our login session. We login to xmlBlaster as user joe. Additionally we have specified to use the public session identifier 3 (this is optionally). Sending this pubSessionId allows us to reconnect to the session 3 at any time later. This is useful for example if the client has crashed or the client stops and later wants to reconnect and find the same state as before (all subscriptions remain and the callback queue has stored messages during client-downtime).

After timeout=3600000 milliseconds (which is one day) of inactivity our login session dies automatically and all resources like the callback queue are garbage collected. The session lasts forever if timeout is set to 0. Please read the requirement engine.qos.login.session about the definition of 'inactivity'.

The user joe can login most ten times, as specified with maxSessions='10'.

For administrative purposes we can set clearSessions='true' which will destroy all other login sessions of joe.

Setting reconnectSameClientOnly='true' would only allow the client which is the creator of a session to reconnect to a session. See requirement client.configuration for more details.

<ptp>

This allows to suppress receiving PtP messages

<duplicateUpdates>

If a client subscribes to the same topic multiple times it will receive multiple updates of the same message. Setting duplicateUpdates to false will suppress multiple subscribes on the same topic to deliver the same message only once. Note that this setting does not support XPath subscriptions.
This setting does reference counting, you need as many unSubscribe() calls as you did subscribe() calls before.
This configuration is deprecated and will probably be removed in a future version as the subscribe QoS specific 'multiSubscribe' setting has more functionality and is specific for each subscribe(), see requirement engine.qos.subscribe.multiSubscribe for more details.

<queue>

This markup allows to configure how our callback queue looks like. Further the inner <callback> tag allows us to pass the address of our client side callback server. In the above example we use CORBA to receive callbacks.

oneway

Setting the oneway attribute to true forces all callback invocations to use the higher performing updateOneway() method call instead of the more reliable update(). We recommend to use the updateOneway setting from the subscribe QoS to configure this only for well chosen subscriptions (see requirement interface.subscribe).

dispatcherActive

Setting the dispatcherActive attribute to false inhibits all callback invocations. You can use this to avoid receiving messages directly after login. When all your client side initialization is done you need to manually activate the callback dispatcher with a administrative command, for example with telnet 

 set client/receiver/1/?dispatcherActive=true
or a command message 
__cmd:client/receiver/1/?dispatcherActive=true
This setting defaults to true.

<burstMode>

The <burstMode collectTime='0' maxEntries='-1' maxBytes='-1' /> settings in the callback section controls how xmlBlaster delivers the callback messages to its subscribers - or the PtP messages to the destination clients.
collectTime The default setting above does not wait on more messages after one has arrived (collectTime=0) and delivers it immediately. You can for example change this to wait some 20 milliseconds and then send those in a bulk for higher performance.
maxEntries When xmlBlaster checks the callback queue for a client it takes out all messages in the RAM queue with the highest priority and sends them in a bulk to the client. This guarantees good performance but may have drawbacks in some use cases. For example if the client is behind a slow dial up line and the callback queue contains 60 messages with same priority and a size of 1MByte each the client has to wait until the complete 60MByte has arrived. If he switches off his PC after getting 59MByte the complete bulk is considered as not delivered by xmlBlaster and will be redilvered after the client logs in again. In such cases setting maxEntries=1 is a good choice.
maxBytes The maximum bytes to collect for a bulk send. Usually you leave this on unlimited and play with maxEntries. At least one message will be delivered even if it is bigger than maxBytes.

persistence

Once you have made a session persistent (see engine.persistence.session) and you are reconnecting, the new connection will ignore the persistent flag. Once made persistent, the session will remain persistent.

clientProperty

Optional clientProperties can be added to the ConnectQos to send other configuration informations to xmlBlaster. Currently none are predefined.

It is possible to send remoteProperties on login with the ConnectQos clientProperties. If you add an additional clientProperty
<clientProperty name='__remoteProperties'>true</clientProperty>
to the ConnectQos, all other clientProperties are copied to the remoteProperties map.
The remoteProperties are useful for observing the remote status of connected clients. Clients can publish their status to xmlBlaster and this status can be observed by the EventPlugin framework. For example a client can choose to send its error logging to xmlBlaster or other fatal situations like low memory or lost database connections. The remoteProperties are available with JMX, so you can easily observe or manipulate them with the jconsole. For a description on how to publish further remoteProperties please see the admin.events requirement.

clientProperty response

The ConnectReturnQos delivers you a client property with the server side timestamp, this can be useful for mobile devices to set the time. The format is ISO 8601 compliant and delivers the UTC time. Expect the precision to be in milliseconds or nanoseconds like "2007-07-09 10:35:43.946Z" or "2007-07-09 10:36:38.180000005Z": 

<clientProperty name='__rcvTimestampStr'>2007-07-09 10:53:29.340000001Z</clientProperty>
Example
XML

Here is an example for the return QoS of a connect invocation which is returned from the server to the client on successful login. 

<qos>

   <securityService type="htpasswd" version="1.0">
     <![CDATA[
     <user>michele</user>
     <passwd>secret</passwd>
     ]]>
   </securityService>

   <session name='joe/3'  
               timeout='3600000'
               maxSessions='10'
               clearSessions='false'
               sessionId='4e56890ghdFzj0'/>

   <!-- Has the client reconnected to an existing session? -->
   <reconnected>false</reconnected>

   <queue relating='callback' maxEntries='1000' maxBytes='4000000'
                                                   onOverflow='deadMessage'>
      <callback type='IOR' sessionId='4e56890ghdFzj0'>
         IOR:10000010033200000099000010....
         <burstMode collectTime='400' />
      </callback>
   </queue>

</qos>

This is more or less a copy of the sent connect QoS but with some added information.

Especially the secret sessionId is returned which has to be used for further requests (not for CORBA which handles this under the cover).

Example
XmlRpc

This is the XmlRpc server interface variant: 

public String connect(String qos_literal) throws XmlBlasterException
Example
RMI

This is the RMI server interface variant: 

public String connect(String qos_literal)
                        throws RemoteException, XmlBlasterException
Example
email

Example of an email based login

   <connect>
     <qos>
       <securityService type="htpasswd" version="1.0">
         <user>joe</user>
         <passwd>secret</passwd>
       </securityService>
       <persistent>true</persistent>
       <session name='joe/1' timeout='0' reconnectSameClientOnly='false'/>
       <queue relating='connection'>
          <!-- LOCAL (if embedded) or 'email' if started as a standalone client with XmlScript -->
          <address type="email" pingInterval='0'>
             xmlBlaster@master.com
          </address>
       </queue>
       <queue relating='callback' maxEntries='10000000' maxEntriesCache='1000'>
          <callback type='email' sessionId='xxpo569hJd' pingInterval='60000'
                    retries='-1' delay='30000' oneway='false' dispatcherActive='true'
                     dispatchPlugin='ReplManager,1.0'>
            repslave@someHost.com
            <burstMode maxEntries='1' />
            <!-- five minutes: 300000 -->
            <attribute name='responseTimeout' type='long'>300000</attribute>
            <!-- one minute: 60000 -->
            <attribute name='pingResponseTimeout' type='long'>60000</attribute>
            <!-- 2 hours: 7200000 (one day: 43200000) -->
            <attribute name='updateResponseTimeout' type='long'>7200000</attribute>
         </callback>
       </queue>
     </qos>
  </connect>

For more details please read requirement protocol.email.
Example
Java

A typical Java client code: 

import org.xmlBlaster.client.qos.ConnectQos;
import org.xmlBlaster.client.qos.ConnectReturnQos;
...

ConnectQos qos = new ConnectQos(glob, "william", "secretPwd");

ConnectReturnQos retQos = con.connect(qos, new I_Callback() {

   public String update(String cbSessionId, UpdateKey updateKey,
                        byte[] content, UpdateQos updateQos) {
      ...
      if (updateKey.isInternal()) {
         ...
      }

      if (updateQos.isOk()) {
         ...
      }
      else if (updateQos.isErased()) {
         ...
      }
      return "";
   }

});
Example
Java

Callback activation

This console example shows how to play with the callback activation setting, which allows to inhibit sending of queued callback messages during login:

java org.xmlBlaster.Main

java javaclients.HelloWorldPublish -destination receiver/1 -numPublish 100

java javaclients.HelloWorldSubscribe -session.name receiver/1 -dispatch/callback/dispatcherActive false

java javaclients.HelloWorldPublish -oid __cmd:client/receiver/1/?dispatcherActive=true

First start the server and a publisher which sends some PtP messages to the user receiver/1.
When receiver/1 connects the PtP messages are not send (note -dispatch/callback/dispatcherActive false) until we finally send the administrative command __cmd:client/receiver/1/?dispatcherActive=true which activates the receivers callback delivery.

Example
Java

Inhibit sending the connect request

Imagine a case where your client is behind a firewall and may not send a connect or subscribe to the xmlBlaster server. But still it wants to setup the callback server instance to receive update() messages, which means you need a fully operational java client library (class XmlBlasterAccess). Here is a 'hard coded' example doing so: 

// HelloWorld7.java

...

ConnectQos qos = new ConnectQos(glob);

// '-dispatch/connection/doSendConnect false' on command line would do the same
qos.doSendConnect(false);

// Initializes everything but does NOT send connect message
con.connect(qos, this);

log.info("HelloWorld7", "Waiting now for updates ...");

It is possible to set the behavior in the xmlBlaster.properties file or on command line as well: 

java MyClient -dispatch/connection/doSendConnect false

In such cases you need a 'delegate client' which connects from somewhere else and does the subscribe for you, with your callback address. This works fine with the XMLRPC callback server and with the 'email' callback server.

Configure

NOTE: Configuration parameters are specified on command line (-someValue 17) or in the xmlBlaster.properties file (someValue=17). See requirement "util.property" for details.
Columns named Impl tells you if the feature is implemented.
Columns named Hot tells you if the configuration is changeable in hot operation.

See REQ interface
See REQ client.configuration
See API org.xmlBlaster.client.qos.ConnectQos
See API org.xmlBlaster.client.qos.ConnectReturnQos
See API org.xmlBlaster.protocol.xmlrpc.AuthenticateImpl
See API org.xmlBlaster.protocol.rmi.AuthServerImpl
See http://www.xmlBlaster.org/xmlBlaster/demo/HelloWorld3.java.html
See http://www.xmlBlaster.org/xmlBlaster/src/java/org/xmlBlaster/protocol/corba/xmlBlaster.idl.html
See TEST org.xmlBlaster.test.authentication.TestLogout
See TEST org.xmlBlaster.test.authentication.TestLogin
See TEST org.xmlBlaster.test.authentication.TestLoginLogoutEvent
See TEST org.xmlBlaster.test.authentication.TestSession
See TEST org.xmlBlaster.test.authentication.TestSessionCb
See TEST org.xmlBlaster.test.authentication.TestSessionReconnect
See TEST org.xmlBlaster.test.authentication.TestReconnectSameClientOnly
See TEST org.xmlBlaster.test.authentication.TestAuthenticationHtPassWd
See TEST org.xmlBlaster.test.classtest.ConnectQosTest

This page is generated from the requirement XML file xmlBlaster/doc/requirements/interface.connect.xml

Back to overview