SampleAPIApplications

The following two samples demonstrate a complete implementation of a Java program executing an XAware BizDoc in a packaged .xar file, from a Windows command line. (Linux and Unix command line execution are also supported.)

The SayHello sample executes the HelloWorld.xbd BizDoc using the High Level interface, and passing in a resource path to the helloworld.xar package. This sample uses an XML string as input data, no input parameters, and prints the XML string result (“pretty-print”) to stdout.

The SayHello2 sample executes the same BizDoc using the Detailed Level interface. This sample uses a test.xml file contained in the .xar package as input data, passes a String input parameter, and processes the XML JDOM result, printing a message to stdout for each element in the result.

Both programs are packaged in the xa-apitest.jar, and are executed using the SayHello.cmd windows script to demonstrate the configuration required. The XAware meta documents and test data file are include in the .xar file. The java source code and an ant build script are also available (a supporting windows script file to setup the classpath is included in the XAware installation).

(The sample code can be found at API Sample Code.)

Contents 1 Building the Sample BizDocs 2 Building the Sample Java 3 Configuring the Samples 4 Executing the Samples

Building the Sample BizDocs

XA-Designer (5.0 GA) was used to build the HelloWorld.xbd, hello.xbc and test.xml files, as well as the SayHello and SayHello2 java applications, using the Eclipse Java Perspective.

Some of the steps used to build the XAware components were as follows:

• Define the XML format for the XML View using an XML schema or XML instance document. Generate a BizDoc from the schema or instance. Define the BizDoc interface (parameters). The input XML for the sample is structured as follows:

<ContactList>
   <Contact>
      <FirstName/>
      <LastName/>
   </Contact>
   <Contact>
     ...
</ContactList>

• Map elements from the input XML instance to the BizDoc elements using the Set XML Path... menu option. Convert XML structures to BizComponents, and map the input elements to the result structure using the BizComponent wizard. (In this simple example, the XML Mapper BizComp was used to map every contact, but any number of BizComps and data sources can be used to implement a BizView xml result).

The BizDoc output XML structure for the sample is as follows:

<HelloWorld>
   <From/>
   <Hello/>
   <Hello/>
    ...
</HelloWorld>

An input parameter with a default value was created and mapped to the <From> element. Each Contact/FirstName is mapped to a <Hello> element in the BizComp.

• Execute, test and debug (XA-Tracer) the BizDoc execution in XA-Designer.

• Use the Package Assembly Tool to create the helloworld.xar file, containing the BizDoc, BizComp and test xml data files. The .xar does not need to be deployed to an XAware Server, since the BizDoc will be executed directly from the Java program.

Please refer to the XAware Help or visit http://www.xaware.org for more information on using XA-Designer to build your BizViews.

Building the Sample Java

Some of the steps used to build the Java components were as follows (make sure you are using Java 1.5 with XAware 5.x; you can use the JRE in the XAware install):

• Switch to the Java Perspective in Eclipse and create a new project. Create a package for the java classes (package is optional; com.xaware.test was used for the sample). Create the class(es) with a main program.

• Add the XAware API classes to your Java Build Path. In Eclipse, you can use Add Library to add all of the <xawarehome>/client/*.jar files to a Library and add the Library to the build path (or you could use Add External Jars to add them separately).

Note: depending on your application, you may not need all of the .jar files in the /client directory, such as the ojdbc14.jar for Oracle connections if you are not using Oracle.

• Code you application using the XAwar API to invoke the BizDoc. You will need to import the classes for the API interface, including at a minimum:

import org.xaware.api.XABizView;
import org.xaware.shared.util.XAwareException;

Import other API classes depending on the features you use. The sample includes two main classes: SayHello, which uses the High Level API interface, and SayHello2, which uses the Detailed Level API interface.

• Execute, test and debug in the Eclipse environment. You will need to set your VM Arguments: to include the file path to your XAware installation home directory, such as -Dxaware.home=C:/xaware5-938

• Use the ant script, or the Eclipse Export option, to build your xa-apitest.jar file containing your classes.

Configuring the Samples

In order to run the application, you must have XAware installed for the "xawarehome" configuration and the API .jar files. The XAware "All-In-One" installation contains both the XA-Designer (used to build the sample application) and the XA-Engine components.

Note: a smaller xawarehome footprint can be created with a subset of the installation files. The configuration can be reduced depending on the XAware features you are using.

The helloworld.xar (containing the XAware BizDoc files and data file) and the xa-apitest.jar (containing the class files) are all the files needed to execute the application. However, the sample also includes a windows command script, which makes it easier to set environment variables and execute both samples. To use SayHello.cmd, first edit the file and change XAWARE_HOME to point to your XAware installation directory. The script calls another script file in the XAWARE_HOME/client directory to add all of the API .jar files to the CLASSPATH and it adds xa-apitest.jar to the CLASSPATH.

Executing the Samples

To execute the script, place xa-apitest.jar and SayHello.cmd in the same directory. (You can place them in different locations if you update the CLASSPATH in SayHello.cmd.) At a windows command prompt, enter (where <resource path> is the path to the helloworld.xar file):

   >> SayHello <resource path> XAware.org

The execution results should look something like the following:

XAWARE_HOME=C:\xaware5-938
JAVA_HOME=C:\Sun\SDK\jdk
---------- SayHello ----------
XML RESULT:
<?xml version="1.0" encoding="UTF-8"?>
<HelloWorld>
    <From>anonymous</From>
    <Hello>Mike</Hello>
</HelloWorld>

---------- SayHello2 ----------
Hello from: XAware.org
Hi: John
Hi: Jane

SayHello maps the input XML string (in the .java file) and uses the "from" parameter default value in the BizDoc. It outputs the XML String received from the BizDoc execution, to stdout.

SayHello2 maps the input XML from the test data file in the .xar package, and passes an input parameter for the “from” value. It processes each node in the BizDoc JDOM response, and writes a line to stdout for the <From> element and a line for each <Hello> element from the response.

(Review the sample code at API Sample Code.)