Reference guide

This chapter describes the different connectors provided in this submarine version. It also try to give a user documentation of the connectors.

xml configuration file
buildXPathString
Base serializers
Base writers
Base pooling function
Base resources
Technical connectors
WSP Writer
SubML connectors
JDBC connectors

 

The Submarine server is a process that hold particular rules of transformation, transport and correlation corresponding to a project logic. This logic is written in one or more configuration file loaded by the Submarine server at start time.
This (those) xml configuration file(s) contains elements describing the core elements to instantiate at run-time.
The syntax is the following:

<submarine>
	<global>
		<server id="demo"/>
		<listener port="9090"/>
		<archive path="archive" encoding="ISO-8859-1"/>
		<threads count="5"/>
		<properties>
			<property name="pty.name">value</property>
		</properties>
	</global>
	<Includes>
		<Include file="XMLFileTransform\eai.xml"/>
		...
	</Includes>
	<Resources>
		<Resource id="ress id" class="package.class">
			...
		</Resource>
		...
	</Resources>
	<PoolingFunctions>
		<PoolingFunction id="pf id" class="package.class">
			...
		</PoolingFunction>
		...
	</PoolingFunctions>
	<ListeningFunctions>
		<ListeningFunction id="lf id" class="package.class">
			...
		</ListeningFunction>
		...
	</ListeningFunctions>
	<Channels>
		<Channel name="channel name">...</Channel>
		...
	</Channels>
	<WritingFunctions>
		<WritingFunction id="wf id"  class="package.class">
			...
		</WritingFunction>
		...
	</WritingFunctions>
</submarine>

XML elements description:

xml configuration
submarine
possible children
nb
description

global
1,1
contains the engine parameters
Includes
0,1
contains a list of configuration file to include
Resources
0,1
contains a list of resources definition
PoolingFunctions
0,1
contains a list of pooling functions implementations
ListeningFunctions
0,1
contains a list of listening functions implementations
Channels
0,1
contains a list of channels descriptions
WritingFunctions
0,1
contains a list of writing functions implementations

Included files follows the same syntax but the global element is not required and not significant.

global
possible children
nb
description

server/@id
1,1
a name that identify the engine uniquely among others submarine engines
listener/@port
1,1
the TCP port on which the internal listener will wait commands
archive/@path
0,1
the directory to which the submarine engine will archive the messages traversing the system and write the errors. This path is relative to the start directory of the virtual machine. The default path is "archive".
archive/@encoding
0,1
the characters encoding to use for the archive files. The default value is "ISO-8859-1".
thread/@count
0,1
the number of concurrent threads executing channels. The default value is 4.
properties
0,1
contains a list of system properties definition

properties
possible children
nb
description

property
1,n
the definition of a system property. A system property could be obtain at run time with System.getProperty().

property
possible children
nb
description

@name
1,1
the name of the system property
text()
1,1
the value of the system property

Includes
possible children
nb
description

Include/@file
1,n
the file name of the configuration to add, with potential path relatively to the start directory of the virtual machine.

Resources
possible children
nb
description

Resource
0,n
The definition of a Resource implementation.

PoolingFunctions
possible children
nb
description

PoolingFunction
0,n
The definition of a pooling function implementation.

ListeningFunctions
possible children
nb
description

ListeningFunction
0,n
The definition of a listening function implementation.

Channels
possible children
nb
description

Channel
0,n
The description of a channel.

WritingFunctions
possible children
nb
description

WritingFunction
0,n
The definition of a writing function implementation.

Resource
possible children
nb
description

@id
1,1
a unique identifier of the resource among all the resources.
@class
1,1
the full name of the class that implements the submarine.core.Resource interface.
node()
0,1
any nodes that define the configuration of the implementation. See class documentation for details.

PoolingFunction
possible children
nb
description

@id
1,1
a unique identifier of the pooling function among all the pooling functions.
@class
1,1
the full name of the class that implements the submarine.core.PoolingFunction interface.
node()
0,1
any nodes that define the configuration of the implementation. See class documentation for details.

ListeningFunction
possible children
nb
description

@id
1,1
a unique identifier of the listening function among all the listening functions.
@class
1,1
the full name of the class that implements the submarine.core.ListeningFunction interface.
node()
0,1
any nodes that define the configuration of the implementation. See class documentation for details.

RouteInfos is an element used to select one or more channels to which a message should be send and if this message should be send synchronously or not.

RouteInfos
possible children
nb
description

source
1,1
a text that specify the source of channels to select. ‘*’ means any source.
destination
1,1
a text that specify the destination of channels to select. ‘*’ means any destination.
msgType
1,1
a text that specify the message type of channels to select. ‘*’ means any message type.
channel
1,1
a text that specify a particular channel to select. In that case source, destination and msgType are ignored. Otherwise, the text must be ‘*’.
sync
1,1
‘true’ to indicate that the channel submission must be synchronous. ‘false’ if the submission must be asynchronous.

Channel
possible children
nb
description

source
1,1
a text that specify the source of this channel
destination
1,1
a text that specify the destination of this channel
msgType
1,1
a text that specify the message type of this channel
parser
1,1
an element describing an implementation of the submarine.core.Serializer interface to use as a transformer of a java.lang.Object to a org.w3c.dom.Document.
xsl-template
1,1
an element describing the configuration of a XSLT transformation.
serializer
1,1
an element describing an implementation of the submarine.core.Serializer interface to use as a transformer of a org.w3c.dom.Document to a java.lang.Object.
writer
1,1
a text giving the name of a declared writing function
on-error-writer
0,1
a text giving the name of a declared writing function to use in case of error. If not specified, an error file is created in the archive directory.

