Classes and their uses including Property File Examples and required Values
Back to Table of Contents

The main Classes are:

Transfer
TransferEngine
GenerateMap
MapEngine
ParserUtils
ProcessXSLT
JMSWrapper

Base level classes

ProcessProperties
GetFile

Utility Classes

GeneratePropFile
XMLDBMS (GUI)

Transfer
Back to Classes

Use:

java de.tudarmstadt.ito.xmldbms.tools.Transfer args[]
e.g.
java de.tudarmstadt.ito.xmldbms.tools.Transfer File=mypropertiesfile

Transfer processes the properties which you feed in and takes the Action as defined by the "Action=" property.
The Public methods are the programmable ones (if you wish to wrap Transfer within your own code).
If you wish to use Transfer on it's own (i.e. not wrapped in your own class / logic) then have a look at the JavaDoc for the class.

Property File Values required for Different Transfer Actions

Programming

Obviously if you are using Transfer within a wrapper then you'd probably not want to use an XML File as Input / output but rather a string.
The basic rule is where the method ends with "_s" it either takes an xml file as a String input (e.g. dispatchStoreDocument_s) or returns the XML as a String (e.g. dispatchRetrieveDocumentByKey_s). i.e if you were passing in a text message (String msg1) obtained via JMS you might call:

TransferEngine te = new TransferEngine();
Transfer e = new Transfer();
te.init(props);
e.dispatchStoreDocument_s(te, props, msg1);


or if you wanted to fetch some xml from a db & send it as a string you might use:

TransferEngine te = new TransferEngine();
Transfer e = new Transfer();
te.init(props);
String message = e.dispatchRetrieveDocumentByKey_s(te,props);



TransferEngine
Back to Classes
The TransferEngine is not usually called directly from code.

