Info*Engine Java EE Connector
The Info*Engine Java Platform, Enterprise Edition (Java EE) connector is Info*Engine’s implementation of Java EE Connector Architecture (JCA) version 1.0. JCA was designed to supply standard implementation for interaction between Java EE application servers and enterprise information systems (EIS), in this case Info*Engine.
The connector is a low level software driver that allows access to Info*Engine from a Java EE application server environment (such as JBOSS or Sun ONE), or a standalone Java client (command-line or swing application). The Info*Engine Java EE connector uses SOAP as its communication protocol. The connector is similar to a JDBC driver, in that the connector understands the low-level aspects of connecting to and interacting with Info*Engine similar to how a JDBC driver connects to and interacts with a relational database.
For more information on configuring your application server environment for use with the Info*Engine Java EE connector, see the appropriate white paper for your environment (Sun ONE or JBoss). These white papers can be found on the Windchill Info*Engine page of the Reference Documents section of the PTC website at the following URL:
The Info*Engine Java EE connector communicates with Info*Engine using SOAP. SOAP is a standard request/response protocol for interacting with a web service using XML. Info*Engine includes the SOAP RPC servlet which allows Info*Engine tasks to be exposed to a client using HTTP or JMS.
Info*Engine can describe a SOAP service to a client at runtime using Web Service Definition Language (WSDL). Delivered along with the Java EE connector are tools that use WSDL metadata information to generate client-side Java classes that can be used to simplify interactions with Info*Engine. The supplied tools can generate Data Access Objects (DAOs) and Enterprise Java Beans (EJBs) that expose standard Java methods that drive interactions with Info*Engine.
JCA Contracts and the Common Client Interface
JCA defines three contracts that a connector must fulfill: connection management, transaction management, and security management. Fulfillment of these three contracts by the Java EE connector allows an application server to plug in value-added services such as connection pooling, automatic transaction management, and security control. JCA also defines the common client interface (CCI). The CCI provides a suggested client API that a Java EE connector can optionally implement. The Info*Engine Java EE connector implements the CCI.
 | This information is provided as a general overview and is not required to write applications using the Info*Engine Java EE connector. |