archive
1,1
an element describing which messages should be archived during the channel process.

parser or
serializer
possible children
nb
description

@class
1,1
the full name of the class that implements the submarine.core.Serializer interface.
node()
0,1
any nodes that define the configuration of the implementation. See class documentation for details.

xsl-template
possible children
nb
description

file
1,1
a text giving the name of the stylesheet file relatively to the start directory of the virtual machine.
params/param
0,n
contains a list of param elements that should be passed to the stylesheet.

param
possible children
nb
description

@name
1,1
the name of the stylesheet parameter.
@type
0,1
  • ‘ctx’ if the value of the parameter is the value of the context attribute ‘name’ in the channel processing.
  • ‘now’ if the value is the current date and time. see @format.
  • not required if the value is given by the text() node.
@format
0,1
if @type="now", the format is a date time format string. see SimpleDateFormat class for details.
text()
0,1
the value of the param.

archive
possible children
nb
description

@in
0,1
‘yes’ if the java object submitted in the channel should be archived. ‘no’ otherwise and by default.
@in.xml
0,1
‘yes’ if the result of parsing the java object should be archived. ‘no’ otherwise and by default.
@out.xml
0,1
‘yes’ if the result of the XSLT transformation should be archived. ‘no’ otherwise and by default.
@out
0,1
‘yes’ if the result of the serialization should be archived. ‘no’ otherwise and by default.

WritingFunction
possible children
nb
description

@id
1,1
a unique identifier of the writing function among all the writing functions.
@class
1,1
the full name of the class that implements the submarine.core.WritingFunction interface.
node()
0,1
any nodes that define the configuration of the implementation. See class documentation for details.

buildXPathString
The buildXPathString is a static function of the submarine.util.Tools class. It is very usefull to construct dynamically a string combining string constant, date and time value, channel context attribute value and xpath query with an xml node as context query.
The function valuates an xml element using its text nodes and elements nodes into a string using the following rules and syntax.
The parameters of this function are :
  1. content: the xml element to evaluate
  2. context: the xml node context for xpath queries. if null, xpath queries are not evaluated.
  3. attrs: a list of properties coming from the channel context.

Text nodes are copied to the result string as is. Element nodes must have the <value-of select=""/> form otherwise they are ignored. The select attribute is interpreted using the following steps:
  1. $(xxxx) patterns are replaced by the property value named ‘xxxx’. If this property does not exist, the pattern is replaced by an empty string.
  2. $[datetime format] patterns are replaced by the current datetime formatted using the given format.
  3. ${xyzt} patterns are replaced by ‘xyzt’. For instance ${$[xx]} is replaced by $[xx].
  4. If the context parameter is null, the modified select attribute is copied to the result string.
  5. Otherwise, the resulting select attribute value is used to execute an xpath query on the context parameter. The result of that xpath query is transformed to a text according to its type and copied to the result string.

Example: Lets say we are the may 2nd 2002 at 22:56:00. We have the following xml document as context node and the following list of attributes:
<root>
	<data @id="123">hello world</data>
</root>
The attributes
project=submarine
attr=id
Now, the following xml element :
<element>It is <value-of select="'$[hh:nn:ss]'"/>.
<value-of select="root/data"/> the id is
<value-of select="root/data/@$(attr)"/> and the project is
<value-of select="'$(project)'"/></element>
The result of the call of the buildXPathString with this element, the root element as node context and those attributes will be :
It is 22:56:00. hello world the id is 123 and the project is submarine

Base serializers

eai.empty

This pseudo eai.empty class name is a keyword used in a channel configuration to tell that the parser or serializer does nothing at all. Precisely, this kind of serializer try to cast the java.lang.Object into a org.xml.dom.Document and cast the Document into a java object in the other side.

eai.empty
Parsed classes
org.w3c.dom.Document
Serialized classes
org.w3c.dom.Document

config
possible children
nb
description

Identity

This class parse a xml text document into a XML DOM representation and serialize a DOM representation into a xml text document.

submarine.connectors.Identity
Parsed classes
org.w3c.dom.Document, org.w3c.dom.Element, java.io.InputStream, java.io.Reader, java.lang.String
Serialized classes
submarine.connectors.ArchivableInputStream

config
possible children
nb
description

encoding
0,1
a text giving the resulting xml stream encoding. Default is the Submarine engine encoding.
xmldecl
0,1
a text. If ‘true’, the resulting stream will contain the xml processing instruction.

ProcessorSerializer

This class allows to make pre treatments or post treatment on the java object before or after the parsing or serialization. This class delegate the implementation to another Serializer.

submarine.connectors.ProcessorSerializer
Parsed classes
depends of the enclosing serializer
Serialized classes
depends of the enclosing serializer

config
possible children
nb
description

Serializer/@class
1,1
the fully qualified class name of a Serializer implementation that will perform the parsing or serialization.
Serializer
1,1
the xml element that will be passed to the Serializer/@class implementation for its initialization.
Processor/@class
1,1
the fully qualified name of a class implementing the submarine.connectors.ObjectProcessor interface.
Processor
1,1
the xml element that will be passed to the ObjectProcessor implementation for its initilization.


  ContextSerializer  

This class allows to add context attributes using the xml document of parsing or serialization. This class delegate the implementation to another Serializer.

submarine.connectors.ContextSerializer
Parsed classes
depends of the enclosing serializer
Serialized classes
depends of the enclosing serializer

config
possible children
nb
description

