XmlBlaster Logo

REQUIREMENT

client.script

XmlBlaster Logo


Type NEW
Priority MEDIUM
Status CLOSED
Topic Invocations to the xmlBlaster server can be done with an xml script.
Des
cription

All invocations available to communicate to xmlBlaster can be done by submitting an xml document (which we also call a script). The syntax for the xml script has been designed with a particular emphasis on simplicity and flexibility.
Flexibility is important since this scripting capability can be for a broad varity of purposes. For example it can be used in the email protocol or it can be used in build tools such as ant and maven, it can be used to execute xml in an update message, in an xsp, ....

The script works with three streams:

  • request stream: the only input stream where the requests are specified
  • response stream: the output stream where the synchronous responses are sent
  • update stream: the output stream where the (asynchronous) updates are sent to
The input stream is mandatory while the output streams are optional. If they are null, then nothing is written to that stream. Response- and update stream could be the same. In that case it is ensured that you never will get an update inside a response or a response inside an update.

The syntax of the request:

A request starts with an xmlBlaster tag having an optional id attribute used to correlate a response to a request. Inside this root tag the following tags are recognized:

  • get childs: key and qos
  • connect childs: qos
  • disconnect childs: qos
  • erase childs: key and qos
  • publish childs: key content and qos
  • publishArr childs: one or more message
  • subscribe childs: key and qos
  • unSubscribe childs: key and qos
  • wait no childs but attributes: delay: the time to wait expressed in milliseconds. updates: the number of update messages to wait for. message: the optional output message
  • input Waits until the user hits a key, no childs but two attributes: message: the prompt message; delay: the time to wait expressed in milliseconds until the message prompt is displayed
For the qos and the key tags the syntax is the one defined in the client interface. The message subtag in the publishArr contains the same childs as a publish tag. The content tag has the following attributes:
  • link: the name of the attachment (if any) where the content resides
  • type: the same meaning as in ClientProperty (currently has no effect)
  • encoding: currently 'base64' is supported.
None of the mentionned attributes is mandatory. If no link is specified the text child of the content element is used. If a link is specified, then the text content is ignored.

The syntax of the response:

A response starts with an xmlBlasterResponse tag having an optional id attribute used to correlate a response to a request (the same id as it was in the request). Inside this root tag the subtags are exactly the same as for the request.

Every such subtag as childs corresponding to the litteral representation of the return object of the corresponding method invocation. For example a publish will have a child corresponding to the PublishReturnQos.toXml() method.

Variable replacement

Variables with ${...} are searched in the environment (Global scope) and are replaced by their values if found. A maximum nesting depth of 20 is supported (${} values which contain further ${}).

To switch this feature on you need to add following flags to the beginning of your script

<!-- replace e.g. ${ICAO} with command line setting '-ICAO EDDI' -->
<replaceQosTokens/>
<replaceKeyTokens/>
<replaceContentTokens/>

<replaceTokens/>

Setting configuration properties

At the beginning of the script you can set configuration properties, similar you would do it from xmlBlaster.properties:

<xmlBlaster>
   <property name="queue/connection/defaultPlugin">RAM,1.0</property>
   <connect/>
   ...
Example
any

The following is a simple session which can be invoked the as:

java javaclients.script.XmlScript \
     -requestFile simpleSession.xml \
     -responseFile out.xml
The simpleSession.xml in this case would contain what follows. The answers coming from xmlBlaster are collected in out.xml. If you want the output on the standard output stream omit to specify a responseFile. If you want to read from the standard input stream omit the requestFile. 

<xmlBlaster>
  <!-- note that if you omit the qos it will take an empty one (default) -->

  <replaceTokens />
  <property name="waitMillis">1000</property>
  <property name="queue/connection/defaultPlugin">RAM,1.0</property>

  <echo message="Starting now ${waitMillis} ..."/>

  <echo message="Starting now ..."/>

  <connect/>

  <input message="Hit a key to continue # "/>

  <subscribe><key oid="test"></key><qos/></subscribe>

  <wait delay="${waitMillis}" />
  <publish>
    <key oid="test"><airport name="london" /></key>
    <content>This is a simple script test</content>
    <qos/>
  </publish>

  <publishArr>
    <message>
      <key oid="test"></key>
      <content>This is a simple script test 1</content>
      <qos/>
    </message>
  </publishArr>

  <get><key oid="test" /></get>

  <input message="Hit a key to continue # "/>

   <subscribe>
     <key queryType="XPATH">//airport</key>
   </subscribe>

  <wait delay="${waitMillis}" />

  <unSubscribe><key oid="test"/></unSubscribe>

  <erase><key oid="test"></key><qos/></erase>

  <wait delay="${waitMillis}" />

  <disconnect />
</xmlBlaster>

Waiting could as well look like this: <wait delay="6000" updates="4" message="Waiting for messages ..."/>