Connection Contract
A connector must implement the following service provider interfaces:
• javax.resource.spi.ManagedConnectionFactory
• javax.resource.spi.ManagedConnection
• javax.resource.spi.ManagedConnectionMetaData
• javax.resource.spi.ConnectionManager
The Info*Engine connector implementation of these classes is as follows:
• com.infoengine.connector.IeManagedConnectionFactory
• com.infoengine.connector.IeManagedConnection
• com.infoengine.connector.IeManagedConnectionMetaData
• com.infoengine.connector.IeConnectionManager
These classes are described in the following sections.
| | Object references in code should be made using the appropriate interface definition and not the implementation class. For example: ManagedConnectionFactory mcf = new IeManagedConnectionFactory (); |
IeManagedConnectionFactory
The IeManagedConnectionFactory class is used to create instances of EIS specific connection factories that can create actual connections to Info*Engine. The class also contains logic required to create and compare physical connections. These additional methods are used by a connection manager, such as an application server or other implementation, to facilitate connection pooling. As an application developer, the only time you might reference this class directly is when you are developing a standalone Java SOAP client. For more information, see Example Standalone Java SOAP Client.
IeManagedConnection
The IeManagedConnection class represents a physical connection to an EIS. As an application developer you do not need to instantiate or interact directly with this class.
IeManagedConnectionMetaData
The IeManagedConnectionMetaData class can be used to get general information about a physical connection to an EIS. The Info*Engine connector has merged this class implementation with that of javax.resource.cci.ConnectionMetaData as part of the CCI implementation. For more information, see the “Common Client Interface” section below.
For example, a client could ask for metadata about a connection in the following manner:
Connection cx = cxFactory.getConnection();
ConnectionMetaData meta = cx.getMetaData ();
ConnectionMetaData meta = cx.getMetaData ();
IeConnectionManager
The IeConnectionManager class is required for managing connections when a connector is used outside of a Java EE application server, such as in a standalone Java SOAP client. An application server’s implementation of this class incorporates functions such as connection pooling and automated transaction management. The Info*Engine Java EE connector implementation of this class supplies support for simple connection pooling. It does not support automated transaction management. Transaction support is only available when the Info*Engine Java EE connector is deployed against a Windchill system. When the connector is used by a standalone application, the application must manage transaction demarcation manually. As an application developer, you never need to instantiate or interact directly with this class. For more information, see Example Standalone Java SOAP Client.
Transaction Contract
The Info*Engine Java EE connector contains LocalTransaction support only. Transactions are only supported if the connector is deployed against Windchill. When using the Info*Engine Java EE connector from a Java EE SOAP client, it is possible to have the application server manage transactions for you. When deployed, each EJB method can declare its transaction requirements. When using Windchill and a transacted delegate is invoked from an EJB, the @FORM context group contains information that the task must use to be enclosed within the transaction. The @FORM attributes are:
• session_instance — The Windchill instance the transaction is started against. This must be used as the value of the INSTANCE parameter to Windchill adapter webjects that are part of a transaction.
• session_id — The session identifier. This must be used as the value of the SESSION_ID parameter to Windchill adapter webjects that are part of a transaction.
Transactions can be demarcated manually if you are executing either from a standalone Java SOAP client or from an EJB that wants to control a transaction itself. For example:
Connection cx = cxFactory.getConnection ();
LocalTransaction tx = cx.getLocalTransaction ();
...
tx.begin ();
...
tx.commit ();
LocalTransaction tx = cx.getLocalTransaction ();
...
tx.begin ();
...
tx.commit ();
Security Contract
The Info*Engine connector supports BasicPassword authentication using the javax.resource.spi.security.PasswordCredential credential interface. Actual validation occurs with the first interaction. If Info*Engine is running in an insecure mode (for instance, with no HTTP server authentication) then the username and password are ignored as if the given credentials are valid and are passed along to be used by supporting tasks. The /com/infoengine/connector/validateUser.xml task is supplied for EJBs to use at creation time to verify that the user can be properly authenticated against the supporting adapter. Automatic EJB generation makes use of this task to validate users at EJB creation time to avoid authentication failures with later interactions.
Common Client Interface (CCI)
| | Interactions with Info*Engine should ideally be performed through generated Data Access Objects (DAOs) rather than at the CCI level. For more information on DAO generation, see Example Standalone Java SOAP Client. |
The Info*Engine Java EE connector avoids a proprietary API for interaction by implementing the Common Client Interface (CCI).
The CCI simplifies the problem of writing code to connect a client to an underlying EIS’s data store. The EIS vendor can use the CCI to write a generic interface to its product. With this one interface, the product works with clients on any Java EE compliant platform. Likewise, application developers only need to learn and use one set of API calls to connect their client to any underlying EIS, rather than having to learn a different API for each EIS.
The following classes are used by the CCI:
• com.infoengine.connector.IeConnectionSpec
• com.infoengine.connector.IeInteractionSpec
• com.infoengine.connector.IeInteractionResult
com.infoengine.connector.IeConnectionSpec
The com.infoengine.connector.IeConnectionSpec class allows credentials to be passed during connection creation. This class supports the standard UserName and Password properties. In addition, this class supports a locale property that allows Info*Engine to generate localized data in response, and an authUser property that can be used in Single Sign On (SSO) scenarios. The authUser property is only accepted by Info*Engine if the connector is configured to digitally sign outgoing requests or if the client resides on a host that is trusted.
com.infoengine.connector.IeInteractionSpec
The com.infoengine.connector.IeInteractionSpec class drives interactions with Info*Engine. The standard FunctionName property specifies the method of function to invoke. This value corresponds to the name of the task delegate to invoke. The additional ClassName property specifies the class the task delegate belongs to. This value corresponds to a type identifier that contains the task delegate to invoke.
com.infoengine.connector.IeInteractionResult
The javax.resource.cci.Interaction implementation supports executing with input record only. It does not support executing with input and output record. The interaction implementation always returns an instance of com.infoengine.connector.IeInteractionResult (implements javax.resource.cci.Record). The IeInteractionResult class is a simple wrapper for the SOAP response. The response object can be retrieved using the getResult() method. An interaction accepts as input either MappedRecord or IndexedRecord.
In the case where MappedRecord is passed, the keys in the map are parameter names and the values are parameter values. In the case where IndexedRecord is passed, each value must be a name=value pair of parameters to be passed. Ideally, MappedRecord should be used, as the use of name=value strings does not allow for any data type other than java.lang.String to be passed.
The following is an example interaction with Info*Engine:
ConnectionFactory cxf = getLDAPFactory (); // look up in JNDI
Connection cx = null;
try {
// get connection with credentials
IeConnectionSpec cxSpec = new IeConnectionSpec ();
cxSpec.setUserName ( "wcadmin" );
cxSpec.setPassword ( "wcadmin" );
cx = cxf.getConnection ( cxSpec );
// or anonymous
//cx = cxf.getConnection ();
Interaction ix = cx.createInteraction ();
IeInteractionSpec ixSpec = new IeInteractionSpec ();
ixSpec.setClassName ( "org.myOrg.Math" );
ixSpec.setFunctionName ( "sum" );
RecordFactory rFact = cxf.getRecordFactory ();
MappedRecord iRec = rFact.createMappedRecord ( "input" );
iRec.put ( "x", new Integer ( 4 ) );
iRec.put ( "y", new Integer ( 5 ) );
IeInteractionResult result =
(IeInteractionResult)ix.execute ( ixSpec, iRec );
Integer sum = (Integer)result.getResult ();
System.out.println ( "sum is " + sum.intValue () );
} catch ( Exception ex ) {
ex.printStackTrace ();
} finally {
if ( cx != null ) cx.close ();
}
Connection cx = null;
try {
// get connection with credentials
IeConnectionSpec cxSpec = new IeConnectionSpec ();
cxSpec.setUserName ( "wcadmin" );
cxSpec.setPassword ( "wcadmin" );
cx = cxf.getConnection ( cxSpec );
// or anonymous
//cx = cxf.getConnection ();
Interaction ix = cx.createInteraction ();
IeInteractionSpec ixSpec = new IeInteractionSpec ();
ixSpec.setClassName ( "org.myOrg.Math" );
ixSpec.setFunctionName ( "sum" );
RecordFactory rFact = cxf.getRecordFactory ();
MappedRecord iRec = rFact.createMappedRecord ( "input" );
iRec.put ( "x", new Integer ( 4 ) );
iRec.put ( "y", new Integer ( 5 ) );
IeInteractionResult result =
(IeInteractionResult)ix.execute ( ixSpec, iRec );
Integer sum = (Integer)result.getResult ();
System.out.println ( "sum is " + sum.intValue () );
} catch ( Exception ex ) {
ex.printStackTrace ();
} finally {
if ( cx != null ) cx.close ();
}