|
| Sun ONE Connector Builder 2.0 Developer's Guide |
General Approach for Building Resource AdaptersThis module describes the following topics:
Sun ONE Connector Builder can generate resource adapters to the client API of almost any EIS. These EIS APIs can be grouped into categories in varying ways. By understanding the different classifications and recognizing key characteristics in an EIS API you are working with, you can determine how best to use Connector Builder to create an adapter. This module describes many of the common styles of EIS APIs. You may find still others with which you can use Connector Builder very successfully.
Classifying EIS APIs
There are a few basic ways of classifying EIS APIs that provide great help as you plan your resource adapter and your use of Connector Builder:
- Classifying by Implementation Language — refers to the programming language in which the EIS API is provided
- Classifying by Connection Style — refers to how, if at all, the idea of connections to the EIS appear in the EIS API
- Classifying by Method Input and Output Data Style — refers to how the methods in the API obtain input information they need to operate and provide output information back to the application
- Classifying by API Abstraction Level — refers to whether the API's method names and parameters refer to application concepts (such as a method named "getCustomer" and parameters named "customer" or "customerID") or more abstract system concepts (such as a method named "execute" and parameters named "procedureName" or "inputTable")
Classifying by Implementation Language
A given API could be exposed in any, or perhaps multiple, programming languages. The languages most relevant to Connector Builder are Java and C/C++. Although Connector Builder itself works only with Java APIs, techniques for creating a Java API based on a C or C++ API are described in Considering Implementation Language.
Classifying by Connection Style
EIS APIs fall into the following categories of connection style:
- Connection-oriented EIS APIs with two subcategories:
- Connection-less EIS APIs
Connection-oriented EIS APIs
Often an API's usage of an EIS involves the concept of a connection. Usually, these connections must be authenticated with a username and password and often involve network traffic between the EIS and the application as the application uses the EIS API. Typically, connections take considerable time and system resources to establish.
This concept of the connection to the EIS can appear in the API as a type of object that the application uses as a handle to identify its particular connection to the EIS. Most often, the application obtains a handle by invoking a method in the EIS API that explicitly constructs a new connection to the EIS and returns the handle as its result.
APIs that are connection-oriented take one of two forms, based on how this handle is used in other methods of the EIS API.
Connection-as-parameter
In this form, the connection handle is passed as a parameter to the other methods in the EIS API. Each method's implementation uses the handle parameter to make sure that the method's work is performed in whatever context that connection handle represents.
The sample COTS EIS API included with Connector Builder has the connection-as-parameter form as follows:
The COTSAPI class offers several static methods that perform the useful work the application might need, such as retrieving a list of all customers. The application invokes these static methods, passing the previously-obtained connection handle as one of the parameters.
Connection-as-target
In other APIs, the connection itself is the object on which the useful methods are defined - the connection is the target of the method invocation. The LDAP API illustrates this form.
LDAP API connection as target
// Obtain a new connection.
LDAPConnection connHandle;
connHandle = new LDAPConnection();
//
// Use the connection.
LDAPSearchResults results = connHandle.search(...);
Here, the application obtains the connection handle and then invokes the search method that is defined on that handle to perform the search rather than passing the handle as a parameter.
Connection-less EIS APIs
Typically, the EIS API includes the concept of a connection, according to either the connection-as-parameter form or the connection-as-target form. Still, it is possible that the EIS does not require an application to connect to it before it provides service or that the API connects to the EIS implicitly for the application. Whatever the reason, this style of API has no explicit notion of a connection.
An example of this type of API could be a library of statistical computations. The API does not require the application to connect to the library, simply to invoke methods on classes contained in it.
Classifying by Method Input and Output Data Style
Any method, including those in an EIS API, can obtain the information required to execute in one or more of the following general ways:
- from input parameters to the method
- from stored (enclosed) object state - private variables of the object that were assigned a value before the method was invoked
- from the environment - Java properties, operating system environment variables, files
Similarly, a method can make the results of its execution available in one or more of the following ways:
- in a return value from the method
- in stored (enclosed) object state
- in the environment
As you prepare to build a resource adapter, you should familiarize yourself with the methods you want to expose to the application. Understand which of these styles each method uses to obtain the input data it needs and provide the output data to the calling method.
Classifying by API Abstraction Level
You can also consider classifying EIS APIs by the abstraction level. You may consider the words used for the method names and parameter names and see if the method names and parameter names use a vocabulary from the application or from software.
Specific EIS APIs - Application Vocabulary
Usually, APIs that use application terms - customer, order, inventory, and others, provide methods that correspond to specific business functions in the EIS. The COTS sample EIS API exposes methods such as these:
COTS getCustomer method
public static Customer getCustomer(COTSEISConnection conn,
int custId )
public static boolean updateCustomer(COTSEISConnection conn,
Customer cust)
Except for the necessary reference to the COTSEISConnection, the method and parameter names refer to concepts from the application and its business vocabulary. This type of EIS API can be considered a specific API, because a single method corresponds to a specific business function in the EIS.
General-purpose EIS APIs - Software Vocabulary
In contrast, other APIs use method and parameter names that pertain to software artifacts such as procedures, functions, parameters, and tables. The SAP Java Connector (JCo) API, for example, includes this method signature defined on the JCO.Client class:
SAP Java Connector (JCo) API
public void execute(java.lang.String name,
JCO.ParameterList input,
JCO.ParameterList output,
JCO.ParameterList tables)
The vocabulary of this API comes from the domain of software, not the domain of customers and orders. When the execute method is invoked the work actually performed inside the EIS can focus on business entities. The vocabulary of the API is software-focused.
Because a single method can perform one of a number of different business functions, depending on the settings of its parameters, this type of API is considered a more abstract general-purpose API.
Working With Different Types of EIS APIs
After classifying your EIS API, there are three other important aspects of EIS APIs that determine whether they can be used effectively in resource adapters.
- The EIS API implementation itself should not have any implementation of connection pooling, or if the API has one it should also provide a way to disable pooling. The J2EE Connector Architecture suggests that the container - not the EIS API - is the appropriate place for connection pooling to occur.
- The EIS API should be thread-safe and should not start threads of its own.
- The EIS API should be synchronous.
When the application invokes a method in the EIS API it should wait until that method completes before proceeding. Although neither the J2EE Connector Architecture 1.0 nor the Connector Builder directly addresses asynchronous EIS APIs, it is possible to use Connector Builder to build part of an adapter that deals with an asynchronous API.
The remaining sections of this module refer to features of Connector Builder that are explained in detail throughout this guide. You can use the steps and procedures in this module as a guide, relying on the subsequent module s for full instructions on how to perform the tasks of defining, generating, and customizing the resource adapter.
The Model EIS API
Connector Builder's design center is a "model" EIS API possessing a certain combination of styles. The following table lists the styles of the model EIS API. The left column lists the type of characteristic and the right column lists what that characteristic is for the model EIS API.
The COTS sample EIS API included with the product exemplifies the model EIS API. When used with a model EIS API, Connector Builder provides these features that minimize the customization that needs to be implemented:
- You can identify connection parameters through the user interface.
- The generated input records contain instance variables and get and set methods that correspond directly to the non-connection input parameters.
- The generated output records contain an instance variable and get and set methods that correspond directly to the EIS API method's return value.
- The generated InteractionSpec for each EIS API method contains logic that maps the private connection and the input record to the EIS API input parameters, executes the EIS API method passing the correct parameter values, and maps the method's return value to the output record.
- You can specify XML-to-Java object transformations when you generate SOAP services.
- You can regenerate the adapter without losing any of the customizations you may have written since the previous generation.
You can use the product to generate resource adapters for virtually any combination of styles. The farther from the model a particular EIS API falls, the more customization or other manual work may be needed to build the adapter.
By recognizing all these basic aspects of an EIS API you can use the appropriate guidelines below to make the most effective use of Connector Builder in constructing an adapter.
Considering Implementation Language
Connector Builder is desgined to work with Java APIs. If you have an API in another implementation language, you can use Connector Builder, however you need to provide a Java wrapper around the non-Java API. You can then use Connector Builder with the Java wrapper to construct a resource adapter.
If the EIS API is expressed in C or C++, you can use the Java Native Interface (JNI) to build a Java wrapper for the non-Java API. The Java web site at:
http://java.sun.com provides full information about JNI and its tools.
The IDE includes the Native Connector Toolkit (NCT). You can use NCT to generate the required Java wrapper for a C++ API rather than use the JNI tools by hand yourself to do so. Because C++ is a superset of C, NCT works for either C or C++ APIs. For more information about NCT, refer to "Working with C/C++ API " of this guide and the Sun ONE Studio 4, Enterprise Edition documentation.
If your API is in a language other than C or C++ neither Java nor the IDE can offer any automated help to wrap that API with Java. You need to provide the Java wrapper yourself, perhaps by building a C wrapper first and then using Java or the IDE's tools to build the Java wrapper for the C wrapper.
Considering Method Input and Output Data Styles
Connector Builder can work with methods that use any or all of the various mechanisms described in Classifying by Method Input and Output Data Style. Some of the data handling techniques lend themselves to clearer applications or simpler resource adapters than others, as described in the next sections.
Data via Parameters and Return Values Only
The J2EE Connector Architecture specification directly addresses how applications can pass data to and get results from the EIS API through the resource adapter as part of the Record concept in the Common Client Interface (CCI). Connector Builder generates Record classes according to each method's parameters and return values in the EIS API. All the information required by or produced by the EIS API methods is passed explicitly between the caller and the method.
Data via Object State
Input or output accomplished through object state - private variables - may or may not be a problem.
In some cases, an object's state changes only as a side-effect of calling a method, as an integral part of the work the method performs. The state information is not used as a way for the caller to influence how the method executes, nor is it used as a way for the caller to find out the results of the method's execution. In such cases, neither the application nor the resource adapter needs to do anything beyond invoking the desired method to get the method to run correctly.
On the other hand, it is rare but possible that the object state is set by the caller before invoking a method as a way of affecting how the method does its work. Similarly, the object state could be inspected by the caller after invoking a method as a way of discovering the results of the method's execution.
In this case, to provide a particular method with all the input information it needs to do its work and to retrieve all the result information from the method's execution, the application or the resource adapter could need to:
- set the object state by invoking one or more setter methods,
- invoke the target method (receiving the method's result value), then
- retrieve any potentially changed object state by invoking one or more getter methods
This would complicate the application. Fortunately, this type of API is uncommon. But there are some issues you should keep in mind if you encounter one and want to build a resource adapter for it.
It would be very difficult to create SOAP services for this type of API. Each SOAP request is self-contained. A SOAP client cannot assume that successive SOAP requests, such as would be required to establish or retrieve object state before or after the method call, will be handled by the same connection inside the resource adapter. Further, the Java Interaction Object (JIO) as generated accounts only for the parameters and the return value defined for the method - not for any object state. This is also true for the generated SOAP service that is based on that JIO.
One approach to handling such an API would be to construct a wrapper class for the EIS API class.
To Construct a Wrapper Class for the EIS API Class
- Create the new wrapper class in the IDE.
- Define a shadow method on the wrapper class for each method on the EIS API class. (Do not create shadow methods for the getter and setter methods that work with the object's internal state.)
Use the method name from the EIS API class as the method name for the shadow method.
Throw the same exceptions from the shadow method as the EIS API method throws.
Set up the input parameters to the shadow methods to include:
all the input parameters accepted by the EIS API method, plus
added parameters corresponding to the internal object state that must be set before the EIS API method is invoked.
- If the EIS API method alters internal object state that the application needs to use:
Define a new class representing the full output from the EIS API method:
Add a private field and get and set methods for the return value from the EIS API method.
Add private fields and get and set methods to represent any internal object state variables that are affected by the EIS API method's execution.
Use this new class as the return type from the shadow method.
If the EIS API method does not change any internal object state, then use the return type of the EIS API method as the return type for the shadow method.
- Implement each shadow method so it:
Once you create the wrapper class and any required output value classes, you can use Connector Builder to define and generate an adapter based on the wrapper class. Because all data travels in and out of the wrapper method via input parameters and the return value, Connector Builder can generate a much better adapter.
Data via Environment
This type of EIS API is rare. Environmental settings, whether implemented as Java properties or operating system environment variables or the contents of files, are typically used for configuring an installation of an EIS API so that it performs differently from other installations but performs consistently within a single installation. This is in contrast to affecting the behavior of one or more methods from one call to the next.
Should you encounter such an EIS API that does use changing environmental data to affect a method's behavior, one approach would be to construct a wrapper class similar to the one in the data via object state case described earlier. As compared to their counterparts in the EIS API, the shadow methods in the wrapper class would have expanded parameter lists with new parameters to hold the environmental settings required for the EIS API method. And, as before, the result value from the wrapper methods might need to be new classes that include the result value for the EIS API plus any altered environmental values. Armed with this new wrapper class, you could create a resource adapter based on it instead of the actual EIS API.
Considering Connection Style
This section describes how you can use certain features of Connector Builder to the best advantage based on the connection style of the EIS API.
Background
Before continuing, it is worth reviewing the special consideration given to connections by the J2EE Connector Architecture and, therefore, the special treatment given to connections by Connector Builder.
Special Handling of Connections in the Connector Architecture
Hiding Physical Connections from Application
The architecture recognizes that connections to the EIS can be very expensive to create. As a result, while the specification does not require the application server or other containers to pool connections, it recognizes that this is a very common and useful technique for improving overall performance. Also, the security model described in the connector specification allows either the application or the container to provide the authentication for a new connection.
Because connections are authenticated and can be pooled, it is important for the application server to have control of the physical connections to the EIS. In particular, the application should not have access to the physical connection. Otherwise, the application could break the connection or change its state in other ways without the application server's knowledge. The application server's later attempts to reuse the connection might not work or might have undesirable side effects.
The J2EE Connector Architecture specifies that an instance of the javax.resource.cci.Connection interface, rather than the physical connection itself, should be supplied to the application. By specifying that the resource adapter should provide this sort of logical connection handle to the application, the architecture provides a way of preventing the application from making accidental or malicious changes to the physical connection without the application server's knowledge.
Establishing Physical Connections in the Resource Adapter
Because the application never deals directly with the physical connection, including establishing it in the first place, the resource adapter must take care of this step.
Most EIS APIs provide a method for explicitly creating a new connection to the EIS. This method accepts all the information needed to locate the EIS and establish communication with it, often including information such as a hostname, port number, username, and password. A stand-alone application (not using the connector architecture) calling the EIS API might obtain these values from the user and then pass them to the method that creates the connection.
The resource adapter gets these connection values from a set of configuration properties associated with the resource adapter. For example, an adapter's configuration properties might include properties named Hostname, PortNumber, Username, and Password. For a given instance of the adapter, the Hostname and PortNumber properties used for connecting to the EIS would need to be the same for all client applications that use that adapter instance. The system administrator would find out what these values should be, then set the configuration property values accordingly as the adapter is deployed and configured.
Depending on the specific adapter, values for other configuration properties might come from the application at run-time with each request for a connection, for example, the Username and Password might be such properties. The connector architecture specifically allows for these two categories of configuration properties.
Configuration property values are available at run-time to the adapter. When the adapter needs to establish a new physical connection to the EIS, it can retrieve the appropriate configuration property values and pass them to the EIS API method that physically connects to the EIS.
Special Handling of Connections in Connector Builder
To address these issues, Connector Builder treats connections especially in two important ways.
- The generated resource adapters protect the physical connection from the application code, in keeping with the J2EE Connector Architecture. The javax.resource.cci.Connection that the application receives from the generated resource adapter is not itself the actual physical connection to the EIS. Equally important, the generated resource adapter provides no way for the application to obtain the physical connection from the logical connection.
- In the connection-as-parameter style, the EIS API methods accept the physical connection as one of the parameters. Because the application does not receive a reference to the physical connection, it cannot pass the physical connection to the resource adapter for use in calling the methods in the EIS API. Instead, the adapter needs a way to
- recognize at design-time in which method parameter positions it should pass the physical connection
- pass at run-time the actual physical connection in those positions, on behalf of the application, when it calls the EIS API method.
Connector Builder generates the code required to do the second step. You need to do the first step. For more information and complete instructions and examples for how you indicate which method parameters should be treated as connection objects see Identifying Connection Objects in "Creating the Resource Adapter".
You also define the configuration properties for your resource adapter through the Connector Builder user interface. Create a configuration property for each value that is needed by the EIS API to open a new physical connection to the EIS. (You can define other configuration properties as well, but be sure to define at least those needed for making connections.) Further, you can specify which configuration property values can be supplied at run-time by a client that wants to use the adapter, such as the Username and Password properties in the example introduced earlier. (See Step 6 - Specifying Configuration Properties for more information.)
With this background, the following are three possible ways your resource adapter might handle connections:
Connection-less
You can use Connector Builder to build a resource adapter for a connection-less API. In most cases, such a resource adapter is not needed in order for applications to use the API. Instead, the application could use the API directly. This reduces development time because no adapter needs to be built. Deployment of the application is less complicated because there is no resource adapter required as part of the solution. This solution also performs better at run-time because the code path is shorter than it would be if an adapter were used.
You can use Connector Builder to generate SOAP services for methods in a connection-less API. You would follow the normal steps of defining, generating, and customizing the adapter.You might not nee to define any configuration properties since no physical connection is ever necessary. You still need to provide the mandatory customizations (see Mandatory Customization Points in "Customizing the Generated Resource Adapter") even though they might not contain any productive logic.
Connection-as-parameter
Recall that an EIS API in the connection-as-parameter style typically includes a method that establishes communication with the EIS and returns a connection handle. Other methods accept that connection handle as one of perhaps several parameters.
You should review each of the methods in the EIS API you want the adapter to support and, for each, note which parameter (if any) is the physical connection.
Once you identify the connection parameters to the product, Connector Builder can generate the appropriate connection-handling code. You do not need to implement any customizations related to passing connections as parameters for APIs in the connection-as-parameter style.
As an example, the COTS sample API includes this method (among others):
COTS getCustomer Method
public static Customer getCustomer(COTSEISConnection conn,
int custId )
The first parameter is the physical connection. In the user interface, you would click the Connection check-box next to the COTSEISConnection parameter but not the one next to the int. This triggers the special connection handling for the first parameter but not for the second, just as you want.
Connection-as-target
Some EIS APIs use the connection object as the target of method invocations, rather than as parameters to methods on other classes. There are two different techniques you can use to generate an adapter for this style of API.
Customize ManagedConnection.getInstance
You can implement an optional customization in one of the generated classes in the resource adapter.
In any EIS API, the methods are defined on one or more EIS classes. In order to invoke such a method at run-time, any generated adapter needs to have an instance of the correct class on which it can perform the method invocation. As a generated adapter runs, it uses the method getInstance on the generated ManagedConnection class to obtain an instance of the class to use for the method invocation. (This method is not prescribed by the connector specification; it is a compatible extension to the specification provided by Connector Builder.) The generated adapter includes a default implementation of this method that simply instantiates the required class and returns the new instance. The adapter then uses that instance for the method invocation.
For a connection-as-target EIS API, the adapter needs to invoke the method on the previously-created physical connection object. You can accomplish this by overriding the ManagedConnection.getInstance implementation with one of your own that returns the physical connection. You can do this because the base class for the generated ManagedConnection class includes a protected method getEISConnection which returns the physical connection to the EIS that was previously established.
Consider the LDAP example again. The LDAPConnection class itself includes the following methods (among others):
The generated adapter includes a class named LDAPManagedConnection.
- Using Connector Builder define and generate the adapter based on the LDAPConnection class.
Mount the directory or jar file that contains the LDAPConnection class into the IDE.
Start the Connector Builder Wizard to define the LDAP adapter.
To specify the EIS API, browse to the LDAPConnection class. Select the methods you want to make available to the application (such as search). You generally do not need to include the connect and disconnect methods. (See Step 4 - Mapping the EIS API in "Creating the Resource Adapter".)
Because none of the methods take a connection object as a parameter, do not click the Connection check-box for any of them.
Create adapter configuration parameters for all of the parameters to the connect method: Version, Host, Port, Dn, and Password. Select "Client Can Override" for Dn and Password.
- Perform the mandatory customizations to the generated adapter, as described in Mandatory Customization Points in "Customizing the Generated Resource Adapter".
- Perform the optional customization of implementing getInstance on the LDAPManagedConnection class as follows:
LDAPManagedConnection class
class LDAPManagedConnection {
...
public object getInstance(Class theClass) {
return this.getEISConnection();
}
- Build the adapter to incorporate the customizations.
At run-time, when the adapter invokes getInstance to obtain an instance of LDAPConnection on which to invoke a method such as search, it uses the actual LDAPConnection object that is the physical connection, thus providing a connection-as-target solution.
Use a Connection-as-parameter Wrapper Class
In this technique, you create a wrapper class that has the connection-as-parameter style implemented on top of the connection object in the EIS API. Then use Connector Builder to define and generated an adapter based on the wrapper class.
The following is an example of how you could build an adapter for the LDAPConnection API using this technique.
To Build an Adapter for the LDAPConnection API
- Wrap LDAPConnection as a new class, LDAP in this example.
Identify the method on LDAPConnection that creates a new connection, in this case connect. Create a method on the new LDAP class that duplicates the signature of that method from the LDAPConnection class. The wrapped version of method returns the LDAPConnection instead of void.
For each other method, copy the signature of the original method but add a parameter of type LDAPConnection as the first parameter. Then implement each such shadow method to first make sure that the LDAPConnection is not null and then invoke the corresponding method on the LDAPConnection, passing the parameters (except the LDAPConnection parameter) through and returning the result. For examples, see the connect, search, and disconnect methods below.
You may find a private utility method such as checkConnection useful. This method throws the standard IllegalStateException if a wrapper class method is called with a null LDAPConnection parameter. Each shadow method can invoke checkConnection before delegating its method invocation to the actual LDAPConnection object.
- Using Connector Builder define and generate the resource adapter based on the LDAP wrapper class.
Mount the directory that contains your new LDAP class into the IDE.
Start the Connector Builder Wizard to define the new LDAP adapter.
To specify the EIS API, browse to your newly-defined LDAP class. Select the methods you want to make available to the application (such as search). You generally do not need to include the connect and disconnect methods. (See Step 4 - Mapping the EIS API in "Creating the Resource Adapter".)
For each method you add to the mapped method list click the Connection check-box next to the LDAPConnection parameter. This triggers the special handling for this parameter.
Create adapter configuration parameters for all of the parameters to the connect method: Version, Host, Port, Dn, and Password. Select "Client Can Override" for Dn and Password.
- Perform the mandatory customizations to the generated adapter, as described in Mandatory Customization Points in "Customizing the Generated Resource Adapter".
- Build the adapter to incorporate the customizations.
Considering EIS API Abstraction Level
Connector Builder supports EIS APIs at either level of abstraction, either general-purpose or specific. The abstraction level greatly influences how much of the adapter can be generated and how much must be provided through customization.
Specific EIS APIs
With EIS APIs that are specific, namely where the method and parameter names come from the application domain, Connector Builder can generate almost all of the resource adapter. For each method you select from the EIS API, the product generates a group of classes related to that method: the InteractionSpec, the input Record, the output Record, and the JIO. (Refer to Naming Conventions for Generated Classes in ""Customizing the Generated Resource Adapter" for more information.)
For example, if you select the getCustomer method from the COTS API example and then generate an adapter, the product generates the classes COTSAPIGetCustomerISpec, COTSAPIGetCustomerInputRecord, and COTSAPIGetCustomerOutputRecord, and COTSAPIGetCustomer.
An application can use the first three classes to invoke the getCustomer method in the COTS API using the connector architecture's CCI. To do so, the application creates new instances of each class, uses the input record's setter methods to set the values of the method's input parameters, then invokes the execute method on the generated ISpec class. After the execute method returns, the application uses the getter method defined on the generated output record class to retrieve the return value provided by the getCustomer method.
Alternatively, the application can invoke getCustomer through the adapter using the JIO style. Although the generated JIOs are not part of the J2EE Connector Architecture they are compatible extensions that provide a more natural way for an application to use the resource adapter to invoke the EIS API's methods. This is because each JIO provides an executeAPI method signature that includes the same input parameters that the corresponding EIS API method has, excluding connection parameters. The application would instantiate the JIO class and invoke its executeAPI method, passing the appropriate values for the input parameters and working with the return value that the JIO passed through from the EIS API method. Each JIO also provides an execute method that accepts the CCI-compatible input and output Records.
Because the Connector Builder generates these finely-tuned classes for each method in a specific EIS API, only a few mandatory customizations to implement before the resource adapter is complete need to be made. These customizations are described in Customizing the Resource Adapter.
General-purpose EIS APIs
General-purpose EIS APIs tend to expose one or a few execute methods that accept as parameters:
- some indication of what EIS task to perform (such as retrieve a customer),
- a generic input data structure that can accommodate the input data required for any EIS task, and
- a generic output data structure that can hold the results from any EIS task.
There is very little information available from a general-purpose EIS API itself that Connector Builder can use to generate the code that invokes the EIS API methods.
The best way to work with general-purpose EIS APIs is to generate template interaction specs using Connector Builder. In this case, you need to completely customize the generated InteractionSpec and input and output Record classes. For more information refer to Edit Template InteractionSpec in "Modifying the Resource Adapter Definition".
The DBMS sample adapter included with the product uses a general-purpose EIS API, namely the JDBC API. Refer to the module s about the DBMS sample in the Sun ONE Connector Builder Installation and Getting Started Guide.
Looking at what the application must do and what the resource adapter must do helps to clarify some of the differences between an adapter for a specific EIS API and one for a general-purpose API.
In particular, the roles and usage of the Interaction, InteractionSpec, and Record classes are much different. In an adapter for a general-purpose API, often only a single InteractionSpec class is used. The application instantiates the InteractionSpec class and assign to the InteractionSpec's function name the name of the EIS task that the application wants to invoke. Then the application needs to instantiate and prepare an instance of the Record class so it contains the input data for the method in the correct format. The application needs to know, based on which EIS task it is about to use, how to format the input data correctly so it can be supplied through the Record. Similarly, and depending on the specific general-purpose API, the application might need to prepare a Record in the correct format that holds the results of the EIS task.
Having prepared the records and the InteractionSpec, the application obtains an Interaction and invoke its execute method, passing the InteractionSpec and Record instances. Once execute returns, the application needs to interpret the contents of the output Record to extract the EIS task's results.
You should customize the Interaction class so it can work with the InteractionSpec and Records as well as with the EIS API. For example, the Interaction.execute method needs to interrogate the InteractionSpec to find out which EIS task should be run. Perhaps based on this information, it then needs to know how to extract information from the input Record and prepare any EIS-specific data structure that conveys the input data to the EIS API method. Then the Interaction can use the EIS API's execute method to perform the work. Once API's execute method completes, the Interaction's execute method needs to interpret any output data structure returned from the EIS - the details of which may depend on which specific EIS task was run - and prepare the output Record with those results for use by the application.
You must provide this logic as customizations because Connector Builder has no way to discover these details on its own and to generate the required logic afterwards.
Summarizing EIS API Classification
One of your first steps in planning the construction of a resource adapter should be to determine what classifications best describe the EIS API of interest. Once you understand what sort of API you are working with, you can optimize the use of the Connector Builder features to generate and customize a resource adapter.
Other sections of this guide provide more detailed information on the steps outlined in this module for defining, generating, and customizing the resource adapter. As you read them, keep in mind that you may use those features differently depending on the type of EIS API you are working with. The COTS and DBMS sample adapters included with the product provide concrete, working examples for two of the common combinations of EIS API classifications. Refer to the sample adapters and to the COTS sample application for more information.