submarine.core
Class EAISystem

java.lang.Object
  |
  +--submarine.core.EAISystem

All Implemented Interfaces:

ConnectorsControler, java.lang.Runnable, Submiter

public class EAISystem

extends java.lang.Object

implements java.lang.Runnable, Submiter, ConnectorsControler

The main class of the Submarine project. It contains the rules of the EAI engine and it drives the plugins (connectors) of the system. This class implements Runnable so it can be launch as a Thread in an existing program or as a standalone program using a very simple class.

This class is used typically in the way of the following sample :

 try {
 	EAISystem eai=new EAISystem();
 	eai.setConfig("config-file.xml");
 	Thread th = new Thread(eai);
 	th.start();
 } catch(Exception e) {
 	System.err.println("Exception in main "+e);
 }
 

The setConfig call, initializes the PoolingFunctions, the ListeningFunctions, creates the WritingFunctions, prepares the Channels and the Resources.

The Submarine architecture project is :

 .|--------------------|   
 .|  ListeningFunction |
 .|--------------------|    /-java.lang.Object--\    |-----------------------------------------|
 .                  \      /                     \   | Channel     X           X                |
 .                   \---------->|-------------| |   |            M           M                |
 .                               |  EAISystem  |---->|  |--------|L  |------| L |------------| |
 .                   /---------->|-------------|     |  | Parser |-->| XSLT |-->| Serializer | |
 .                  /                                |  |--------|   |------|   |------|-----| |
 .|--------------------|                             |---^-----------------------------|-------|
 .|  PoolingFunction   |                         |                     java.lang.Object|
 .|--------------------|                        |--------|-----|            |----------V------|
 .                                              |   Resource   |            | WritingFunction |
 .                                              |--------------|            |-----------------|
 

Description :

EAISystem receive messages of type java.lang.Object from two kind of interfaces. ListeningFunctions submit to EAISystem the messages joined to routing information. PoolingFunctions are lauched at a defined frequency by the EAISystem and supply messages implementing the function getNextDocument. In both cases messages are received by the function submit and added in the queue if message is asynchronous. If the message is synchronous, it is directly supplied to the Channel's submit function.( In this case an instance of the Channel is created. Asynchronous messages waiting in the queue are taken out by a Thread in the pool of Thread-Channel. Then it is executed by the Channel.

A Channel execute a message following the steps of a Channel.

At the end of the processing, the resulting message is submited synchronously or asyncronousely to a WritingFunction.

Inner Class Summary

static class	EAISystem.ErrorObject Classe servant à encapsuler un message soumis au systeme accompagnée d'une erreur détectée.
private class	EAISystem.RunListeningFunction Classe Runnable interne à EAISystem et destinée à lancer une ListeningFunction.
private class	EAISystem.RunPoolingFunction Classe Runnable interne à EAISystem et destinée à lancer une PoolingFunction.
static class	EAISystem.Tools Une classe contenant des méthodes statiques utiles pour la manipulation du XML et autre.

Field Summary

private java.text.SimpleDateFormat	_id_format
private java.io.File	archivePath
private boolean	bReloadConfig used to indicate the server to reload its configuration at the next stop() call function.
private java.util.Hashtable	channelInfos Channels list as defined in the configuration file.
private int	ChannelThreadCount The maximum number of concurrent Channel-Thread.
private java.lang.String	configFile the default configuration file name.
private java.lang.String	encoding The file encoding for archives files and errors.
SyncQueue	errorQueue
private ListeningFunction	internalListener a special Listening function used to handle the server using telnet connection.
static java.lang.String	jndiConnectorsControler
static java.lang.String	jndiSubmiter
private java.util.Hashtable	listeningFunctions
static java.lang.String	mainXMLElement The main XML element tag that should appears in the configuration file.
private java.util.Hashtable	poolingFunctions
private java.util.Hashtable	resources The Resources list shared by the connectors list as defined in the configuration file.
private java.lang.Thread	runThread
private java.lang.String	serverId The string identifier for the server.
private boolean	stopping
private java.util.Vector	threads List all the internally managed threads.
private long	txCounter The last number used to create a message id.
SyncQueue	waitingQueue The queue in which the asynchronous messages arrives.
private java.util.Hashtable	writingFunctions WritingFunctions list as defined in the configuration file.

Constructor Summary

EAISystem()
Default constructor.

Method Summary