Serializer/@class
1,1
the fully qualified class name of a Serializer implementation that will perform the parsing or serialization.
Serializer
1,1
the xml element that will be passed to the Serializer/@class implementation for its initialization.
attributes
1,1
contains a list of attribute definition
attributes
attribute
1,n
defines an attribute to set in the context.
attribute
@name
1,1
the name of the attribute to set
node()
1,n
the content of this node is the attribute value and is interpreted by the buildXPathString function.



ReturnWriter

The ReturnWriter writing function just returns the doc arguments when called synchronously and false otherwise.

Base writers
submarine.connectors.ReturnWriter
Accepted classes
java.lang.Object
Synchronous
supported
Asynchronous
supported

config
possible children
nb
description


ListWriter

The ListWriter writing function writes the doc argument iteratively to each inner writing functions. It returns the logical AND combination of all the returns in case of asynchronous call and a vector of the returned object in case of synchronous call.

submarine.connectors.ListWriter
Accepted classes
classes accepted by all the internal writing functions
Synchronous
supported
Asynchronous
supported

config
possible children
nb
description

Writer/@id
0,n
id of a declared writing function to use in the list. Several Writer elements could be present.

ChainWriter

The ChainWriter writing function writes the doc argument to the first inner writing functions, then call the following writing functions with the result of the previous one. It returns the result of the last inner writing function.

submarine.connectors.ChainWriter
Accepted classes
classes accepted by the first writing function
Synchronous
supported
Asynchronous
not supported. Done synchronously.

config
possible children
nb
description

Writer/@id
0,n
id of a declared writing function to use in the list. Several Writer elements could be present.

Loopback

The Loopback class is a writing function that write the doc argument to an inner writing function and submit the result/doc to the Submarine engine.
In a synchronous mode, the result of the putSyncDocument() of the inner writing function is submitted to Submarine with the routing information. The result is the result of the submission.
In an asynchronous mode, if the result of the putDocument() of the inner writing function is true, it submits the doc argument to Submarine with the routing information. the result is true if the submission occurred and succeeded.

submarine.connectors.Loopback
Accepted classes
classes accepted by the inner writing function
Synchronous
supported
Asynchronous
supported

config
possible children
nb
description

writer/@id
1,1
id of a declared writing function to use.
RouteInfos
1,1
Routing information for the channels selection. See "xml configuration file" for the detail of this element.

FileSystemConnector

This class is either a writing function and a pooling function. As a writing function, this class write the doc argument into a file. If the file already exists, it appends the argument in the file. missing path are automatically created.

submarine.connectors.FileSystemConnector (as a writing function)
Accepted classes
java.io.InputStream, java.io.Reader, java.lang.String,
Synchronous
supported
Asynchronous
not supported. Done synchronously.

config
possible children
nb
description

filename
1,1
the content of this node is the file name relative to the start directory of the virtual machine. It is interpreted by the buildXPathString function using no xml document.


FileSystemConnector

This class is either a writing function and a pooling function. As a pooling function, this class look in a directory for files whose name ends with a suffix. Each found file is submitted to Submarine in a particular type (file, stream or string) and then moved to another directory.

Base pooling function
submarine.connectors.FileSystemConnector (as a pooling function)
Returned classes
submarine.connectors.ArchivableFile, submarine.connectors.ArchivableInputStream,
java.lang.String
Attributes context
fileName
the name of the file returned with the extension

fileNameNoExt
the name of the file returned without extension

filePath
the full pathname of the file returned

absoluteFilePath
the absolute pathname of the file returned


config
possible children
nb
description

fileExt
1,1
the extension of the files to select
poolingPath
1,1
the directory in which the files are selected
movedPath
0,1
the directory to which moved the red files. the default directory is ‘moved’ in the poolingPath.
objectType
1,1
one of the following text: ‘FILE’ if the returned document is a File, ‘STREAM’ if the returned document is an InputStream and ‘STRING’ if the returned document is a String.
objectType/@encoding
0,1
If objectType is ‘STRING’ this attribute give the file characters encoding in order to corverti it correctly. Default is the default system encoding.
frequency
1,1
a text giving the number of milliseconds to wait between each search in the directory.
RouteInfos
1,1
Routing information for the channels selection. See "xml configuration file" for the detail of this element.

TimerFunction

This class is a special pooling function that never submit document to Submarine but use the pooling mechanism in order to reproduce the well known unix crontab behaviour.
With a certain frequency, the pooling function is activated and if some date and time rules are true a writing function is called with the current date as argument.
The highest precision of the date and time rules is the minute. That mean that the writing function is called at worst once by minute and never more.

submarine.connectors.TimerFunction
Returned classes
none. hasNewDocument() always return false
Attributes context
none

config
possible children
nb
description

frequency
1,1
a text giving the number of milliseconds to wait between each rules test.
At
1,1
An xml element that gives the date and time rules for calling the writer. Each rule is a string following the "rule syntax"
Writer
0,1
a text giving the id of a declared writing function that will receive a java.util.Date object as parameter.
At
@minute
0,1
the rule on the minutes with values in (0 ... 59)
@hour
0,1
the rule on the hours with values in (0 ... 23)
@dayofweek
0,1
the rule on the day in the week with values in (1=Sunday ... 7=Saturday)
@dayofmonth
0,1
the rule on the day in the month with values in (1 ... 31)
@month
0,1
the rule on the month in the year with values in (0=January ... 11=December)
@year
0,1
the rule on the year with values in (1900 ... *)

The rule syntax has the following bnf syntax:
rule::='*'|<test>(','<test>)*
test::=<integer>|<integer>'-'<integer>
‘*’ means any value match the rule. <test1>,<test2> means that a value match the rule is the value match test1 or test2. x-y means that a value match the rule if the value is like x<=value<=y.