The Best way (and the way I would recomend) is to call it from Transfer as seen in the above piece of code.
You initialize the TransferEngine by simply calling init and providing it with a properties object as the argument.
It uses this to set up the Parser, the JDBC info etc.
TransferEngine (in it's createMap() method) uses the Object Cache to stored map Objects which means it only needs to create a map object once and then it can reuse the object thus speeding up map object handling quite a lot (in long running processes).

GenerateMap
Back to Classes

GenerateMap is similar to Transfer in that it is an easy to use class which process'es the properties you feed in & then starts MapEngine in order to Generate a Map.

It is designed to be used simply to produce mapfiles.

Use:

java de.tudarmstadt.ito.xmldbms.tools.GenerateMap args[]
e.g.
java de.tudarmstadt.ito.xmldbms.tools.GenerateMap File=mypropertiesfile

GenerateMap processes the properties which you feed in and takes the Action as defined by the "Action=" property.

Property File Values required for Different Generate Map Actions

MapEngine
Back to Classes

The MapEngine is similar to TransferEngine and is also not usually called directly from code.

The Best way (and the way I would recomend) is to call it from Generatemap.

ParserUtils
Back to Classes

The ParserUtils Interface is used to set up the system for different Parsers.
I am including this in the list purely for the programmers reading this as some of the methods are usefull if chaining different actions together (see ProcessXSLT).

In essence look at the JavaDoc / Interface as the methods are usefull as of and by themselves if you are wrapping XML-DBMS code in your own and wish to manipulate the XML Document. As an example, the JAXP ParserUtil provides most of the stuff "missing" from JAXP e.g. the ability to write out a document.

ProcessXSLT
Back to Classes

ProcessXSLT works via an XSLTLoader which then loads a class which implements ProcessXslt Interface. Both Xalan 1 & 2 are supported. There is a small engine called XSLTest which allows you to run XSLT scripts in the same way as Transfer and GenerateMap.

Use:

de.tudarmstadt.ito.xmldbms.xslt.XSLTest args[]
e.g.
java de.tudarmstadt.ito.xmldbms.xslt.XSLTest File=mypropertiesfile

Property File Values required for Different XSLT Actions

The point of the design (as you will see with the JMS code as well) is that given a common properties object, chains of string handling can be marshalled either going from XML > SQL & vice versa. Given large and complex DTD'es such as the Biztalk/Oagi etc and a set of (possibly unchangeable) SQL tables to map them to you will like this.

Given the example used in the Transfer section:
To transform an "outgoing" (i.e. DB to XML) file/string

TransferEngine te = new TransferEngine();
Transfer e = new Transfer();
te.init(props);
String message = e.dispatchRetrieveDocumentByKey_s(te,props);
XSLTLoader xs = new XSLTLoader();
processxslt = xs.init(props);
String Message1 = processxslt.transformString(message, props.getProperty(XMLDBMSProps.XSLTScript));

To transform an "incoming" (i.e. XML to DB) file/string

XSLTLoader xs = new XSLTLoader();
processxslt = xs.init(props);
String msg1 = processxslt.transformString(msg, props.getProperty(XMLDBMSProps.XSLTScript));
TransferEngine te = new TransferEngine();
Transfer e = new Transfer();
te.init(props);
e.dispatchStoreDocument_s(te, props, msg1);

ProcessXSLT1 & 2 (along with de.tudarmstadt.ito.xmldbms.tools.ProcessProperties and de.tudarmstadt.ito.xmldbms.TransferEngine)use the object cache. i.e. once an XSLT Sheet has been processed once then the Processed Sheet / Object is held in the Object Cache and that is retrieved thus saving on processing the sheet everytime (if running in a long running process).

JMSWrapper
Back to Classes

de.tudarmstadt.ito.xmldbms.jms.JMSWrapper is a catch all Class for doing JMS messaging.
It can send & receive & it's even got an "onMessage(Message)" method to have a go with.
It's fairly simple to write to but looking at the 2 User Useable classes (using the good old File=property file command line as with everything else) should show you that.
It should handle most proper JMS servers & even handles SonicMQ w/o trouble (SonicMQ does not use an Initial Context). The 2 User Classes are:

JMSTest which sends messages

and

JMSTestRec which receives messages


Use:

de.tudarmstadt.ito.xmldbms.jms.JMSTest args[]
e.g.
de.tudarmstadt.ito.xmldbms.jms.JMSTest File=mypropertiesfile

Use:

de.tudarmstadt.ito.xmldbms.jms.JMSTestRec args[]
e.g.
de.tudarmstadt.ito.xmldbms.jms.JMSTestRec File=mypropertiesfile

Note: It is possible to send Java objects via JMS. In the JMSwrapper is a test receive method receiveTestObj() and a send method send(ArrayList message) which is built to demonstrate this using an ArrayList. It could be adapted to any serializable object.
I have played with sending Properties Objects & even the entire ObjectCache via JMS and it works. This could be used to scale an "XMLDBMS Server" Horizontally (i.e many Appservers serving / storing XML docs from / into a single DB).



Given the example used in the XSLT section:
To transform an "outgoing" (i.e. DB to XML) file/string and send it

TransferEngine te = new TransferEngine();
Transfer e = new Transfer();
te.init(props);
String message = e.dispatchRetrieveDocumentByKey_s(te,props);
XSLTLoader xs = new XSLTLoader();
processxslt = xs.init(props);
String Message1 = processxslt.transformString(message, props.getProperty(XMLDBMSProps.XSLTScript));
JMSWrapper j = new JMSWrapper();
j.init(props1);
j.send(Message1);

Property File Values required for Different JMS Actions

Base Classes
Back to Classes

These classes provide support services to XMLDBMS. You can use them all over the place as they are very usefull.

It should be pointed out that these classes are for developers as otherwise they simply act as invisible support for the rest of the code.

ProcessProperties
Back to Classes

de.tudarmstadt.ito.xmldbms.tools.ProcessProperties is the class which loads & process'es properties files. All classes which can be started directly using the commandline / properties file (e.g. Transfer, JMSTest etc) all extend ProcessProperties e.g.

public class GenerateMap extends ProcessProperties

It has one central method getProperties(String[] args, int start) The Int start gives the arg number to start the processing from. Usually it is 0. The class is small and simple and is one of the few to use the ObjectCache.
The best thing is again to look at the code as it's (hopefully) fairly simple.


GetFile
Back to Classes

de.tudarmstadt.ito.xmldbms.tools.GetFile is an interface to allow for the abstraction of retrieving files. It is implemented via 2 Classes:

de.tudarmstadt.ito.xmldbms.tools.GetFileJNDI

and

de.tudarmstadt.ito.xmldbms.tools.GetFileURL

The GetFileJNDI works but I'm not too happy with the solidity of fetching files via JNDI at the moment. Maybe I am just unlucky but fetching (even text files such as property files) was a bit dodgy & slow & hard to set up (vs setting up a webserver to serve the files). As such I've left the class there for when / if someone wants to store /retrieve their files (XSLT,Properties, map files) using JNDI e.g. using LDAP but it's unused at the moment.

GetFileURL will load files from any source handled by the Java URL class, local files and Jar files.

My favourite because of it's speed and simplicity is to use http. I would caution that there is a bug (not in our code) which prevents loading an XML file from a jar/zip file where the dtd is also stored in the jar/zip & the reference points to the jar. i.e if using the jar loading to load resources then the XML files must either
(a) not have a DOCTYPE declaration or
(b) it must reference somewhere other than the jar file (e.g. a http url).
GetFileURL also has a method called public String fullqual(String filename) which returns a fully qualified path to the file e.g. file:/// etc.
To load from a jar simply address the file as /filename or /directoryinZipFile/filename.


Utility Classes
Back to Classes

GeneratePropFile
Back to Classes

de.tudarmstadt.ito.xmldbms.tools.GeneratePropFile is a very simple commandline class which is simply used to turn a commandline and / or a set of property files into a single property file.


XMLDBMS
Back to Classes

de.tudarmstadt.ito.xmldbms.gui.XMLDBMS is a sort of proto-GUI (Graphical User Interface). I have been rethinking what's needed as a GUI. Anyway it helps with creating properties files. It does not help with creating mapfiles or XSLT sheets.


Example Properties Files
Back to Table of Contents

1. JMS
2. XSLT
3. Generate Map:
1. CreateMapFromDTD
4. Transfer:
1. StoreDocument
2. RetrieveDocumentBySQL
3. RetrieveDocumentByKey
4. RetrieveDocumentByKeys
5. Example "Admin" (Global) File

Example JMS Properties Files
Back to Example Properties Files

Here is an example of using the JMSTest class to send a file (D\:\\aat\\rt\\test1.xml) to a topic called testtopic located on a machine called MyMachine using Weblogic once (set by the JMSTestNum=1)

JMSContext=weblogic.jndi.WLInitialContextFactory
JMSProviderURL=t3://MyMachine:7001
JMSTopic=testtopic
JMSAckMode=CLIENT_ACKNOWLEDGE
JMSTCF=jms.defaultConnectionFactory
JMSTestNum=1
JMSMessage=D\:\\aat\\test1.xml

Here is the same thing where the file you wish to send is located on an http server:

JMSContext=weblogic.jndi.WLInitialContextFactory
JMSProviderURL=t3://MyMachine:7001
JMSTopic=testtopic
JMSAckMode=CLIENT_ACKNOWLEDGE
JMSTCF=jms.defaultConnectionFactory
JMSTestNum=1
JMSMessage=http://MyMachine/test1.xml


Here is the same thing where the JMS Server is SwiftMQ

JMSContext=com.swiftmq.jndi.InitialContextFactoryImpl
JMSProviderURL=smqp://MyMachine:4001
JMSTopic=testtopic
JMSAckMode=CLIENT_ACKNOWLEDGE
JMSTCF=jms.defaultConnectionFactory
JMSTestNum=1
JMSMessage=http://MyMachine/test1.xml

Note:

You could pull messages off this topic / attach a listener simply by calling the JMSTestRec Class and using the exact same properties.

For normal (not testing) useage only the following need to be set:

JMSContext
JMSProviderURL
JMSTopic
JMSAckMode
JMSTCF
Note:

JMSAckMode defaults to AUTO_ACKNOWLEDGE is not set. If that is what you want then you don't have to set JMSAckMode.

Example XSLT Properties File
Back to Example Properties Files

In the example below I am transforming the test1.xml file using the test1.xsl script & the de.tudarmstadt.ito.xmldbms.xslt.XSLTest class and I am setting the output file to be output1.xml. I am using Xalan1 as set by the XSLTClass.

XSLTScript=D:\\aat\\test1.xsl
XMLFile=D:\\aat\\test1.xml
XSLTClass=de.tudarmstadt.ito.xmldbms.xslt.ProcessXslt1
XSLTOutput=D:\\aat\\output1.xml


The same example except that I am fetching the xsl and xml files via http but saving locally.

XSLTScript=http://MyMachine/test1.xsl
XMLFile=http://MyMachine/test1.xml
XSLTClass=de.tudarmstadt.ito.xmldbms.xslt.ProcessXslt1
XSLTOutput=D:\\aat\\output1.xml

For normal (not testing) useage only the following need to be set:

XSLTScript
XSLTClass