void	archive(java.lang.String Channel, java.lang.Object message, Message.MsgContext ctx, int type) Archive un message pendant ses différentes phases de transformation par le Channel.
private void	createChannelInfos(org.w3c.dom.Element elm) Initialise une nouvelle instance de ChannelInfos à partir d'un élément XML.
private void	createListeningFunction(org.w3c.dom.Element elm) Crée une nouvelle ListeningFunction à partir d'un élément XML.
private void	createPoolingFunction(org.w3c.dom.Element elm) Create a new PoolingFunction from an XML element.
private void	createResource(org.w3c.dom.Element elm) Crée une nouvelle Resource à partir d'un élément XML.
private void	createWritingFunction(org.w3c.dom.Element elm) Create a new WritingFunction from an XML element.
ChannelInfos	getChannelByName(java.lang.String name) Retreive a ChannelInfos from its name.
ConnectorsControler	getControler() returns the ConnectorsControler interface of the system. implementation of the SubmiterAware interface.
ListeningFunction	getListenerById(java.lang.String id) Retreive a ListeningFunction from its id.
private java.lang.String	getNewDocId() Crée un nouvel identifiant de document unique dans le systeme.
PoolingFunction	getPoolerById(java.lang.String id) Retreive a PoolingFunction from its id.
Resource	getResourceById(java.lang.String id) Retreive a Resource from its name.
WritingFunction	getWriterById(java.lang.String id) Retreive a WritingFunction from its id.
private void	includeFiles(org.w3c.dom.Document doc, java.util.List redFiles)
private void	initSubmiterAware(java.lang.Object o) Gives the Submiter interface of the Server to an object if its implements interface SubmiterAware.
void	manageError(Message m, java.lang.String error) Traite une erreur intervenue durant l'exécution d'un Channel ou d'un connecteur.
private boolean	matchChannel(RouteInfos ri, ChannelInfos ci, java.lang.String ChannelName) Détermine si un Channel correspond aux informations de routages fournies.
void	printQueues(java.io.PrintWriter pout) Affiche les files d'attente et d'erreur sur le printer.
void	restart()
void	run() Implémentation de Runnable.
protected java.lang.String[]	selectChannels(RouteInfos infos) Calcule la liste des noms de Channels pouvant correspondre aux informations de routages.
private void	setConfig(org.w3c.dom.Document doc)
void	setConfig(java.lang.String fileName) Cette méthode initialise le système EAI à partir d'un fichier de configuration XML.
void	stop() Interrompt tous les threads lancé explicitement par le système et notifie le thread principal qui a lancé run().
java.lang.Object	submit(java.lang.Object message, RouteInfos infos) Soumet un message au Submiter.
java.lang.Object	submit(java.lang.Object message, RouteInfos infos, Message.MsgContext context) Utilisé pour soumettre un nouveau message au systeme.

Methods inherited from class java.lang.Object

, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait

Field Detail

mainXMLElement

public static final java.lang.String mainXMLElement

The main XML element tag that should appears in the configuration file. Could be changed if you want another.

jndiSubmiter

public static final java.lang.String jndiSubmiter

jndiConnectorsControler

public static final java.lang.String jndiConnectorsControler

ChannelThreadCount

private int ChannelThreadCount

The maximum number of concurrent Channel-Thread. This value is define in the configuration file.

serverId

private java.lang.String serverId

The string identifier for the server. Used to marks the message id. This value is define in the configuration file.

txCounter

private long txCounter

The last number used to create a message id. When the value reach 9999 it is reset to 0.

encoding

private java.lang.String encoding

The file encoding for archives files and errors.

channelInfos

private java.util.Hashtable channelInfos

Channels list as defined in the configuration file.

writingFunctions

private java.util.Hashtable writingFunctions

WritingFunctions list as defined in the configuration file.

poolingFunctions

private java.util.Hashtable poolingFunctions

listeningFunctions

private java.util.Hashtable listeningFunctions

resources

private java.util.Hashtable resources

The Resources list shared by the connectors list as defined in the configuration file.

internalListener

private ListeningFunction internalListener

a special Listening function used to handle the server using telnet connection.

threads

private java.util.Vector threads

List all the internally managed threads.

archivePath

private java.io.File archivePath

runThread

private java.lang.Thread runThread

stopping

private boolean stopping

bReloadConfig

private boolean bReloadConfig