PropertiesResource

This class is a Resource implementation. It gives a shared but synchronized access to a set of properties (name=value). These properties are persistent. It means that once written, a property value is available to the next start of the Submarine server.
There is two ways of persisting the properties. Once is at each modification of a property (storeImmediatly) the other is at the Submarine engine stop.

Base resources
submarine.connectors.PropertiesResource
Multiple instance
yes

config
possible children
nb
description

properties
1,1
a text giving the properties file name. The path name is relative to the virtual machine start directory.
storeImmediatly
1,1
if the text is ‘true’, each property modification saves the properties in the file. Else, if the text is ‘false’, properties are stored to the file when Submarine stops.

ThreadManager

This class is a Resource implementation designed to interrupts and terminates threads registered to it. When the Submarine server stops, the resource interrupts all the registered alive threads, waits 3 seconds max each for their stop and then if still alive stop them.

submarine.connectors.ThreadManager
Multiple instance
yes

config
possible children
nb
description


FlatFileSerializer

This class is a Serializer designed to transformed a text flat file into an xml dom document and vice versa. The transformation is based on an xml file (the xflat schema) developers should learn to build these serialization.
The classes that make the transformation are sold by the Unindex company (www.unidex.com) and the documentation of the xflat schema could be found at http://www.unidex.com/overview.htm.

Technical connectors
submarine.connectors.FlatFileSerializer
Parsed classes
java.io.File, java.io.InputStream, java.io.Reader, java.lang.String
Serialized classes
submarine.connectors.ArchivableInputStream

config
possible children
nb
description

encoding
0,1
The encoding to use if the source is an InputStream. Default value is UTF-8.
schema

The file name of the xflat schema. the path name is relative to the virtual machine start directory.

Note that the Unindex classes are enclosed in the Submarine packaging in the xmlflat.jar for evaluation purpose only because those classes are not distributed under an open-source licence.

ShellWriter

This class is a writing function designed for executing system commands (unix and windows) using the jdk1.3 java.lang.Runtime.exec() method.
The synchronous implementation returns a string that contains the standard output and error of the executed command. To do so, two threads are created to read in real-time the output and error stream.
In the asynchronous mode, the writer start a new thread that execute the command and returns true. In this case, it is possible and recommended to use a ThreadManager, so this thread will be terminated properly if Submarine stops before the end of the command.
The command and start directory defined in the configuration are both evaluated with the buildXPathString method. The xml node context is the doc argument if it is an instance of Node.
Note that to execute a shell command with the Runtime class you must specify for windows:
cmd /C dir c:\
and for unix:
/bin/sh -C ls -als /

submarine.connectors.ShellWriter
Accepted classes
any, but org.w3c.dom.Node allows xpath query in command and working directory.
Synchronous
supported
Asynchronous
supported

config
possible children
nb
description

command
1,1
a xml element interpreted with buildXPathString to define the shell command to execute.
workDir
0,1
a xml element interpreted with buildXPathString to define the directory in which the command should be launched. The default directory is the virtual machine start directory.
manager
0,1
a text giving the id of a ThreadManager Resource. The default is ‘ThreadManager’. If no ThreadManager resource is found, the threads are not managed.

TCPWriter

This class is a writing function designed to send the doc argument to a TCP connection socket and to wait a response from the connected server. In asynchronous mode, no response is waited. The doc argument is converted into a binary stream according to a defined encoding and written to the socket. If the endOfStream is set to ‘–1’ then the socket output stream is closed else the endOfStream value is written to the socket to tell that the message ends.
In synchronous mode, the writer wait for the response by reading the socket input stream with a defined timeout. The red stream is then converted in the same type that the doc argument (if possible) and returned.

submarine.connectors.TCPWriter
Accepted classes
java.lang.String, java.io.InputStream, java.io.Reader, org.w3c.dom.Document
Synchronous
supported
Asynchronous
supported, but returns when all the argument have been sent

config
possible children
nb
description

host
1,1
the ip address or name of the TCP server host
port
1,1
a text giving the port number of the server.
encoding
1,1
a text giving the encoding for the stream
endOfStream
0,1
an integer that should be sent after the message to the socket stream. If ‘-1’ the socket output stream is closed. The default value is ‘0’.
wait-response
0,1
if this element is present, it means that the writer must wait a response from the server. If absent, the writer returns after sending the message to the server.
wait-response
@timeout
0,1
The number of milliseconds to wait the response from the server. The default value is ‘0’ which mean an infinite time.

This writer is useful to integrate Submarine with any tcp server. The need is to create a Serializer from the message to a stream of the particular protocol to implements (HTTP, FTP, SOAP, ...)

SyncWriter

This class is a writing function designed to correlate two messages flow. Imagine that the message M1 is sent to submarine but need a message M2 before being sent to the final recipient. To implement this logic, we must use two SyncWriter. One for the M1 message in order to wait for M2 and another one for the M2 message in order to notify the first one.
We see that the two SyncWriter are linked together with a key that tell the second writer to notify the first one.

submarine500.jpg

Most of the time the key is the M1 message id because it identifies uniquely the message, but it could be any other string.
This writer does not work asynchronously (of course). It has two behaviors, "waiting for" and "notification".
As a "waiting for" behavior (on M1) it returns the M2 message or null if the timeout occurred.
As a "notification" behavior (on M2) it returns also the M2 message which is the doc argument.
A typical use case is the following diagram:

submarine501.jpg

submarine.connectors.SyncWriter
Accepted classes
any, but org.w3c.dom.Node allows xpath query in key definition.
Synchronous
supported
Asynchronous
not supported, treated as synchronous

