XmlBlaster Logo

REQUIREMENT

protocol.local

XmlBlaster Logo


Type NEW
Priority HIGH
Status CLOSED
Topic XmlBlaster supports native client server communication in the same JVM
Des
cription

If a client connects to XmlBlaster with the XmlBlasterAccess client interface it can choose the communication protocol like Corba, SOCKET, XmlRpc and more. But if the client runs in the same JVM we can avoid the communication over a socket by choosing the LOCAL protocol plugin. This improves speed and avoids using OS resources like ports and threads.
Switching the protocol is just a configuration setting, so any existing client can choose to communicate locally.

Client that want's to be able to use the local protocol must however have access to the serverside "singleton" org.xmlBlaster.engine.ServerScope, either directly or through a global wich contains the serverside global i is ObjectEntry under the key: ServerNodeScope. Futhermore, it must see to it than any cloning it does of its global (for example to be able to use more than one XmlBlasterAccess) contians this ServerNodeScope entry. The org.xmlBlaster.j2ee.util.GlobalUtil may be used to do just that.

There are currently three ways to do this.

It is possible to start xmlBlaster clients with the runlevel manager of xmlBlaster. Like this the client is started on xmlBlaster startup in the same JVM as the server in a configurable sequence with other services (see our runlevel manager requirement).Note that the client must implement the I_Plugin interface to be loadable as a plugin, this is described in the engine.runlevel requirement.

If one starts an embedded XmlBlaster it is also possible to access the ServerScope: serverThread.getMain().getGlobal()

When using the JBoss/JMX service to start XmlBlaster it is also possible to specify a JNDIname where an instance of GlobalUtil should be bound. This GlobalUtil instance will contain a reference to the engine global as long as its looked up in the same VM.
Example
Java

The following demo code is a client which can be started as a standalone client or it can be loaded dynamically by the runlevel manager to run in the same JVM as the server: 

    
 1 // xmlBlaster/demo/javaclients/HelloWorldNative.java
     2 package javaclients;
     3 import org.xmlBlaster.client.qos.ConnectQos;
     4 import org.xmlBlaster.client.I_XmlBlasterAccess;
     5 import org.xmlBlaster.client.XmlBlasterAccess;
     6 import org.xmlBlaster.util.Global;
     7 import org.xmlBlaster.util.XmlBlasterException;
     8 import org.xmlBlaster.util.MsgUnit;
     9 import org.xmlBlaster.util.plugin.I_Plugin;
    10 import org.xmlBlaster.util.plugin.PluginInfo;
    11 
    12 
    13 /**
    14  * This native client plugin is loaded by xmlBlaster on startup, 
    15  * it then connects to xmlBlaster and gets synchronous a message and disconnects. 
    16  * <p />
    17  * You need to add this plugin to xmlBlasterPlugins.xml, for example:
    18  * <pre>
    19  *  &lt;plugin id='HelloWorldNative' className='javaclients.HelloWorldNative'>
    20  *     &lt;action do='LOAD' onStartupRunlevel='9' sequence='5'
    21  *                          onFail='resource.configuration.pluginFailed'/>
    22  *     &lt;action do='STOP' onShutdownRunlevel='6' sequence='4'/>
    23  *  &lt;/plugin>
    24  * </pre>
    25  * As a protocol driver to talk to xmlBlaster it has configured "LOCAL", this
    26  * plugin works only if client and server is in the same virtual machine (JVM).
    27  * Other protocols like CORBA or SOCKET would work as well but carry the overhead
    28  * of sending the message over TCP/IP.
    29  * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/engine.runlevel.html"
    30  *       target="others">run level requirement</a>
    31  * @see javaclients.HelloWorldNative2
    32  */
    33 public class HelloWorldNative implements I_Plugin
    34 {
    35    private Global glob;
    42 
    43    private final void queryServerMemory() {
    44       try {
    45          System.err.println("HelloWorldNative: Connecting with protocol 'LOCAL'\n");
    46          I_XmlBlasterAccess con = new XmlBlasterAccess(glob);
    47 
    48          ConnectQos qos = new ConnectQos(this.glob); /* Client side object */
    49          qos.setUserId("A-NATIVE-CLIENT-PLUGIN");
    50          qos.getSessionQos().setSessionTimeout(0L);
    51          con.connect(qos, null);  // Login as "A-NATIVE-CLIENT-PLUGIN"
    52 
    53          MsgUnit[] msgs = con.get("<key oid='__cmd:?freeMem'/>", null);
    54 
    55          System.out.println("\nHelloWorldNative: xmlBlaster has currently " +
    56                 new String(msgs[0].getContent()) + " bytes of free memory\n");
    57 
    58          con.disconnect(null);
    59       }
    60       catch (Exception e) {
    61          System.err.println("HelloWorldNative: Exception: "+e.toString());
    62       }
    63    }
    64 
    65    public void init(org.xmlBlaster.util.Global glob, PluginInfo pluginInfo)
    66                                                     throws XmlBlasterException {
    67       this.glob = glob.getClone(glob.getNativeConnectArgs());
    68       this.glob.addObjectEntry("ServerNodeScope", 
    69                                glob.getObjectEntry("ServerNodeScope"));
    70       System.out.println("\nHelloWorldNative: init(): The plugin is loaded");
    71       queryServerMemory();
    72    }
    73 
    74    public String getType() {
    75       return "HelloWorldNative";
    76    }
    77 
    78    public String getVersion() {
    79       return "1.0";
    80    }
    81 
    82    public void shutdown() throws XmlBlasterException {
    83       System.err.println("\nHelloWorldNative: shutdown()\n");
    84    }
    85 
    86    /** To start as a plugin */
    87    public HelloWorldNative() {}
    88 
    89    /** To start as a standalone client: java javaclients.HelloWorldNative */
    90    public HelloWorldNative(String args[]) {
    91       this.glob = new Global(args);
    92       queryServerMemory();
    93    }
    94 
    95    public static void main(String args[]) {
    96       new HelloWorldNative(args);
    97    }
    98 }