used to indicate the server to reload its configuration at the next stop() call function.

configFile

private java.lang.String configFile

the default configuration file name.

waitingQueue

public SyncQueue waitingQueue

The queue in which the asynchronous messages arrives.

errorQueue

public SyncQueue errorQueue

_id_format

private java.text.SimpleDateFormat _id_format

Constructor Detail

EAISystem

public EAISystem()

Default constructor. Initialize to the default values and force the XML parsers to uses org.apache.xerces.jaxp.DocumentBuilderFactoryImpl to create XML documents.

Method Detail

getWriterById

public WritingFunction getWriterById(java.lang.String id)

Retreive a WritingFunction from its id. Implementation of the ConnectorsControler interface.

Specified by:

getWriterById in interface ConnectorsControler

Parameters:

name - The name of the WritingFunction the function should returns.

Returns:

submarine.core.WritingFunction

getListenerById

public ListeningFunction getListenerById(java.lang.String id)

Retreive a ListeningFunction from its id. Implementation of the ConnectorsControler interface.

Specified by:

getListenerById in interface ConnectorsControler

Parameters:

name - The name of the ListeningFunction the function should returns.

Returns:

submarine.core.ListeningFunction

getPoolerById

public PoolingFunction getPoolerById(java.lang.String id)

Retreive a PoolingFunction from its id. Implementation of the ConnectorsControler interface.

Specified by:

getPoolerById in interface ConnectorsControler

Parameters:

name - The name of the PoolingFunction the function should returns.

Returns:

submarine.core.PoolingFunction

getChannelByName

public ChannelInfos getChannelByName(java.lang.String name)

Retreive a ChannelInfos from its name. Implementation of the ConnectorsControler interface.

Specified by:

getChannelByName in interface ConnectorsControler

Parameters:

name - The name of the ChannelInfos the function should returns.

Returns:

submarine.core.ChannelInfos

getResourceById

public Resource getResourceById(java.lang.String id)

Retreive a Resource from its name. Implementation of the ConnectorsControler interface.

Specified by:

getResourceById in interface ConnectorsControler

Parameters:

name - The name of the Resource the function should returns.

Returns:

submarine.core.Resource

getControler

public ConnectorsControler getControler()

returns the ConnectorsControler interface of the system. implementation of the SubmiterAware interface.

Specified by:

getControler in interface Submiter

initSubmiterAware

private void initSubmiterAware(java.lang.Object o)

Gives the Submiter interface of the Server to an object if its implements interface SubmiterAware.

Parameters:

o - The object that should implements SubmiterAware.

createWritingFunction

private void createWritingFunction(org.w3c.dom.Element elm)

Create a new WritingFunction from an XML element.

This XML element should follows the syntax :
No control is made on the given element tag name.

 <WritingFunction id="writing function name" class="package.class"/>
 <!-- @id identify the WritingFunction uniquely -->
 <!-- @class is the class name which implements interface WritingFunction -->
 <!-- A WritingFunction implements XMLConfigurable. After its creation, 
 	 the new instance receive the same XML element in order to initialize 
 	 specific informations. See the specific documentation class. -->
 

Parameters:

elm - XML element following this syntax.

createPoolingFunction

private void createPoolingFunction(org.w3c.dom.Element elm)

Create a new PoolingFunction from an XML element.

This XML element should follows the syntax :
No control is made on the given element tag name.

 <PoolingFunction id="pooling function name" class="package.class">
 <!-- @id identify th PoolingFunction uniquely -->
 <!-- @class is the class name which implements interface WritingFunction -->
 <!-- A WritingFunction implements XMLConfigurable. After its creation, 
 	 the new instance receive the same XML element in order to initialize 
 	 specific informations. See the specific documentation class. -->
 	 <!-- A pooling function need to parameter the frequency
 		 and the routing information 
 		 so it is recomanded to have the two following elements: -->
 	<RouteInfos>
 	 <!-- see RouteInfos.init for content details -->
 	</RouteInfos>
 	 <!-- frequency in ms -->
 	<frequency>1000</frequency>
 </PoolingFunction>
 

Parameters:

elm - L'élément XML devant suivre cette syntaxe.

createListeningFunction

private void createListeningFunction(org.w3c.dom.Element elm)

Crée une nouvelle ListeningFunction à partir d'un élément XML.