config
possible children
nb
description

waitFor
0,1
an xml element to set the writer in "wait for" behavior. The content is interpreted to the key with buildXPathString.
notify
0,1
an xml element to set the writer in "notification" behavior. The content is interpreted to the key with buildXPathString.
timeout
0,1
If the writer is in "wait for" behavior, this is the number of milliseconds to wait for the notification. Default value is 1 minute. If the value is ‘0’ the writer wait indefinitely.


Note that at least once of the waitFor and notify element must be present. If not, an exception is thrown during initialization.


The WSP (Writing Server Page) technology is fully inspired of the JSP (Java Server Page) technology in the J2EE standard.
A WSP page is a writing function represented by an xml file that describes some treatments on the doc argument of the WritingFunction interface. At run-time, the Submarine engine compiles the WSP file into a WritingFunction implementation exactly in the same way an application server compile a JSP file into a Servlet.
In that context we can say that if pre-compiled writing functions are like Servlet, WSP are JSP.
A WSP implementation inherits from the BaseWriterPage class (see java doc)

WriterPageInvoker

This class is a writing function designed to be a wrapper between Submarine engine and a WSP page. When invoking the writing function, this writer implementation check if the wsp file as changed from the last time, compiles it into a java class and executes it.
The compiled class execute the run() method that can use all the protected members of BaseWriterPage class.

WSP Writer
submarine.pages.WriterPageInvoker
Accepted classes
java.lang.Object
Synchronous
supported
Asynchronous
supported, wsp executed in a separated thread

config
possible children
nb
description

page
1,1
the name of the wsp page to execute. The path name is relative to the virtual machine start directory.
internal

an xml element passed to the wsp implementation as the xmlConfig protected member.

Example of wsp writing function declaration:
<WritingFunction id="WSPPageSW" class="submarine.pages.WriterPageInvoker">
	<page>SyncWriter/pagesw.wsp</page>
	<internal>
		<!-- anything the wsp page need -->
	</internal>
</WritingFunction>
The most simplest compiled wsp page looks like:
import submarine.core.*;
import submarine.util.*;
import submarine.pages.*;
import java.io.*;
import java.util.*;
import org.w3c.dom.*;
public class pagename_wsp_0 extends BaseWriterPage {
	public void run()  {
		// your code comes here
	}
}

The WSP Syntax

A wsp file is an xml file based on the http://submarine.sourceforge.net/pages namespace grammar. To have a detailed documentation of the WSP schemas (W3C standard) open submarine/pages/WriterPage.xsd and submarine/pages/BasePage.xsd in the submarine source package. The compilation of a WSP page is implemented by a XSLT stylesheet that transform the xml WSP file into a java text file. Finally, the java file is compiled with the Sun compiler.
This documentation will only shows the main interesting features of the WSP syntax.
The following example is a very simple WSP page that read the page configuration, merge it with the receive document, write something to the log and returns the result document.
<sub:WriterPage xmlns:sub="http://submarine.sourceforge.net/pages">
	<!-- import some classes into the java code -->
	<sub:import package="com.company.project.*"/>
	<!-- declare an internal class -->
	<sub:declaration>
		private static class myclass { public int i; };
	</sub:declaration>
	<!-- ensure the request is a xml document -->
	<sub:java>Document docRequest=(Document)request;</sub:java>
	<sub:java>
		try { // Start a try statement that will be closed later
	</sub:java>
	<!-- Get the interesting header element in the internal xml element of the configuration -->
	<sub:var name="header">
		<sub:copy-of var="xmlConfig" select="/header[@id]"/>
	</sub:var>
	<!-- Merge of the configuration and the request into a DOC -->
	<sub:var name="docResponse"><sub:as-document>
		<DOC xmlns="http://www.company.com/mydoc">
			<sub:copy-of var="header"/>
			<BODY>
				<sub:copy-of var="docRequest" select="/*"/>
			</BODY>
		</DOC>
	</sub:as-document></sub:var>
	<sub:java>
		System.out.println("The response document have been created and returned ");
		// returns the DOC document.
		response=docResponse;
		} catch(Exception e) {
			System.err.println("Error detected :"+e);
			e.printStackTrace(System.err);
		}
	</sub:java>
</sub:WriterPage>


sub:WriterPage

This element is the root element of a WSP page. It hold the submarine namespace : http://submarine.sourceforge.net/pages with conventionally the "sub" namespace prefix. You can use the prefix you want, include the default prefix, but remember that as for xslt stylesheet, xml elements you will manipulates does not have the submarine namespace.

possible children
nb
description
sub:import package=""
0,n
Add an import clause in the compiled class. The package attribute is the name of a package with the star (*) or a fully qualified class name.
sub:declaration
0,n
Add a java bloc of declarations in the compiled class, just before the run() method implementation of the wsp. This element allows to define functions and procedures, sub-classes that will be available in the run() method.
sub:java
0,n
Add a java bloc of instructions in the run() method. The java code can use any of the declared members submitter, request, response, context and xmlConfig.
sub:var name=""
0,n
Add a local variable declaration. The name of the variable is the name attribute.
sub:set name=""
0,n
Add a local variable setting. The new value of the variable is the content of the set element.
sub:*

others possible elements, see xml schema.

sub:var

The sub:var element add a local variable into the run() method of the wsp page.
If already define, the java compilation will failed.
The content of the var element will defined the type of the new variable. Any xml element outside the submarine namespace will be interpreted as a xml value for this variable.
The type of the variable will be
For instance :
<sub:var name="localvar">
	<elem att="value"/>
	<elem><item/></elem>
