This Java package provides a Document Object Model interface to Tamino on all client platforms where a Java Virtual Machine is installed.
This section contains the following topics:
The Reference documentation for the Java API is provided in Javadoc format. This is a standard mechanism whereby HTML documentation is created directly from the Java source programs. The Javadoc documentation is available in the API Reference Section.
The explanations in this section assume that you are familiar with using the Tamino Manager to create databases, and with using the Tamino Interactive Interface to load schemas and data and perform XML database queries.
This section gives an overview of how to use the main methods of the API and indicates the basic techniques that you can use to access and modify data of a Tamino database.
The Java Document Object Model interface to Tamino provides the following main classes:
TaminoClient
This class facilitates Tamino operations. The interface permits the user to make queries and updates to Tamino without knowledge of the low level HTTP protocol. In particular, transactions are handled transparently. This class provides the most basic functionality:
Create an instance of the class, bind it to a URL of the Tamino server.
Optionally, set up transaction parameters and open/close transactions.
Perform Tamino operations e.g. query, process, insert, update, delete. These operations result in an instance of TaminoResult from which a DOM is available.
TaminoResult
This delivers the complete Tamino response as a DOM object (provided that it can successfully be parsed). This has two uses: (a) To provide a DOM object to facilitate method calls like createElement, which are only implemented by the DOM Object. (b) For diagnostic purposes. This class represents the result of a Tamino operation. It also implements interface "Enumeration".
TaminoError
This class represents an error returned from the Tamino server.
TaminoNonXML
This interface describes the API for non-XML data. The API supports, in principle, two methods with different signatures.
The classes are delivered in the package taminoclient.jar.
The prerequisites for using the Java DOM are are as follows:
A Java Virtual Machine is required with JDK 2.
For parsing the Tamino result an XML parser is required. This package includes James Clark's XP as the JAR file xp.jar, but any other parser recommended for the DOM will do.
domsdk.jar
sax.jar
w3cdom1.jar
All of these prerequisites are provided in the Tamino distribution kit.
For UNIX platforms: After the installation, the Java Virtual Machine is located by default in /usr/java/jre. The JAR files for the other prerequisites are located in $INODIR/$INOVERS/bin.
You can also obtain these prerequisites from the following sources:
xp.jar can be downloaded from http://www.jclark.com/xml/xp/index.html.
domsdk.jar can be downloaded from http://www.docuverse.com/domsdk/index.html.
sax.jar can be downloaded from http://www.megginson.com/SAX.
w3cdom1.jar can be downloaded from http://www.w3.org/ or http://www.docuverse.com/domsdk/index.html.
Details of how to communicate with a Tamino server from a client application are provided in the different example programs. For a full definition of the class properties and methods see the API Reference Section.
In general you need the following instructions :
import com.softwareag.tamino.api.dom.*;
...
try {
TaminoClient tamino = new TaminoClient("http://localhost/tamino/mydb/mycollection");
tamino.setPageSize(5);
....
TaminoResult tr = tamino.query("Telephone[LoginName="Walter"]");
}
catch (TaminoError e){
System.out.println("Tamino Error Text: " + e.errorText );
System.out.println("Tamino Error Code: " + e.responseCode );
}
The Tamino DOM API is included in package com.softwareag.tamino.api.dom.*, so the first thing to do is to import this package.
Then you have to instantiate an object of class TaminoClient to be able to use methods of this class like query, insert and delete. As a parameter you have to provide the Tamino database URL (in this case including the collection name). Be aware that if you specify the collection name in the URL you cannot specify this or another collection name in the methods supporting this (optional) parameter.
Optionally you can set a page size (by calling the method setPageSize of class TaminoClient), default page size however is 5. The page size determines how many documents that match a database query will be returned in a single call to the database. If there are more documents matching the query than can be returned in a single call according to the page size, the response document from any given call contains information that allows you to make subsequent calls to retrieve the remaining documents that match the query.
By calling the method query (a method of class TaminoClient) and providing the database query as an input argument (here: Telephone[LoginName="Walter"]) you send a query request to the Tamino Server. The result is an instance (DOM Object) of TaminoResult. By instantiating an object of type TaminoResult you are able to do any further investigation of the resulting DOM Object. TaminoResult offers a wide variety of methods to work with the DOM object like getElement, getNext and getInoId.
Some methods like getElement create a result object of type W3C DOM.
You can use methods of any third party DOM implementation to further process these DOM objects. In our examples we use the Docuverse implementation. The Docuverse DOM SDK is included in the Tamino distribution kit. On Tamino UNIX systems, the Docuverse domsdk.jar file is located in the bin directory under the installation root directory $INODIR/$INOVERS. On Tamino Windows systems, the domsdk.jar file is located in the "Tamino nnn\Bin" folder under the installation root directory, where "nnn" is the Tamino product version number. See also http://www.docuverse.com/ for more details.
You need the following additional instruction if you use objects and methods of this third party implementation:
import com.docuverse.dom.*;
If you perform updates with transaction logic, you should bracket your instructions in the following way:
import com.softwareag.tamino.api.dom.*;
...
try {
TaminoClient tamino = new TaminoClient("http://localhost/tamino/mydb/mycollection");
tamino.setPageSize(5);
tamino.startSession();
....
TaminoResult tr = tamino.query("Telephone[LoginName="Walter"]");
....
tamino.delete(...);
tamino.commit(false);
tamino.endSession();
}
catch (TaminoError e){
System.out.println("Tamino Error Text: " + e.errorText );
System.out.println("Tamino Error Code: " + e.responseCode );
}
By opening and closing a session you enable Tamino to keep the user context, which is otherwise not supported by the HTTP protocol. You could also provide parameters "Lockwaitmode" or "IsolationLevel". The Tamino DOM API handles transactions transparently to the user.
By invoking the method "commit" you close your update instruction; after this action a rollback is not possible anymore.
This section provides examples of how to use Java DOM API in a client application that accesses or modifies data in a Tamino database.
The following sections provide more detail:
To run the example, perform the following steps:
Use the Tamino Manager to create a test database. The examples don't contain the database URL in the source code, therefore they don't have to be adapted. The database URL has to be provided as an input parameter when invoking the example programs.
Use the Tamino Interactive Interface to define the "Telephone" schema that the example requires. The source file that contains the schema is telschem.xml.
Then use the Tamino Interactive Interface to load the test data from the file teldata.xml into the Tamino database.
Data for each person in the Telephone document is stored in a XML structure like the one below:
<Telephone> <EntryID>124</EntryID> <LoginName>Wehlmann124</LoginName> <PassWord>Wehlmann124</PassWord> <Lastname>Wehlmann</Lastname> <Firstname>Anton</Firstname> <Date_of_Birth>02.01.1945</Date_of_Birth> <Company_Name>Deutsche Bank</Company_Name> <Salutation>Herr</Salutation> <Email>Wehlmann124@web.de</Email> <Address> <Street>Seitersweg 200</Street> <City>Darmstadt</City> <ZIP>64287</ZIP> <Country>Germany>/Country> <Telephone>06150-41404</Telephone> <Fax>06150-896177</Fax> </Address> </Telephone>
At this point you can check how many people in the test database live in Frankfurt by using the Tamino Interactive Interface to submit the query Telephone[Address/City="Frankfurt"] to the database.
Compile and run the example programs.
The following examples are provided:
This example program demonstrates how to use the methods "ping" and "echo" of Tamino API class TaminoClient to get information about the Tamino Server.
Java Source:
01 import com.softwareag.tamino.api.dom.*;
02 public class DemoPing {
03 public static final void main(String arg[]) throws Exception {
try{
04 TaminoClient tamino=new TaminoClient( parseArgs(arg) );
05 System.out.println("Tamino Version :" + tamino.getVersion() + "\n");
06 TaminoResult tr = tamino.Ping() ;
07 System.out.println(tr.getDocument() + "\n");
08 tr = tamino.Echo();
09 System.out.println(tr.getDocument());
}
10 catch (com.softwareag.tamino.api.dom.TaminoError e){
System.out.println("Tamino Error Text: " + e.errorText );
System.out.println("Tamino Error Code: " + e.responseCode );
}
}
11 public static final String parseArgs(String args[]){
if (args.length >= 1)
return args[0];
else {
System.out.println("\n>> Tamino Demo Programs << \n" +
"Copyright (c) 2000 SOFTWARE AG, ALL Rights Reserved. \n\n" +
"Usage: java Demo.... database-url \n" +
" e.g. java DemoPing http://pcmypc/tamino/mydb/mycollection \n" );
System.exit(0);
return null;
}
}
}
Annotations:
01: Specifying of package which includes the Tamino API classes. In this example no more
packages are needed.
02: Definition of class DemoPing
03: Definition of the main method.
04: Instantiating the object "tamino" from class TaminoClient with parameter "Database URL".
The parameter has to be specified when this program is invoked.
05: Invoking method "getVersion" (of class TaminoClient) and sending the result to
System.out.
06: Invoking method "Ping" (of class TaminoClient). "Ping" tests for path completeness.
The result is of type TaminoResult and is being stored in variable "tr".
07: Invoking method "getDocument" (of class TaminoResult) and sending the result to
System.out.
"getDocument" creates a DOM document out of "tr".
08: Invoking method "Echo" (of class TaminoClient) and storing the result (of type
TaminoResult) in variable "tr".
Echo delivers a pre-defined string as positive answer in case the inner X-Machine layer is
reachable by the connection layer, otherwise an error message generated by the connection
layer.
09: Invoking method "getDocument" (of class TaminoResult) and sending the result to
System.out.
"getDocument" creates a DOM document out of "tr".
10: Error routine to catch Tamino errors. In case of errors errorcode and errortext are shown.
11: Definition of method "parseArgs" to check the input string for "DemoPing".
This example demonstrates how to insert a DOM object into a Tamino database using the Tamino DOM API method insert of class TaminoClient.
The DOM object is being processed by methods of the Docuverse DOM implementation.
Session Handling is included.
The program inserts an XML document such as the following one:
<Telephone> <EntryID>124</EntryID> <LoginName>Wehlmann124</LoginName> <PassWord>Wehlmann124</PassWord> <Lastname>Wehlmann</Lastname> <Firstname>Anton</Firstname> <Date_of_Birth>02.01.1945</Date_of_Birth> <Company_Name>Deutsche Bank</Company_Name> <Salutation>Herr</Salutation> <Email>Wehlmann124@web.de</Email> <Address> <Street>Seitersweg 200</Street> <City>Darmstadt</City> <ZIP>64287</ZIP> <Country>Germany</Country> <Telephone>06150-41404</Telephone> <Fax>06150-896177</Fax> </Address> </Telephone>
Java Source:
01 import com.docuverse.dom.*;
import com.softwareag.tamino.api.dom.*;
02 public class DemoInsert {
public static final void main(String arg[]) throws Exception
{
try{
03 TaminoClient tamino=new TaminoClient( parseArgs(arg) );
04 tamino.startSession();
05 BasicDocument doc=new BasicDocument();
06 BasicElement telephone = new BasicElement(doc,"Telephone");
07 BasicElement c = new BasicElement(doc,"EntryID");
08 c.appendChild(new BasicText(doc,"124"));
09 telephone.appendChild(c);
c = new BasicElement(doc,"LoginName");
c.appendChild(new BasicText(doc,"Wehlmann125"));
telephone.appendChild(c);
c = new BasicElement(doc,"PassWord");
c.appendChild(new BasicText(doc,"Wehlmann124"));
telephone.appendChild(c);
c = new BasicElement(doc,"Lastname");
c.appendChild(new BasicText(doc,"Wehlmann"));
telephone.appendChild(c);
c = new BasicElement(doc,"Firstname");
c.appendChild(new BasicText(doc,"Anton"));
c.appendChild(c);
c = new BasicElement(doc,"Date_of_Birth");
c.appendChild(new BasicText(doc,"02.01.1945"));
telephone.appendChild(c);
c = new BasicElement(doc,"Company_Name");
c.appendChild(new BasicText(doc,"Deutsche Bank"));
telephone.appendChild(c);
c = new BasicElement(doc,"Salutation");
c.appendChild(new BasicText(doc,"Herr"));
telephone.appendChild(c);
c = new BasicElement(doc,"Email");
c.appendChild(new BasicText(doc,"Wehlmann124@web.de"));
telephone.appendChild(c);
10 BasicElement adresse = new BasicElement(doc,"Address");
c = new BasicElement(doc,"Street");
c.appendChild(new BasicText(doc,"Seitersweg 200"));
adresse.appendChild(c);
c = new BasicElement(doc,"City");
c.appendChild(new BasicText(doc,"Darmstadt"));
adresse.appendChild(c);
c = new BasicElement(doc,"ZIP");
c.appendChild(new BasicText(doc,"64287"));
adresse.appendChild(c);
c = new BasicElement(doc,"Country");
c.appendChild(new BasicText(doc,"Germany"));
adresse.appendChild(c);
c = new BasicElement(doc,"Telephone");
c.appendChild(new BasicText(doc,"06150-41404"));
adresse.appendChild(c);
c = new BasicElement(doc,"Fax");
c.appendChild(new BasicText(doc,"06150-896177"));
adresse.appendChild(c);
11 telephone.appendChild(adresse);
12 TaminoClient.printTree(telephone);
13 TaminoResult tr= tamino.insert(telephone);
14 tamino.commit(false);
15 tr = tamino.query("Telephone[LoginName=\"Wehlmann125\"]");
16 if (tr.getElement() != null ){
TaminoClient.printTree(tr.getElement());
}
else
System.out.println("Telephone[LoginName=\"Wehlmann125\"] not found" );
17 tamino.endSession();
}
18 catch (TaminoError e){
System.out.println("Tamino Error Text: " + e.errorText );
System.out.println("Tamino Error Code: " + e.responseCode );
}
}
19 public static final String parseArgs(String args[]){
if (args.length >= 1)
return args[0];
else {
System.out.println("\n>> Tamino Demo Programs << \n" +
"Copyright (c) 2000 SOFTWARE AG, ALL Rights Reserved. \n\n" +
"Usage: java Demo.... database-url \n" +
" e.g. java DemoInsert http://pcmypc/tamino/mydb/mycollection \n" );
System.exit(0);
return null;
}
}
}
Annotations:
01: Specification of the packages which include the Tamino API classes and the Docuverse's
DOM implementation classes.
02: Definition of class "DemoInsert" and of main method.
03: Instantiating of object tamino (from class TaminoClient) with parameter "Database URL".
The parameter has to be specified when this program is invoked. Collection name is included.
Be aware that if you specify the collection name in the URL you cannot specify this or
another collection name in the methods supporting this (optional) parameter. You can invoke
method "setUrl" to change the URL or collection name if needed.
04: Start of a transaction by invoking method "startSession", to let Tamino keep the user
context.You could also provide parameters "Lockwaitmode" or "IsolationLevel".
05: Creation of the XML document as a DOM object. The DOM object has a tree structure.
Instantiating of object "doc" from class "BasicDocument".
"BasicDocument" is a class of Docuverse's DOM implementation. It is used here to create
a DOM document, which is then turned over to the Tamino API.
06: Instantiating of object "telephone" from class "BasicElement".
"BasicElement" is a class of Docuverse's DOM implementation.
The new element is named "Telephone" and it is the root element of the document.
07: Instantiating of object "c" from class "BasicElement".
The new element is named "EntryID" and appended to the root element "doc".
08: Instantiating of an object from class "BasicText" and assigning value "124".
Invoking method "appendChild" (of class BasicDocument). Thus "124" is being appended
to "c" (the object created in step 07).
09: Invoking method "appendChild" (of class BasicDocument). Thus the branch which has
been created in step 08 is being appended to object "telephone".
At this point the created tree looks like this:
Telephone ->
EntryID ->
#text 124
Steps 07,08 and 09 repeat now for all objects below root element "Telephone".
10: Instantiating of object "adresse" from class "BasicElement" and assigning name "Address".
During the following steps objects are appended to object "adresse" by invoking
method "appendChild".
11: Now the object "adresse" is complete and is being appended to object "telephone".
12: Invoking method "printTree" (of class TaminoClient),applied to the just created DOM
object.Method "printTree" prints a tree representation of a DOM element on System.out.
13: Invoking method "insert" (of class TaminoClient).
The just created DOM object "telephone" is being inserted in Tamino database.
The result is being stored in object "tr" (type TaminoResult).
14: Committing the database Update transaction by invoking method "commit".
15: Invoking of method "query" (of class TaminoClient). Thus sending following
query to Tamino: "Telephone[LoginName="Wehlmann125"]".
16: Invoking method "getElement" (of class TaminoResult), applied to the result of the
previous step. "getElement" extracts the element "xql:result" out of the complete
Tamino result structure.
If the result is not empty method "printTree" is being applied to the result of the
previous step. Method "printTree" prints a tree representation of the result on System.out.
If the document could not be found an error text is sent to system.out.
17: End of session by invoking method "endSession" (of class TaminoClient).
18: Error routine to catch Tamino errors. In case of errors errorcode and errortext are shown.
19: Definition of method "parseArgs" to check the input string of DemoInsert.
This example program demonstrates how to retrieve document elements in a Tamino database and deal with the resulting elements using the Java enumeration interface.
An interface of the W3C DOM specification is also used.
Session Handling is included.
Java Source :
01: import java.util.*;
import org.w3c.dom.*;
import com.softwareag.tamino.api.dom.*;
02: public class DemoQuery {
public static final void main(String arg[]) throws Exception
{
03: TaminoClient tamino = new TaminoClient( parseArgs(arg) );
04: tamino.setPageSize(5);
05: tamino.startSession();
try {
06: TaminoResult tr = tamino.query("Telephone[LoginName~=\"V*\"]");
07: Enumeration e = tr;
08: int i = 0;
09: while( e.hasMoreElements() ){
10: Element el=(Element)e.nextElement();
11: TaminoClient.printTree(el);
}
12: tamino.endSession();
}
13: catch(Throwable th) {
th.printStackTrace(System.out);
}
}
14: public static final String parseArgs(String args[]){
if (args.length >= 1)
return args[0];
else {
System.out.println("\n>> Tamino Demo Programs << \n" +
"Copyright (c) 2000 SOFTWARE AG, ALL Rights Reserved. \n\n" +
"Usage: java Demo.... database-url \n" +
" e.g. java DemoQuery http://pcmypc/tamino/mydb/mycollection \n" );
System.exit(0);
return null;
}
}
}
Annotations:
01: Specification of the packages which include the Tamino API classes, the W3C Interface
specification and Java Utilities.
02: Definition of class "DemoQuery" and of main method.
03: Instantiating of object tamino (from class TaminoClient) with parameter "Database URL".
The parameter has to be specified when this program is invoked. Collection name is included.
Be aware that if you specify the collection name in the URL you cannot specify this or
another collection name in the methods supporting this (optional) parameter. You can invoke
method "setUrl" to change the URL or collection name if needed.
04: Invoking method "getPageSize" to limit the elements which have to be returned by Tamino.
However, "5" is the default.
05: Start of a session by invoking method "startSession", to let Tamino keep the user
context.You could also provide parameters "Lockwaitmode" or "IsolationLevel".
06: Invoking method "query" (of class TaminoClient). Thus sending following XQL query to
Tamino: "Telephone[LoginName~="V*"]". The result is of type TaminoResult and is being
stored in variable "tr".
07: Transformation of variable "tr" to an object of type "Enumeration". Thus methods of
interface "Enumeration" can be applied.
Remark: In example "DemoDelete" you can find another way to use Enumeration. Class
TaminoResult implements the Interface Enumeration and offers the methods "hasMoreElements"
and "getNextElement".
08: Definition of loop counter.
09: Invoking method "hasMoreElements" (of Interface Enumeration), which returns a boolean
value and determines the end of the loop.
By specifying "while( e.hasMoreElements() && i++ < tamino.getPageSize() )" the end of
the loop could also be determined by the pagesize set.
10: By invoking the method "nextElement" (of Interface Enumeration) the next element in
Tamino's result structure is being selected and assigned to the reference of a DOM element
(Interface of W3C specification). The method returns the next element in result structure
independant of the pagesize.
11: Invoking method "printTree" (of class TaminoClient), applied to the just created DOM
object. Prints a tree representation of a DOM element on System.out. End of loop.
12: End of session by invoking method "endSession" (of class TaminoClient).
13: Error routine to catch Tamino errors. In case of errors the stacktrace is sent to
system.out.
14: Definition of method "parseArgs" to check the input string of DemoQuery.
This example program demonstrates how to delete an element in a document in a Tamino database.
An interface of the W3C DOM specification is used.
Session Handling is included.
Java Source:
01: import org.w3c.dom.*;
import com.softwareag.tamino.api.dom.*;
02: public class DemoDelete {
public static final void main(String arg[]) throws Exception
{
03: TaminoClient tamino=new TaminoClient( parseArgs(arg) );
04: tamino.setPageSize(10);
05: tamino.startSession();
06: TaminoResult tr=tamino.query("Telephone[LoginName=\"Wehlmann125\"]");
07: while(tr.hasMoreElements()) {
08: Element el=tr.getNextElement();
09: TaminoClient.printTree(el);
10: tamino.delete(el);
}
11: tamino.commit(false);
12: tamino.endSession();
}
13: public static final String parseArgs(String args[]){
if (args.length >= 1)
return args[0];
else {
System.out.println("\n>> Tamino Demo Programs << \n" +
"Copyright (c) 2000 SOFTWARE AG, ALL Rights Reserved. \n\n" +
"Usage: java Demo.... database-url \n" +
" e.g. java DemoDelete http://pcmypc/tamino/mydb/mycollection \n" );
System.exit(0);
return null;
}
}
}
Annotations:
01: Specification of the packages which include the Tamino API classes and the W3C Interface.
02: Definition of class "DemoDelete" and of main method.
03: Instantiating of object tamino (from class TaminoClient) with parameter "Database URL".
The parameter has to be specified when this program is invoked. Collection name is included.
Be aware that if you specify the collection name in the URL you cannot specify this or
another collection name in the methods supporting this (optional) parameter. You can invoke
method "setUrl" to change the URL or collection name if needed.
04: Invoking method "getPageSize" to limit the elements which have to be returned by Tamino
to 10.
05: Start of a transaction by invoking method "startSession", to let Tamino keep the user
context.You could also provide parameters "Lockwaitmode" or "IsolationLevel".
06: Invoking method "query" (of class TaminoClient). Thus sending following XQL
query to Tamino: "Telephone[LoginName="Wehlmann125"]". The result is of type TaminoResult and
is being stored in variable "tr".
07: Invoking method "hasMoreElements" (of class TaminoResult). The methods checks if there
is another element in Tamino's result structure and returns a boolean value which
determines the end of the loop.
TaminoResult implements the Interface Enumeration and the appropriate methods
"hasMoreElements" and "getNextElement".
08: By invoking the method "getNextElement" (of class TaminoResult) the next element in
Tamino's result structure is being selected and assigned to the reference of a DOM element
(Interface of W3c specifikation).
09: Invoking method "printTree" (of class TaminoClient), applied to the just created DOM
objekt. Prints a tree representation of a DOM element on System.out.
10: Invoking method "delete" (of class TaminoClient), applied to the previously created
DOM element. The element is being deleted in Tamino database. End of loop.
11: By invoking method "commit" (of class TaminoClient) the "delete" is being confirmed
to Tamino database.
12: End of session by invoking method "endSession" (of class TaminoClient).
13: Definition of method "parseArgs" to check the input string of DemoQuery.
The Reference documentation for the Java API is provided in Javadoc format. The Javadoc documentation is available in the following sections.