| Using XMLink | |
To facilitate support for data exchange using XML, XMLink supports an alternate style of access to Oracle Tuxedo services. In this case, XML input is received by an instance of XMLConnector.
If you are writing server-side Java and want to use the XML invocation style, you can create an instance of XMLConnector and directly call its process method. XMLink also includes an EJB wrapper, called TConnXML, that acts as a facade to XMLConnector. For more information, see "Using an EJB to Input XML." You will typically use the TConnXML EJB to invoke Oracle Tuxedo services from an EJB client.
If you are using XMLink in a distributed server-side environment, using XMLink's TConnXML EJB allows you to easily access your Tuxedo services even when XMLink is installed on a remote application server.
Both the input String to TConnXML.process and the InputStream argument to XMLConnector.process must be in XML format and must conform to the tconn.dtd document type definition.
For Java documentation of the XMLink interfaces, refer to the Javadoc portion of the online documentation.
Inputting Data Using XML |  |
XMLConnector objects support a method process that takes the following parameters:
ConnectionFactory object as its first parameter
The contents of the The following is the document type definition for input to the Each XML document is delimited by an A Other than the InputStream parameter must be in XML format and must conform to the tconn.dtd document type definition.
process method:
<!-- DTD for TUXEDO service requests -->
<!-- Basic elements -->
<!ELEMENT agenda (connection?, (servicecall | transaction)*)>
<!ELEMENT transaction (servicecall*)>
<!ELEMENT connection EMPTY>
<!ELEMENT servicecall
(FMLRecord | FML32Record | STRINGRecord | CARRAYRecord |
JAMFLEXRecord)>
<!ELEMENT FMLRecord (field*)>
<!ELEMENT FML32Record (field*)>
<!ELEMENT STRINGRecord (data)>
<!ELEMENT CARRAYRecord (data)>
<!ELEMENT JAMFLEXRecord (field*)>
<!ELEMENT data (#PCDATA)>
<!ELEMENT field (#PCDATA)><!-- Attributes for connection element -->
<!ATTLIST connection username CDATA #REQUIRED>
<!ATTLIST connection clientname CDATA #REQUIRED>
<!ATTLIST connection password CDATA #REQUIRED>
<!ATTLIST connection groupname CDATA #REQUIRED>
<!ATTLIST connection data CDATA #REQUIRED><!-- Attributes for servicecall element -->
<!ATTLIST servicecall name CDATA #REQUIRED>
<!ATTLIST servicecall mode (SYNCH | ASYNCH) "SYNCH">
<!ATTLIST servicecall mode timeout CDATA "0"><!-- Attributes for records -->
<!ATTLIST FMLRecord encoding CDATA #IMPLIED>
<!ATTLIST FML32Record encoding CDATA #IMPLIED>
<!ATTLIST STRINGRecord encoding CDATA #IMPLIED>
<!ATTLIST CARRAYRecord encoding CDATA #IMPLIED>
<!ATTLIST JAMFLEXRecord encoding CDATA #IMPLIED><!-- Attributes for field element -->
<!ATTLIST field name CDATA #REQUIRED> Elements in the XML Input DTD
Agenda Element
agenda element. The agenda is a list of the service requests to be made to the Oracle Tuxedo application. The agenda can optionally contain a single connection element. If there is a connection element, it must be the first element in the agenda.
Connection Element
connection is an empty element with the attributes username, clientname, password, groupname and data. If a connection element is included in an agenda, the service requests in the agenda are made using a connection created according to the information provided as the connection's attributes. If no connection element is provided, the service requests use a "default" connection type.
Transaction and Servicecall Elements
connection element, an agenda can contain any number of transaction elements and servicecall elements. transaction elements themselves can contain any number of sevicecall elements. So an agenda can contain service calls grouped into transactions, plus service calls that are independent of any transaction.
transaction elements have no attributes. They merely serve to group servicecall elements.
servicecall elements have the following attributes:
name—Name of the service call being requested
Each A The following is an example of a series of service calls invoked through the XML interface:
When a request for Oracle Tuxedo services is received, the XML servicecall element (whether inside a transaction element or not) must contain a single element. This can be either an FMLRecord, an FML32Record, a JAMFLEXRecord, a STRINGRecord, or a CARRAYRecord element. This element contains the input data for the service.
FMLRecord, FML32Record, and JAMFLEXRecord elements can contain any number of field elements. STRINGRecord and CARRAYRecord elements must each contain a single data element.
Field Elements
field records have a name attribute. This is the name of the field. More than one field element can have the same name. If a field element has the same name as another field element, then its contents will represent another occurrence of the field in the FML buffer.
Data Elements
data element has no attributes, it simply delimits the data to be packaged into a STRING or CARRAY buffer.
Example: Using XML Input
<agenda>
<connection username="managerxml"
clientname="manager"
password="password1"
groupname=""
data=""/><transaction>
<servicecall name="FINDEMP">
<FMLRecord>
<field name="employee_ssn">111221111</field>
<field name="last_name">Jones</field>
<field name="first_name">Fred</field>
<field name="dept_id">10</field>
</FMLRecord>
</servicecall>
</transaction>
</agenda>InputStream will be parsed, and the servicecall requests will be issued in the order in which they occur in the file. When a transaction element is encountered, a tpbegin is issued. When the transaction end tag is encountered, a tpcommit is issued. If any of the servicecall elements between the transaction demarcations returns an error, a tpabort will be issued.
Returning Data in XML | |
The process method fills the OutputStream with the return data from the service requests specified in the InputStream. The OutputStream's contents will also be in XML format, and will correspond to the tconnoutput.dtd document type definition.
The following is the document type definition for the output from a process call.
<!-- DTD for output from TUXEDO service requests -->
<!-- Basic elements -->
<!ELEMENT resultset ((returndata | error | xactionmsg)*)>
<!ELEMENT returndata
(FMLRecord | FML32Record | STRINGRecord | CARRAYRecord |
JAMFLEXRecord, UserReturnCode?)>
<!ELEMENT FMLRecord (field*)>
<!ELEMENT FML32Record (field*)>
<!ELEMENT STRINGRecord (data)>
<!ELEMENT CARRAYRecord (data)>
<!ELEMENT JAMFLEXRecord (field*)>
<!ELEMENT UserReturnCode (#PCDATA)>
<!ELEMENT error (#PCDATA)>
<!ELEMENT xactionmsg (EMPTY)>
<!ELEMENT field (#PCDATA)>
<!ELEMENT data (#PCDATA)>
<!-- Attributes for returndata element -->
<!ATTLIST returndata servicename CDATA #REQUIRED>
<!-- Attributes for error element -->
<!ATTLIST error servicename CDATA #REQUIRED>
<!-- Attributes for xactionmsg element -->
<!ATTLIST xactionmsg action (BEGIN | ABORT | COMMIT) #REQUIRED>
<!-- Attributes for records -->
<!ATTLIST FMLRecord encoding CDATA #IMPLIED>
<!ATTLIST FML32Record encoding CDATA #IMPLIED>
<!ATTLIST STRINGRecord encoding CDATA #IMPLIED>
<!ATTLIST CARRAYRecord encoding CDATA #IMPLIED>
<!ATTLIST JAMFLEXRecord encoding CDATA #IMPLIED>
<!-- Attributes for field element -->
<!ATTLIST field name CDATA #REQUIRED>
Each such document will contain a single resultset element that can contain any number of returndata elements, error elements, and xactionmsg elements.
Each returndata element represents the data returned from an Oracle Tuxedo service call. A returndata element has a single attribute, servicename, that contains the name of the service that the returndata element represents. Each returndata element will contain a single element, either an FMLRecord element, an FML32Record element, a STRINGRecord element, or a CARRAYRecord element.
FMLRecord and FML32Record elements can each contain any number of field elements. Each field element has a name attribute, and contains the field's value as its data. If more than one of the field elements in a given FMLRecord or FML32Record element share the same name value, they represent different occurrences in a single field.
STRINGRecord and CARRAYRecord elements each contain a single data element, which has no attributes, and merely contains the value of the buffer as its contents.
Each error element corresponds to an Oracle Tuxedo service request that returned an error. An error message has a name attribute the value of which is the name of the Oracle Tuxedo service that returned the error. The error element contains the text of the error returned as its contents.
Each xactionmsg element is empty and has a single attribute, called action. The action attribute can have the following values: BEGIN, ABORT, COMMIT. The xactionmsg elements are placed in the returndata elements to mark the boundaries of the transactions that had been specified in the service request.
The following are examples of XML text representing the return values of service calls:
<?xml version="1.0" standalone="no"?>
<!DOCTYPE resultset SYSTEM "tconnoutput.dtd">
<resultset>
<returndata servicename="GetEmpData">
<FML32Record>
<field name=Fred>Fred occurrence one</field>
<field name=Fred>Fred occurrence two</field>
<field name=Fred>Fred occurrence three</field>
<field name=Barney>This is Barney</field>
</FML32Record>
</returndata>
</resultset>
<?xml version="1.0" standalone="no"?>
<!DOCTYPE resultset SYSTEM "tconnoutput.dtd">
<resultset>
<returndata servicename="TOUPPER">
<STRINGRecord>
<data>TO BE OR NOT TO BE</data>
</STRINGRecord>
</returndata>
</resultset>
Using an EJB to Input XML | |
TConnXML, the EJB wrapper to XMLConnector, supports the following interface:
public interface TConnXML extends javax.ejb.EJBObject
{
String process(String xml)
String process(String xml, String cfName)
}
Use the second variant of process to access a ConnectionFactory that has been deployed.
The first variant of process takes a single argument of type String and is like using XMLink in a non-managed environment. This is the input to the service requests.
The second variant of process, which is the recommended version, also requires a second String parameter. The value of the second parameter is used when doing a JNDI lookup to get a ConnectionFactory that has been deployed.
The first variant should only be used in cases where JNDI deployment of a ConnectionFactory is not desired. In this case, the ConnectionFactory is instantiated with default properties. TUXCONFIG, WSNADDR (or WSENVFILE must be set in the environment to specify the correct Tuxedo domain. Authentication in this case would be specified in XMLink.
The input String to process must be in XML format and must conform to the tconn.dtd document type definition. To see the DTD, refer to "Inputting Data Using XML."