All Packages Class Hierarchy This Package Previous Next Index
java.lang.Object
|
+----org.xmlmiddleware.xmldbms.tools.PropertyProcessor
|
+----org.xmlmiddleware.xmldbms.tools.Transfer
Introduction
Transfer provides three interfaces for using XML-DBMS: a command line interface, a dispatch-style API, and a high-level, traditional API. The command line interface also consists of a single method (main). The dispatch-style API consists of a single method (dispatch). All other methods (setDatabaseProperties, storeDocument, retrieveDocument, and deleteDocument) belong to the traditional API.
The traditional API can transfer data between the database and a file or a string. Strings are a useful way to represent an XML document, since they can easily be passed to/from an XSLT processor, HTTP, etc. The dispatch-style API and the command line interface can only transfer data between a database and a file.
Properties
All of Transfer's interfaces use properties. The dispatch-style API and command-line interface are entirely properties based, while the traditional API uses properties for configuration information such as the commit mode and which key generators to use.
Properties fall into the following categories:
Property-processing properties are used to process other properties. This are File.
Parser properties provide information about the XML parser / DOM implementation. They are ParserUtilsClass.
Database properties are used to connect to the database(s). They are DBName, DataHandlerClass, DataSourceClass, User, and Password. If there is more than one database, use sequentially numbered versions of these properties -- DBName1, DBName2, etc.
When the value of DataSourceClass is "JDBC1DataSource", the Driver and URL properties are used to configure the data source. When the value of DataSourceClass is "JDBC2DataSource", the JNDIContext and JNDILookupName properties are used to configure the data source. If the main database properties are numbered, these properties must also be numbered.
Note that DBName and DataHandlerClass are both optional. If DBName is omitted, "Default" is used. This is an error if there is more than one database. If DataHandlerClass is omitted, org.xmlmiddleware.xmldbms.datahandlers.GenericHandler is used.
Transfer properties specify what is to be done (store, retrieve, or delete a document) and the files to use. They are Method, MapFile, XMLFile, ActionFile, and FilterFile. See below for details.
Select properties specify result sets to use when retrieving data. They are Select, SelectDBName, and SelectResultSetName.
Configuration properties specify how the underlying data transfer classes are to function. They are Encoding, SystemID, PublicID, CommitMode, StopOnError, ReturnFilter, KeyGeneratorName, and KeyGeneratorClass. See below for details.
When using the command line or the dispatch-style API, the Method property specifies the action to take. Legal values are StoreDocument, RetrieveDocumentByFilter, RetrieveDocumentBySQL, and DeleteDocument. (When using the traditional API, the Method property is not needed since this information is inherent in the method called.) The following table shows which transfer properties are used with each value of the Method property:
| Method | Transfer properties |
|---|---|
| StoreDocument | MapFile XMLFile ActionFile FilterFile (when ReturnFilter is "Yes") |
| RetrieveDocumentByFilter | MapFile XMLFile FilterFile[1] |
| RetrieveDocumentBySQL | MapFile XMLFile FilterFile[1] Select[2] SelectDBName[2][3] SelectResultSetName[2][4] |
| DeleteDocument | MapFile ActionFile FilterFile |
NOTES:
[1] If the filter document uses parameters, these should be passed in as well.
Because parameter names begin with a dollar sign ($), there should be no conflict
between parameter names and the names of other properties.
[2] If there is more than one result set, use Select1, Select2, ...,
SelectDBName1, SelectDBName2, etc.
[3] Optional. If no database name is specified, "Default" is used.
[4] Optional if there is only one result set, in which case "Default" is used.
Required if there is more than one result set. Result set names correspond to
result set names in the filter document./p>
The following table shows which configuration properties apply to each method. Configuration properties are used by all three interfaces.
| Method | Configuration properties |
|---|---|
| StoreDocument | CommitMode[1] StopOnError ReturnFilter KeyGeneratorName[2] KeyGeneratorClass[2][3] Encoding[4] SystemID[4] PublicID[4] Validate[5] |
| RetrieveDocumentByFilter RetrieveDocumentBySQL |
Encoding SystemID PublicID Validate[6] |
| DeleteDocument | CommitMode[1] Validate[7] |
NOTES:
[1] Legal values of CommitMode are AfterStatement, AfterDocument, None, and
NoTransactions.
[2] If there is more than one key generator, use KeyGeneratorName1,
KeyGeneratorName2, ... KeyGeneratorClass1, KeyGeneratorClass2, etc.
[3] If the key generator requires initialization properties, these should be
passed in as well. See the documentation for your key generator to see what
these are.
[4] Applies to the output filter file, if any.
[5] Value is a space-separated list containing Map, XML, and/or Action.
[6] Value is a space-separated list containing Map and/or Filter.
[7] Value is a space-separated list containing Map, Action, and/or Filter.
For a complete description of the properties used by Transfer, see ?????.
Command Line Syntax
The syntax of the command-line interface is:
java Transfer= [ = ...]
Property/value pairs are read in order and, if a property occurs more than once, the last value is used. If a property/value pair contains spaces, the entire pair must be enclosed in quotes.
For example, the following is used to store data from the sales.xml file to the database:
java org.xmlmiddleware.xmldbms.tools.Transfer
ParserUtilsClass=org.xmlmiddleware.domutils.helpers.ParserUtilsXerces
DataSourceClass=JDBC1DataSource
Driver=sun.jdbc.odbc.JdbcOdbcDriver URL=jdbc:odbc:xmldbms
User=ron Password=ronpwd
Method=StoreDocument
MapFile=sales.map XMLFile=sales.xml ActionFile=sales.act
A special property, File, can be used to designate a file containing other properties. For example, if the parser properties are stored in xerces.props and the database properties stored in db.props, the following is equivalent to the previous command line:
java org.xmlmiddleware.xmldbms.tools.Transfer File1=xerces.props File2=db.props
Method=StoreDocument MapFile=sales.map XMLFile=sales.xml ActionFile=sales.act
Notice that when more than one File property is used, the File properties must be numbered sequentially. File properties can also be used inside property files, making it possible to have a hierarchy of property files. File properties can be used from the command line and with the dispatch-style interface. They cannot be used with the traditional API.
Dispatch-style Interface
The dispatch-style interface is called that because methods are not called directly. Instead, the name of the method and its arguments are passed as properties and Transfer "dispatches" the call to the actual method based on these properties.
The dispatch-style interface consists of a single method, dispatch(). In general, applications that want to call Transfer programmatically should probably use the traditional API instead. Not only is it easier to use, it is more efficient because it holds database connections open across calls. The dispatch() method connects to the database each time it is called.
Traditional API
The traditional API consists of a number of methods: setDatabaseProperties() and a number of variations of storeDocument(), retrieveDocument(), and deleteDocument(). These methods allow you to transfer data between the database and an XML file, a string, or (in the case of storeDocument()) an InputStream. Applications using this interface must call setDatabaseProperties() before calling any of the other methods.
storeDocument(), retrieveDocument(), and deleteDocument() accept configuration parameters in the form of properties. All of these have defaults except for the key generator properties, which are required by storeDocument when the specified map uses key generators.
Object Caching
When Transfer is called through the dispatch(), storeDocument(), retrieveDocument(), and deleteDocument() methods, it caches various objects for reuse in subsequent calls. The following objects are cached, with the key (property) shown in parentheses. If the item to which the key points (such as a map file) changes between calls to these methods, the new object will not be used. To use the new object, applications must instantiate and use a new Transfer object. Note that database objects (DataSource, DataHandler, etc.) are cached between calls to setDatabaseProperties().
XMLDBMSMap (MapFile) Actions (ActionFile) FilterSet (FilterFile) KeyGenerator (KeyGeneratorName)
Transfer(ParserUtils)
Transfer(Properties)
deleteDocument(Properties, String, String, String, Hashtable)
dispatch(Properties)
main(String[])
retrieveDocument(Properties, String, Properties, String, Hashtable)
If the class map for the element type corresponding to the result set contains related classes, this method retrieves additional data from the database.
retrieveDocument(Properties, String, Properties, String, Hashtable, String)
If the class map for the element type corresponding to the result set contains related classes, this method retrieves additional data from the database.
retrieveDocument(Properties, String, String, Hashtable)
retrieveDocument(Properties, String, String, Hashtable, String)
setDatabaseProperties(Properties)
storeDocument(Properties, String, String, InputStream)
storeDocument(Properties, String, String, String)
storeDocument(String, Properties, String, String)
Transfer
public Transfer(Properties props) throws XMLMiddlewareException
Transfer
public Transfer(ParserUtils utils)
main
public static void main(String args[])
See the introduction for the command line syntax.
setDatabaseProperties
public void setDatabaseProperties(Properties props) throws XMLMiddlewareException, SQLException
For a list of database properties, see the introduction. Applications that call storeDocument(), retrieveDocument(), or deleteDocument() must call this method before calling those methods. Calling this method closes any existing connections to the database, so it should be used sparingly.
dispatch
public void dispatch(Properties props) throws XMLMiddlewareException, SQLException
For a list of valid methods (values of the Method property) and the properties each of these methods needs, see the introduction.
storeDocument
public FilterSet storeDocument(Properties configProps,
String xmlFilename,
String mapFilename,
String actionFilename) throws XMLMiddlewareException, SQLException
storeDocument
public FilterSet storeDocument(String xmlString,
Properties configProps,
String mapFilename,
String actionFilename) throws XMLMiddlewareException, SQLException
storeDocument
public FilterSet storeDocument(Properties configProps,
String mapFilename,
String actionFilename,
InputStream xmlStream) throws XMLMiddlewareException, SQLException
retrieveDocument
public String retrieveDocument(Properties configProps,
String mapFilename,
String filterFilename,
Hashtable params) throws XMLMiddlewareException, SQLException
retrieveDocument
public void retrieveDocument(Properties configProps,
String mapFilename,
String filterFilename,
Hashtable params,
String xmlFilename) throws XMLMiddlewareException, SQLException
retrieveDocument
public String retrieveDocument(Properties configProps,
String mapFilename,
Properties selects,
String filterFilename,
Hashtable params) throws XMLMiddlewareException, SQLException
If the class map for the element type corresponding to the result set contains related classes, this method retrieves additional data from the database.
retrieveDocument
public void retrieveDocument(Properties configProps,
String mapFilename,
Properties selects,
String filterFilename,
Hashtable params,
String xmlFilename) throws XMLMiddlewareException, SQLException
If the class map for the element type corresponding to the result set contains related classes, this method retrieves additional data from the database.
deleteDocument
public void deleteDocument(Properties configProps,
String mapFilename,
String actionFilename,
String filterFilename,
Hashtable params) throws XMLMiddlewareException, SQLException
All Packages Class Hierarchy This Package Previous Next Index