Cet élément XML doit suivre la syntaxe suivante :
Aucune vérification n'est faite sur le nom de l'élément dans cette fonction.

 <ListeningFunction id="nom de la listening function" 
 class="package.class"/>
 <!-- @id identifie la ListeningFunction de manière unique -->
 <!-- @class est la classe qui doit implémenter l'interface ListeningFunction 
 -->
 <!-- Une ListeningFunction implémente XMLConfigurable. Après sa 
 construction, l'instance
 	 reçoit ce même élément pouvant contenir des informations spécifiques à la 
 classe
 	 reportez-vous à la documentation propre de la classe. -->
 

Parameters:

elm - L'élément XML devant suivre cette syntaxe.

createResource

private void createResource(org.w3c.dom.Element elm)

Crée une nouvelle Resource à partir d'un élément XML.

Cet élément XML doit suivre la syntaxe suivante :
Aucune vérification n'est faite sur le nom de l'élément dans cette fonction.

 <Resource id="nom de la listening function" class="package.class"/>
 <!-- @id identifie la Resource de manière unique -->
 <!-- @class est la classe qui doit implémenter l'interface Resource -->
 <!-- Une Resource implémente XMLConfigurable. Après sa construction, l'instance
 	 reçoit ce même élément pouvant contenir des informations spécifiques à la classe
 	 reportez-vous à la documentation propre de la classe. -->
 

Parameters:

elm - L'élément XML devant suivre cette syntaxe.

createChannelInfos

private void createChannelInfos(org.w3c.dom.Element elm)

Initialise une nouvelle instance de ChannelInfos à partir d'un élément XML.

La syntaxe de cet élément suit les règles suivantes :

 <Channel name="Channel name">
 	<!-- @name identifie de façon unique le Channel -->
 	<!-- Le contenu de cet élément est décrit dans ChannelInfos.init -->
 </Channel>
 

Parameters:

elm - l'élément à partir duquel le ChannelInfos est initialisé

setConfig

public void setConfig(java.lang.String fileName)

Cette méthode initialise le système EAI à partir d'un fichier de configuration XML.

La syntaxe XML attendue est la suivante:

 <submarine>
 	<global> <!-- Les informations configurant le serveur lui-même 
 -->
 		<server id="server-id"/>
 		<listener port="9999"/> <!-- internal listener port -->
 		<archive path="archive" encoding="ISO-8859-1"/>
 			<!-- répertoire en encodage de l'archivage des messages -->
 		<threads count="3"/>
 			<!-- Nombre de Thread-Channel créés pour traiter les messages 
 -->
 	</global>
 	<Includes>
 <!-- Included files have the same syntax and can also include files. -->
 	<	Include file="a-file.xml"/>
 	</Includes>
 	<PoolingFunctions>
 		<PoolingFunction/> <!-- voir le 
 détails -->
 	</PoolingFunctions>
 	<ListeningFunctions>
 		<ListeningFunction/> <!-- voir le détails -->
 	</ListeningFunctions/>
 	<Channels>
 		<Channel/> <!-- voir le détails 
 -->
 	</Channels>
 	<WritingFunctions>
 		<WritingFunction/> <!-- voir le 
 détails -->
 	</WritingFunctions>
 </submarine>
 

Parameters:

fileName - le nom complet du fichier xml contenant la configutation. Ce fichier peut être encodée de façon standard (UTF-8, UTF-16, ISO-xxxx-x). Le parser utilisé est xerces.

includeFiles

private void includeFiles(org.w3c.dom.Document doc,
                          java.util.List redFiles)
                   throws java.lang.Exception

setConfig

private void setConfig(org.w3c.dom.Document doc)
                throws java.lang.Exception

stop

public void stop()

Interrompt tous les threads lancé explicitement par le système et notifie le thread principal qui a lancé run(). Cette methode arrête le système EAI.

restart

public void restart()

manageError

public void manageError(Message m,
                        java.lang.String error)

Traite une erreur intervenue durant l'exécution d'un Channel ou d'un connecteur.

Le traitement consiste en l'écriture d'un fichier dans le répertoire d'erreur du Channel.

Puis si le Channel contient un element on-error-writer, celui-ci est appelé de façon synchrone en donnant un EAISystem.ErrorObject en valeur d'entrée

Parameters:

m - Le message en cours de traitement.

error - Le message d'erreur.

run

public void run()

Implémentation de Runnable.

Les étapes sont les suivantes :