And as the response to the upper request:

   
<xmlBlasterResponse>

   <!-- _____________________  connect ________________________________ -->
   <connect>
      <qos>
         <securityService type="htpasswd" version="1.0">
         <user>michele</user>
         <passwd>secret</passwd>
         </securityService>
         <session name='/node/xmlBlaster_127_0_0_2_3412/client/michele/-3'
               timeout='86400000' maxSessions='10' clearSessions='false' 
               reconnectSameClientOnly='false' sessionId='IIOP:0111332A414'/>
         <queue relating='connection'>
         <address type='IOR'>
            
         </address>
         </queue>
         <queue relating='subject'/>
         <queue relating='callback' maxEntries='1000' maxEntriesCache='1000'>
         <callback type='IOR' dispatchPlugin='undef'>
            IOR:000000000000004049444C3A6F72672E786D6C426C6173746..........
         </callback>
         </queue>
         <serverRef type='IOR'>
            IOR:000000000000003749444C3A6F72672E786D6C426C617374657........
         </serverRef>
      </qos>
   </connect>

   <!-- _____________________  subscribe ______________________________ -->
   <subscribe>
      <qos>
         <subscribe id='__subId:xmlBlaster_127_0_0_2_3412-5'/>
         <isSubscribe/>
      </qos>
   </subscribe>

   <!-- -- -- -- -- -- -- -- -- update -- -- -- -- -- -- -- -- -- -- -- -->
   <update>
      <sessionId>unknown</sessionId>
      <key oid='test'>
         <airport name='london'></airport>
      </key>
      <content><![CDATA [This is a simple script test]]&gt;</content>
      <qos>
         <sender>/node/xmlBlaster_127_0_0_2_3412/client/michele/-3</sender>
         <subscribe id='__subId:xmlBlaster_127_0_0_2_3412-5'/>
         <rcvTimestamp nanos='1075409585202000001'/>
         <queue index='0' size='1'/>
         <isUpdate/>
      </qos>
   </update>

   <!-- ________________________  publish ________________________________ -->
   <publish>
      <qos>
         <key oid='test'/>
         <rcvTimestamp nanos='1075409585202000001'/>
         <isPublish/>
      </qos>
   </publish>

   <!-- -- -- -- -- -- -- -- -- -- update -- -- -- -- -- -- -- -- -- -- -- -->
   <update>
      <sessionId>unknown</sessionId>
      <key oid='test'/>
      <content><![CDATA [This is a simple script test 1]]&gt;</content>
      <qos>
         <sender>/node/xmlBlaster_127_0_0_2_3412/client/michele/-3</sender>
         <subscribe id='__subId:xmlBlaster_127_0_0_2_3412-5'/>
         <rcvTimestamp nanos='1075409585342000001'/>
         <queue index='0' size='1'/>
         <isUpdate/>
      </qos>
   </update>

   <!-- -- -- -- -- -- -- -- -- -- update -- -- -- -- -- -- -- -- -- -- -- -->
   <update>
   <sessionId>unknown</sessionId>
      <key oid='test'/>
      <content><![CDATA [This is a simple script test 2]]&gt;</content>
      <qos>
         <sender>/node/xmlBlaster_127_0_0_2_3412/client/michele/-3</sender>
         <subscribe id='__subId:xmlBlaster_127_0_0_2_3412-5'/>
         <rcvTimestamp nanos='1075409585348000001'/>
         <queue index='0' size='1'/>
         <isUpdate/>
      </qos>
   </update>

   <!-- -- -- -- -- -- -- -- -- -- update -- -- -- -- -- -- -- -- -- -- -- -->
   <update>
      <sessionId>unknown</sessionId>
      <key oid='test'/>
      <content><![CDATA [This is a simple script test 3]]&gt;</content>
      <qos>
         <sender>/node/xmlBlaster_127_0_0_2_3412/client/michele/-3</sender>
         <subscribe id='__subId:xmlBlaster_127_0_0_2_3412-5'/>
         <rcvTimestamp nanos='1075409585400000001'/>
         <queue index='0' size='1'/>
         <isUpdate/>
      </qos>
   </update>

   <!-- -- -- -- -- -- -- -- -- -- update -- -- -- -- -- -- -- -- -- -- -- -->
   <update>
   <sessionId>unknown</sessionId>
      <key oid='test'/>
      <!-- Same attributes as clientProperty are supported: -->
      <content encoding="base64" charset="windows-1252">SGVsbG9Xb3JsZA==</content>
      <qos>
         <sender>/node/xmlBlaster_127_0_0_2_3412/client/michele/-3</sender>
         <subscribe id='__subId:xmlBlaster_127_0_0_2_3412-5'/>
         <rcvTimestamp nanos='1075409585412000001'/>
         <queue index='0' size='1'/>
         <isUpdate/>
      </qos>
   </update>

   <!-- ________________________  publishArr _____________________________ -->
   <publishArr>
      <message>
         <qos>
            <key oid='test'/>
            <rcvTimestamp nanos='1075409585342000001'/>
            <isPublish/>
         </qos>
      </message>

      <message>
         <qos>
            <key oid='test'/>
            <rcvTimestamp nanos='1075409585348000001'/>
            <isPublish/>
         </qos>
      </message>

      <message>
         <qos>
            <key oid='test'/>
            <rcvTimestamp nanos='1075409585400000001'/>
            <isPublish/>
         </qos>
      </message>

      <message>
         <qos>
            <key oid='test'/>
            <rcvTimestamp nanos='1075409585412000001'/>
            <isPublish/>
         </qos>
      </message>
   </publishArr>

   <!-- ________________________  get ____________________________________ -->
   <get>
      <message>
         <key oid='test'/>
         <content><![CDATA[This is a simple script test 4]]&gt;</content>
         <qos>
            <sender>/node/xmlBlaster_127_0_0_2_3412/client/michele/-3</sender>
            <rcvTimestamp nanos='1075409585412000001'/>
            <route>
            <node id='xmlBlaster_127_0_0_2_3412' stratum='0'
                  timestamp='1075409585412000001' dirtyRead='false'/>
            </route>
         </qos>
      </message>
   </get>

   <!-- -- -- -- -- -- -- -- -- -- update -- -- -- -- -- -- -- -- -- -- -- -->
   <update>
      <sessionId>unknown</sessionId>
      <key oid='test'/>
      <content><![CDATA [This is a simple script test 4]]&gt;</content>
      <qos>
         <sender>/node/xmlBlaster_127_0_0_2_3412/client/michele/-3</sender>
         <subscribe id='__subId:xmlBlaster_127_0_0_2_3412-XPATH6'/>
         <rcvTimestamp nanos='1075409585412000001'/>
         <queue index='0' size='1'/>
         <route>
            <node id='xmlBlaster_127_0_0_2_3412' stratum='0'
                  timestamp='1075409585412000001' dirtyRead='false'/>
         </route>
         <isUpdate/>
      </qos>
   </update>

   <!-- ________________________  subscribe ______________________________ -->
   <subscribe>
      <qos>
         <subscribe id='__subId:xmlBlaster_127_0_0_2_3412-XPATH6'/>
         <isSubscribe/>
      </qos>
   </subscribe>

   <!-- ________________________  unSubscribe ____________________________ -->
   <unSubscribe>
      <qos>
         <subscribe id='__subId:xmlBlaster_127_0_0_2_3412-5'/>
         <isUnSubscribe/>
      </qos>
      <qos>
         <subscribe id='__subId:xmlBlaster_127_0_0_2_3412-XPATH6:7'/>
         <isUnSubscribe/>
      </qos>
   </unSubscribe>

   <!-- ________________________  erase __________________________________ -->
   <erase>
      <qos>
         <key oid='test'/>
         <isErase/>
      </qos>
   </erase>

   <!-- ________________________  disconnect _____________________________ -->
   <disconnect>true</disconnect>