To tell the runlevel manager when to load the plugin you need to edit xmlBlasterPlugins.xml and register the plugin: 

<plugin id='HelloWorldNative' className='javaclients.HelloWorldNative'>
   <action do='LOAD' onStartupRunlevel='9' sequence='5'
              onFail='resource.configuration.pluginFailed'/>
   <action do='STOP' onShutdownRunlevel='6' sequence='4'/>
</plugin>

Please read the requirement engine.runlevel.howto for further details

The example HelloWorldNative2 provides an extended example how to do publish/subscribe from a plugin and how to pass plugin specific attributes/parameters to the plugin.

Example
Java

Looking up a GlobalUtil and using it in a JBoss environment:

      Global Util globalUtil = (GlobalUtil)new InitialContext().lookup(jndiName);
      Global glob = globalUtil.newGlobal( propFile, props );
      I_XmlBlasterAccess conOne = glob.getXmlBlasterAccess();
      I_XmlBlasterAccess conTwo = globalUtil.getClone( glob ).getXmlBlasterAccess();

Using it when embedding XmlBlaster:

      EmbeddedXmlBlaster serverThread = EmbeddedXmlBlaster.startXmlBlaster(args);
      GlobalUtil globalUtil = new GlobalUtil( serverThread.getMain().getGlobal() );
      Global runglob = globalUtil.getClone( glob );
      con = runglob.getXmlBlasterAccess();
      ConnectQos qos = new ConnectQos(runglob, name, passwd);
      I_XmlBlasterAccess con.connect(qos, this); // Login to xmlBlaster
Configure

On client side we need to register the LOCAL protocol plugin to be available in the Java client library.

Property Default / Example Description Implemented
ClientProtocolPlugin[LOCAL][1.0] org.xmlBlaster.client.protocol.local.LocalConnection Specify the plugin to get support of direct client/server communication in the same JVM yes
ClientCbServerProtocolPlugin[LOCAL][1.0] org.xmlBlaster.client.protocol.local.LocalCallbackImpl Specify the native callback plugin yes

On serverside side we need to register the LOCAL protocol serverside callback driver.

Property Default / Example Description Implemented
CbProtocolPlugin[LOCAL][1.0] org.xmlBlaster.protocol.local.CallbackLocalDriver Specify the callback driver on the serverside. yes

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.

Todo
  1. Example of a I_Plugin client.
See REQ protocol
See REQ engine.runlevel.howto
See API javaclients.HelloWorldNative
See http://www.xmlBlaster.org/xmlBlaster/demo/javaclients/HelloWorldNative.java.html
See API javaclients.HelloWorldNative2
See http://www.xmlBlaster.org/xmlBlaster/demo/javaclients/HelloWorldNative2.java.html
See API org.xmlBlaster.client.protocol.local.LocalConnection
See API org.xmlBlaster.client.protocol.local.LocalCallbackImpl
See API org.xmlBlaster.protocol.local.CallbackLocalDriver
See API org.xmlBlaster.j2ee.util.GlobalUtil
See API org.xmlBlaster.j2ee.jmx.XmlBlasterService

This page is generated from the requirement XML file xmlBlaster/doc/requirements/protocol.local.xml

Back to overview