Lance les threads pour
• les Thread-Channels,
• les ListeningFunctions,
• les PoolingFunctions.

Puis

• Charge éventuellement la dernière queue de messages persistante.
• Attends que le thread courrant soit notifié de son arrêt.
• Rends éventuellement persistent la file d'attente des messages.
• Se termine.

Specified by:

run in interface java.lang.Runnable

matchChannel

private boolean matchChannel(RouteInfos ri,
                             ChannelInfos ci,
                             java.lang.String ChannelName)

Détermine si un Channel correspond aux informations de routages fournies.

L'algorithme est le suivant :

• Si ri.Channel=ChannelName alors le Channel est sélectionné.
• Si ri.Channel!="*" alors le Channel ne peut pa être sélectionné. "*" représente tous les Channels.

Les trois conditions suivantes doivent être vrai pour sélectionner le Channel:

• ri.source="*" ou ri.source=ci.source
• ri.destination="*" ou ri.destination=ci.destination
• ri.msgType="*" ou ri.msgType=ci.msgType

Parameters:

ri - Les informations de routages

ci - Les informations du Channel

ChannelName - Le nom du Channel

Returns:

boolean

selectChannels

protected java.lang.String[] selectChannels(RouteInfos infos)

Calcule la liste des noms de Channels pouvant correspondre aux informations de routages. L'ensemble des Channels sélectionnés sera utilisé pour émettre le document. Un Channel est sélectionné si matchChannel() retourne vrai.

Parameters:

infos - Les informations de routage.

Returns:

String[] Un tableau toujours non null contenant les noms des Channels devant traiter le message envoyé avec ces informations de routages.

printQueues

public void printQueues(java.io.PrintWriter pout)

Affiche les files d'attente et d'erreur sur le printer.

Parameters:

pout - Le flux devant recevoir les informations sur les files.

getNewDocId

private java.lang.String getNewDocId()

Crée un nouvel identifiant de document unique dans le systeme.

Cet identifiant est une chaine construite de la manière suivante:
l'identifiant du serveur,
la date systeme au format yyyyMMdd,
l'heure systeme au format HHmmss,
la valeur courante de txCounter.

Returns:

String

submit

public java.lang.Object submit(java.lang.Object message,
                               RouteInfos infos,
                               Message.MsgContext context)

Utilisé pour soumettre un nouveau message au systeme.

Specified by:

submit in interface Submiter

Parameters:

message - Le message à soumettre.

infos - Les informations de routages.

Returns:

java.lang.Object Si la soumission est synchrone, la fonction retourne la réponse de la WritingFunction. Sinon le docId est retourné.

submit

public java.lang.Object submit(java.lang.Object message,
                               RouteInfos infos)

Description copied from interface: Submiter

Soumet un message au Submiter.
La valeur retournée peut être l'un des cas suivants:

• La valeur de retour de la WritingFunction du Channel, si la soumission est Synchrone.
• Le docId de la soumission, si celle-ci est asynchrone.
• Une Exception si une erreur s'est produite durant le traitement de la soumission.

Specified by:

submit in interface Submiter

Following copied from interface: submarine.core.Submiter

Parameters:

message -

infos -

Returns:

java.lang.Object

archive

public void archive(java.lang.String Channel,
                    java.lang.Object message,
                    Message.MsgContext ctx,
                    int type)

Archive un message pendant ses différentes phases de transformation par le Channel. Cette méthode crée un fichier dans le répertoire dédié du Channel. L'objet est archivé de la manière suivante:

• Si le message implémente Archivable, la méthode archive est utilisée.
• Si le message est un Document XML (org.w3c.xml.Document) il est écrit dans un fichier à l'aide de Tools.archiveXML.
• Si le message est une instance de String, la chaîne est écrite dans le fichier en utilisant l'encodage prévu dans la configuration.
• Si le message implémente Serializable, il est sérialisé dans le fichier.
• Dans les autres cas, une chaîne donnant la classe et la représentation en String de l'object est écrite dans le fichier en utilisant l'encodage.

Parameters:

Channel - Le nom du Channel. Servira à choisir le répertoire à utiliser ou a créer dans le répertoire d'archive définis dans le serveur.

message - L'objet à archivé.

ctx - Le contexte du message. Le docId servira à construire le nom du fichier.

type - Le type d'archive. Voir ChannelInfos.archive.