</sub:var>
Will be compiled to:
// Fragment declaration
DocumentFragment localvar =
	createFragment(new Node[] {
		createElement("elem", new Attr[] {createAttribute("att", "value")}, new Node[] { }),
		createElement("elem", new Attr[] {}, new Node[] {createElement("item", new Attr[] {}, new Node[] { }) }) });
possible children
nb
description
@var
1,1
The java name of the variable to declare.
sub:copy-of var="" select=""
0,n
duplicates nodes selected by the @select xpath query on the @var context
sub:value-of var="" select=""
0,n
get the string value of nodes selected by the @select xpath query on the @var context
sub:document file="" select=""
0,n
get the nodes selected by the @select xpath query on the @file xml document.
sub:as-document
0,n
cast the enclosed Element as a Document
sub :transform source="" template=""
0,n
Transform the @source var name using the XSLT @template var name stylesheet.
* | text()
0,n
Any element of any namespace and text nodes.

sub:set

Reset the value of an already defined variable.

possible children
nb
description
@var
1,1
The java name of the variable to set.
sub:copy-of var="" select=""
0,n
duplicates nodes selected by the @select xpath query on the @var context
sub:value-of var="" select=""
0,n
get the string value of nodes selected by the @select xpath query on the @var context
sub:document file="" select=""
0,n
get the nodes selected by the @select xpath query on the @file xml document.
sub:as-document
0,n
cast the enclosed Element as a Document
sub :transform source="" template=""
0,n
Transform the @source var name using the XSLT @template var name stylesheet.
* | text()
0,n
Any element of any namespace and text nodes.

sub:value-of

Get the text value of a node selection.
If the node is an attribute, the text is its value.
If the node is a text node, the text is its content.
If the node is a comment node, the text is its content.
If the node is an element node, the text is the value if all its children.
If the node is an a document fragment node, the text is the value if all its children.

possible children
nb
description
@var
1,1
The java name of the variable to evaluate.
@select
0,1
The xpath query to execute on the @var nodes. The default is "/" which means all nodes.

sub:copy-of

Duplicates the nodes returned by a node selection.

possible children
nb
description
@var
1,1
The java name of the variable to duplicate.
@select
0,1
The xpath query to execute on the @var nodes. The default is "/" which means all nodes.

sub:document

Load an xml document from a file and select some nodes from it using an xpath query.

possible children
nb
description
@file
1,1
The file name to load. The path name is relative to the virtual machine start directory.
@select
0,1
The xpath query to execute on the loaded document. The default is "/" which means all nodes.

sub:as-document

Force the creation of a dom document with the content of this element.
Only the first child element is used, the others are forgotten. Comments and processing instructions are kept. Documents or document fragments as children of this element raises an exception. If no child element is found an exception is raised.

possible children
nb
description
comment() | pi()
0,n
comments or processing instructions are duplicated.
*
1,n
At least one element is required to build the document


SubML is the name I gave to an XML syntax designed to communicate with the Submarine engine. SubML could be translated to Submarine Markup Language.
The SubML is very simple and is able to specify a message to be processed by the Submarine engine or a response and error from the engine.

SubMLSyntax

The root element is SubmarineML. No namespace have been defined in this syntax.

SubML connectors
SubmarineML
possible children
nb
description

@action
1,1
the type of the document:
  • request: ask for a document processing
  • response: a response to the request
  • error: an error produced by the request
@version
1,1
The actual version is "1.0". Greater version must be compatible.
Header
1,1
Element containing heading information
Body
1,1
Element containing the message request, response or error.

Header
possible children
nb
description

RouteInfos
0,1
Required in a request, it specify the routing information for the channel selection. See the RouteInfos description in "xml configuration file" chapter.
Context
1,1
Always required, it contains the context properties to configure the request or to complete the response.

Context
possible children
nb
description

attribute
0,n
element defining a named attribute.
attribute
@name
1,1
the name of the attribute.
text()
0,n
a text giving the value of the attribute.

Body
possible children
nb
description

@type
1,1
the type of message format :
  • text: message is a text
  • xml: message is an xml dom node
  • binary: message is an opaque binary stream
  • java: message is a Serializable java object
text()
0,1
contains the message if @type is "text", "binary" or "java". In the two last case, the binary message is encoded in base64.
node()
0,1
contains the xml dom node. If the node is an attribute, the attribute is added to the Body element. If the node is a document, only the document element is added. In all the other case, the node is copied to the Body node as a child.

SubMLListener

This class is a ListeningFunction designed to listen on a TCP port for client connection. Clients must send a SubML request message and can wait for a SubML response or error.
Once the listener receive a request it submits to the Submarine engine using the Header information and if the request is synchronous, wait for the channel result.
The number of concurrent clients could be limited in the configuration.

submarine.connectors.SubMLListener
Listen on
TCP/IP connection.

config
possible children
nb
description

port
1,1
The tcp port on which the server will listen on.
maxCnx
1,1
The number of concurrent clients the server will accept. It is not possible to define a no limit acceptance.
encoding
1,1
The encoding for the SubML message. Socket stream are enclosed with reader and writer with this encoding.

SubMLSerializer

This class is a Serializer designed to convert a SubMLInfos class into a SubML message and vice versa. This SubMLInfos class is a nested class of the SubMLSerializer.

submarine.connectors.SubMLSerializer
Parsed classes
submarine.connectors.SubMLSerializer.SubMLInfos
Serialized classes
submarine.connectors.SubMLSerializer.SubMLInfos

config
possible children
nb
description
 

SubMLClient