</xmlBlasterResponse>

Example
any

Exception example


<xmlBlasterResponse>
  <exception errorCode='user.illegalArgument'>
    <class>org.xmlBlaster.util.XmlBlasterException</class>
    <isServerSide>true</isServerSide>
    <node>heron</node>
    <location>Authenticate-/node/heron.InvalidClientName</location>
    <lang>en</lang>
    <message>#1.0.7 Your given loginName is null or shorter 2 chars</message>
    <versionInfo>version=1.0.7,os.name=Linux,os.version=2.6.13</versionInfo>
    <timestamp>2005-11-11 09:30:30.69</timestamp>
    <stackTrace>errorCode=user.illegalArgument message=#1.0.7
      Your given loginName is null or shorter 2 chars, loginName rejected
      at Authenticate.connect(Authenticate.java:352)
      at AuthServerImpl.connectIntern(AuthServerImpl.java:260)
      at AuthServerImpl.connect(AuthServerImpl.java:232)
      at RequestProcessor.invokeOperation(RequestProcessor.java:281)
      at RequestProcessor.process(RequestProcessor.java:576)
      at RequestProcessor.run(RequestProcessor.java:718)></stackTrace>
    <embeddedMessage></embeddedMessage>
  </exception>
</xmlBlasterResponse>
Configure

You can control the extend of the generated XML markup (the returned QoS) by setting following configuration parameters.

xmlDeclaration <?xml version='1.0' encoding='UTF-8'?> The header to add to the script if formatted with XmlScriptParser. yes
schemaDeclaration xmlns:xsi= 'http://www.w3.org/2001/XMLSchema-instance' xsi:noNamespaceSchemaLocation= 'mySchema.xsd' This allows to add a schema declaration to the generated XML. The method name root tag (for example <update xmlns:xsi=...) is complemented with the given string. yes
sendResponseSessionId true Add the sessionId="..." xml-attribute to the XmlScript markup? For example <update sessionId='fgg694' .... yes
sendResponseRequestId true Add the requestId="..." xml-attribute to the XmlScript markup? For example <update requestId='17743005' .... yes
sendSimpleExceptionFormat false If set to true and used with XmlScriptParser the UpdateReturnQos has a simple format (even for exceptions) which satisfies the XML-schema simpleReturnQos.xsd. 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.

See API org.xmlBlaster.client.script.XmlScriptInterpreter
See API The test client XmlScriptClient
See REQ engine.qos.clientProperty
See REQ interface
See TEST org.xmlBlaster.test.classtest.XmlScriptInterpreterTest

This page is generated from the requirement XML file xmlBlaster/doc/requirements/client.script.xml

Back to overview