This class is not one of the core element but it is designed to be a simple API for Submarine engine from another process and machine, using the SubML connectors.
The following piece of java code shows how to simply send a message to Submarine from another java program.
SubMLClient cl=new SubMLClient("localhost",9091,"ISO-8859-1");
Object result=cl.submitSync("*", "*", "*", "channel-name",
				messageObject);
To use this class in your program you must add the clientEAI.jar of the bin package.

The JDBC connectors is a package in the Submarine distribution (submarine.connectors.jdbc) that contains a set of core elements for integration with a RDBMS system. Most of the RDBMS has their JDBC driver so it is interesting to use this technology to integrate with Submarine.
The concept choose to build integration with database is a pooling function (JDBCPooler) that try to find records in the database that match criteria sending these records as a xml document and then executing action after the submission in order to notify the database that the records were treated.
On the other side, if a system needs to send data to a database, the solution is to create sql queries in an xml document (easy to create with an xslt stylesheet) and use a connector (JDBCWriter) to performs the actions on the database.
These two way of integrating a database need to manage connections to the RDBMS. To do so, we use a Resource, shared by all the connectors that distributes connection from a pool (JDBCResource).

JDBCBatch and JDBC XML syntax

The JDBCBatch class is designed to encapsulate a set of queries and result to a database using a JDBC driver.
A JDBCBatch hold a list of Statement (an abstract class that represents a query on the database). There is today three types of statement. The CommentStatement that allow to deactivate a true statement or to add comment. The QueryStatement that encapsulate a sql dynamic command (select, update, delete, insert, create, drop, ...) and eventually a set of recordset (as XML element), result of a select query. The TransactionStatement that encapsulate transaction commit and rollback operations.
By default a JDBCBatch executes its statement on a connection in auto-commit to false and commit or rollback automatically the statements at the end.

A JDBCBatch instance could be transformed into XML or created from XML using the JDBCSerializer. The XML syntax used in this case is the following. Root element is "JDBCBatch"
The following format will be used by all the dates in the JDBC XML representations

JDBC connectors
Date
possible children
nb
description

@year
1,1
the year in 4 digits
@month
1,1
the month in 1 or 2 digits
@day
1,1
the day in 1 or 2 digits
@time
0,1
the time in format hh:nn:ss.msec

JDBCBatch
possible children
nb
description

@count
0,1
The number of statement in this batch. This attribute is not used for serialization (xml to object)
TimeStamp
0,1
The date and time of the batch serialization. This element contains a Date element.
Statement
0,n
A JDBC statement representation
StatementResult
0,n
A JDBC statement result representation
Error
0,n
A JDBC statement execution error

Statement
possible children
nb
description

@action
0,1
describe the type of statement: "commit", "rollback" and "comment". When not specify, it is a query statement.
@order
0,1
Specify the order of the statement among the others. This attribute is not used for serialization (xml to object)
text() and node()
0,1
the text of the statement for query and comment statements. The text is interpreted with the buildXPathString function during serialization.

Error
possible children
nb
description

@type
1,1
The fully qualified class name of the Exception
text()
1,1
The message of the generated Exception
SQLError
0,n
If the error is SQLException, these elements gives the internal sql error codes

SQLError
possible children
nb
description

@state
1,1
The SQLException.getSQLState() method result
@code
1,1
The SQLException.getErrorCode() method result
text()
1,1
The SQLException.getMessage()method result

StatementResult are never serialized when present in an xml element. StatementResult represents the result of a QueryStatement. It is possible with many database that multiple record set or lines updates are returned.

StatementResult
possible children
nb
description

@count
1,1
The number of result (Update or ResultSet) in this statement result.
Update
0,n
An update, delete or insert result that gives the number of rows affected by the command.
ResultSet
0,n
A select result that contains a list of rows.
Warnings
0,1
This element contains a list of warning and messages bring up by the database

Warnings
possible children
nb
description

Warning
0,n
This element represents a single warning

Warning
possible children
nb
description

@state
1,1
The SQLWarning.getSQLState() method return
@code
1,1
The SQLWarning.getErrorCode() method return
text()
1,1
The SQLWarning.getMessage() method return

Update
possible children
nb
description

@order
1,1
The position of this result among the other results in the StatementResult
@rowcount
1,1
The number of rows updated by the corresponding statement

ResultSet
possible children
nb
description

@order
1,1
The position of this result among the other results in the StatementResult
Cols
1,1
The records columns description (JDBC meta data).
Rows
1,1
The records
Warnings
0,1
The eventual warnings

Cols
possible children
nb
description

@count
1,1
The number of columns in the record set.
ColDesc
1,n
The description of one column

ColDesc
possible children
nb
description

@order
1,1
The position of this column among the others (first is 1)
@name
1,1
The column name
@label
1,1
The column label
@type
1,1
The column type code (see java.sql.Types)
@strType
1,1
The column type name
@size
1,1
The column display size
@precision
1,1
The column precision
@scale
1,1
The column scale

Rows
possible children
nb
description

@count
1,1
The number of records in the record set.
Row
1,n
The description of one column

Row
possible children
nb
description

@order
1,1
The position of this row among the others. First is 1
Col
1,n
The value of a column

Col
possible children
nb
description

@order
1,1
The position of the column. This order identify the column in the ColDesc list.
@null
0,1
‘true’ if the column value is null. Default is ‘false’.
text()
0,1
a string value of the value according to its type.
Date
0,1
if the type is a date, this is the Date element value.

JDBCPooler

This class is a pooling function designed to select records in a database, submit them to the Submarine engine and notify the database of the submission.
Select and notification to the database are implemented by executing a JDBCBatch on it.
The request is a set of statements constructed with buildXPathString at each wake up of the pooling function. But no xml context neither channel context could be used to parameterize the request with buildXPathString.
The result of the request batch is serialized into an xml document. This result is conform to the previously described syntax.
The documents submitted to Submarine are xml documents defined as following. A Submit element in the configuration tells which nodes to select in the request batch document result and how much nodes must be sent in each document.
After the submission of each document to Submarine, a JDBC batch is dynamically constructed from the AfterSubmit element of the configuration. This element can contain Bacth elements defining a set of statements to construct with the buildXPathString function, for each nodes selected by a xpath query on the request batch document result.

submarine.connectors.jdbc.JDBCPooler
Returned classes
org.w3c.dom.Document (see following syntax)
Attributes context
none

config
possible children
nb
description

JDBCRessource
1,1
a text giving the id of a JDBCResource from which the JDBC connection will be obtained. Take care of the double ‘s’ in the element name.
Request
1,1
An xml element interpreted with buildXPathString with no xml context and an empty attributes list. The value is a JDBCBatch used to select records. The content of this node follows the Statement syntax.
Submit
0,1
An xml element giving the xpath query to select the nodes to send to submarine and the number of these nodes in each returned document. If omitted, the default is an empty Submit element. See Submit detail.
AfterSubmit
1,1
An xml element interpreted as a JDBCBatch to execute after each document submission. The interpretation is done by buildXPathString with the submitted document as xml context and an empty attributes list.
frequency
1,1
a text giving the number of milliseconds to wait between each search in the directory.
RouteInfos
1,1
Routing information for the channels selection. See "xml configuration file" for the detail of this element.

Submit
possible children
nb
description

@select
0,1
An xpath query to execute on the Request batch result document. The default value is ‘.’ witch mean the JDBCBatch root element.
@count
0,1
A number that gives the maximum number of the selected nodes to put in the document sent to Submarine. If the value is ‘-1’, all the nodes are put in the same document. The default value is –1.

AfterSubmit
possible children
nb
description

Batch
0,n
A sub part of the batch to build for a submitted document.
Batch
@for-each
0,1
an xpath query on the submitted document giving a list of nodes used as context of the contained Statement.
node()
0,n
A list of Statement elements following the JDBCBatch syntax. The elements are interpreted for each node of the @for-each query by the buildXPathString function. The context node is the current selected node and the attribute list is empty.

The submitted document to Submarine are dom document which root element is "JDBCResult" containing the nodes selected by the Submit/@select xpath query.

An example will show you more concretely how it works. Lets say we have a table CUSTOMER with an id (int), a name (varchar) and a phone number (varchar). A replication process could be done by the following Submarine configuration. A REPLIC_ST table will contains the customers id already replicated.
...
<PoolingFunctions>
	<PoolingFunction
		id="replicator"
		class="submarine.connectors.jdbc.JDBCPooler">
		<JDBCRessource>TheResource</JDBCRessource>
		<Request>
			<Statement>select * from CUSTOMER
				where id not in (select id from REPLIC_ST)
			</Statement>
		</Request>
		<Submit
			select="StatementResult[ResultSet/Rows/Row]"
			count="10"/>
		<AfterSubmit>
			<Batch for-each="StatementResult/ResultSet/Rows/Row">
				<Statement>insert into REPLIC_ST (id, statut)
				values (<value-of select="Col[@order=1]"/>, 'OK')
				</Statement>
			</Batch>
			<Batch for-each=".">
				<Statement action="commit"/>
			</Batch>
		</AfterSubmit>
		<RouteInfos>
			<source>*</source>
			<destination>*</destination>
			<msgType>*</msgType>
			<channel>A channel name</channel>
			<sync>true</sync>
		</RouteInfos>
		<frequency>10000</frequency>
	</PoolingFunction>
	...
</PoolingFunctions>
...

JDBCRessource

This class is a Resource designed for holding a pool of JDBC connections.

submarine.connectors.jdbc.JDBCRessource
Multiple instance
yes

config
possible children
nb
description

driver
1,1
The fully qualified class name of the JDBC driver to use
url
1,1
The url of the database according to the driver documentation
login
1,1
the login of the connections
passwd
1,1
the password associated with the login
InitialSize
1,1
The initial number of connections the resource will open at startup time.
MaxSize
1,1
The maximum number of connections the resource will keep opened
MaxExtend
1,1
The maximum number of connections used simultaneously. If a client query for a connection and the MaxExtend have been reach, the calling thread waits for a connection release.

JDBCSerializer

This class is a Serializer designed for transformation of a JDBCBatch into an XML document and vice versa. The syntax of the XML document is described in the JDBCBatch chapter.
Important note:
Serialization from xml to JDBCBatch only concerns the Statement elements. Serialization ignores Error and StatementResult element.
Parsing from JDBCBatch to xml create all the elements (Statement, StatementResult and Error) correctly.

submarine.connectors.jdbc.JDBCSerializer
Parsed classes
submarine.connectors.jdbc.JDBCBatch
Serialized classes
submarine.connectors.jdbc.JDBCBatch

config
possible children
nb
description

JDBCWriter

This class is a writing function designed to execute a JDBCBatch object on a database connection. The writer takes a JDBCBatch instance from the channel and query a connection from the JDBCResource. It executes the batch on the connection, release the connection and finally returns the completed batch object.

submarine.connectors.jdbc.JDBCWriter
Accepted classes
submarine.connectors.jdbc.JDBCBatch
Synchronous
supported
Asynchronous
not supported. Done synchronously.

config
possible children
nb
description

JDBCRessource
1,1
a text giving the id of a JDBCResource from which the JDBC connection will be obtained. Take care of the double ‘s’ in the element name.