piotrp 2002/12/15 23:23:24
Added: java/doc/wsdl_extensions/j2c_extensions WSDLJ2EE.gif
wsif_j2.gif TextJ2C.gif wsif_j2c_extensions.htm
WSIFForm.gif WSDLConn.gif wsif_j1.gif
Log:
Move documentation for the WSIF J2C provider from proposals
to the docs.
Revision Changes Path
1.1
xml-axis-wsif/java/doc/wsdl_extensions/j2c_extensions/WSDLJ2EE.gif
<<Binary file>>
1.1
xml-axis-wsif/java/doc/wsdl_extensions/j2c_extensions/wsif_j2.gif
<<Binary file>>
1.1
xml-axis-wsif/java/doc/wsdl_extensions/j2c_extensions/TextJ2C.gif
<<Binary file>>
1.1
xml-axis-wsif/java/doc/wsdl_extensions/j2c_extensions/wsif_j2c_extensions.htm
Index: wsif_j2c_extensions.htm
===================================================================
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>WSIF J2C Extensions</title>
</head>
<body>
<h2>WSIF Extensions for J2EE Connector Architecture</h2>
<p><font FACE="Verdana" SIZE="2">The WSIF Extensions for J2EE Connector
Architecture (J2C) allow Enterprise Information Systems (EIS) to
provide the following:</font></p>
<ul>
<li><font size="2" face="Verdana">Modeling of interactions with the EIS as
services, using WSDL.</font></li>
<li><font size="2" face="Verdana">Execution of interactions with the EIS using
WSIF.</font></li>
<li><font face="Verdana" size="2">Implementation of the Import
Service that exposes EIS metadata in WSDL.</font></li>
</ul>
<p><font FACE="Verdana" SIZE="2">J2EE Connector Architecture 1.0 (specification
available at:
"http://java.sun.com/j2ee/download.html#connectorspec") provides a
runtime architecture that allows EIS Resource Adapters to plug into a J2EE
Application Server environment. The WSIF Extensions for J2C extend it to bring
the Resource Adapters into the world of services and also make them pluggable
into tool environments. The extensions specify the format of metadata that an
EIS must provide and define how a tool environment interacts with an EIS to get
this
information, i.e. define the Import Service with operations to
list and import the EIS metadata in the tool environment independent manner.
The extensions also show how the EIS
provides code generation contributions. To support the execution of
interactions, the extensions provide a set of
classes and interfaces that allow EIS to easily, especially if Resource
Adapter supports CCI, implement its specific WSIF provider. </font></p>
<h3><a name="Metadata support">Modeling</a></h3>
<p><font FACE="Verdana" SIZE="2">Metadata support is important from two
perspectives. First, tools want to be
able to discover meta information about the functions offered by an EIS. The
tools then aid a developer in building components (for example, Java Beans, EJBs
and others) that use these functions.
runtimes either drive a connector
through code generated by the tools from the metadata, or they are engines that
drive a connector by interpreting the metadata.</font></p>
<h4>WSDL</h4>
<p><font size="2" face="Verdana">The following picture shows the WSDL document
architecture. Shown at the top
are the sections that allow you to describe a service interface in an abstract
way. WSDL prefers to use XML Schema as its canonical type system. The sections at
the bottom describe how and where to access the
concrete service that implements the abstract interface. Looking at the W in WSDL
may cause you to think that the language is for
describing Web Services only, but this is not true. The inventors equipped the
language with a smart extensibility mechanism, which allows you to describe any
kind of service, be it a Web Service or some legacy EIS service
(function).</font></p>
<p>
<img border="0" src="WSDLJ2EE.gif" alt="WSDL document architecture"
width="351" height="331" align="middle"></p>
<h5>WSDL and J2EE Connector Architecture - A Natural Fit</h5>
<p><font FACE="Verdana" SIZE="2">WSDL provides a standard way for describing which
services are offered by a
specific EIS instance, and how you access them. The J2EE Connector Architecture
provides a standard client programming model for accessing EIS services.</font></p>
<p><font FACE="Verdana" SIZE="2">If you look at the WSDL information that is
relevant for the single
execution of an operation you end up with a very natural fit between the
two:</font></p>
<p>
<img border="0" src="TextJ2C.gif" alt="Relationship between WSDL and J2EE terms"
width="294" height="90" align="center"></p>
<h4>Connector Binding</h4>
<p><font FACE="Verdana" SIZE="2">To invoke an operation through a connector we have
to be able to capture
meta information about the following aspects:</font></p>
<ul>
<li><font FACE="Verdana" SIZE="2">The connection properties to be set on a
ManagedConnectionFactory.</font></li>
<li><font FACE="Verdana" SIZE="2">The interaction properties to be set on an
InteractionSpec.</font></li>
<li><font FACE="Verdana" SIZE="2">The Records, for example, their structure and
the specific way that they
have to be formatted.</font></li>
<li><font FACE="Verdana" SIZE="2">The operation, which combines InteractionSpec,
input Record, and output Record (provided by WSDL). </font></li>
<li><font face="Verdana" size="2">A specific endpoint that offers particular
operation (provided by WSDL).</font></li>
</ul>
<p><font FACE="Verdana" SIZE="2">ManagedConnectionFactory describes location or
providing endpoint of the operation. The requirement for the Connector Binding is to
provide a port extension to capture this information.</font></p>
<p><font FACE="Verdana" SIZE="2">The InteractionSpec specifies the operation in a
way that is
understood by the endpoint. The Connector Binding is required to
provide an operation binding extension to capture this information.</font></p>
<p><font FACE="Verdana" SIZE="2">For Records you need to know their structure and
the way that they have to
be formatted so that an endpoint is able to interpret them. The structure is
defined by XML Schema from which you can derive a Java
representation, as described later. It is the format aspect that imposes a
requirement
on the Connector Binding. It has to provide a format binding extension to
capture the specific formatting information (see format binding
section).</font></p>
<h5>A Connector WSDL Sample</h5>
<p>
<img border="0" src="WSDLConn.gif" alt="Sample of a connector in a WSDL document"
width="550" height="560"></p>
<h5>How the Connector Binding Extends WSDL</h5>
<pre> <definitions .... >
<binding ...>
<<b>connector:binding /</b>>
<b>format:typeMapping</b> encoding="..."
style="...">
<<b>format:typeMap </b>
typeName="..."
formatType="..." /> *
</format:typeMapping>
<operation .... >
<<b>connector:operation</b> functionName="name"...
interaction attributes ... />
<input>
...
</input>
<output>
...
</output>
</operation>
</binding></pre>
<pre> <port .... >
<<b>connector:address</b> hostName="uri"
portNumber="..."
...connection attributes ... />
</port>
</definitions></pre>
<h6>connector:binding</h6>
<p><font FACE="Verdana" SIZE="2">The purpose of the connector binding is to signify
that the binding is bound
to a J2C based Resource Adapter. A "connector" is the short name
for the namespace that identifies the particular connector, for example </font>
<samp>
<font FACE="Verdana" SIZE="2"><cics:binding
/></font></samp></p>
<h6>connector:operation</h6>
<p><font FACE="Verdana" SIZE="2">The connector operation contains the
InteractionSpec attributes that are
necessary to execute the operation on the EIS side, for example </font> <samp>
<font FACE="Verdana" SIZE="2"><cics:operation
functionName="GETCUST" /></font></samp></p>
<h6>connector:address</h6>
<p><font FACE="Verdana" SIZE="2">The connector address contains the attributes
of the ManagedConnectionFactory, necessary to configure the connection factory, for
example </font> <samp>
<font FACE="Verdana" SIZE="2"><cics:address
connectionURL="..." serverName="..." /></font></samp></p>
<h4>Format Binding</h4>
<h5>format:typeMapping</h5>
<p><font FACE="Verdana" SIZE="2">The format typeMapping identifies the style and
encoding of the native
types. The typeMapping contains format typeMaps which associate the logical
format (XML Schema) with the native format.</font></p>
<p><font FACE="Verdana" SIZE="2">The native format is identified by a format type
identifier.</font></p>
<p><font FACE="Verdana" SIZE="2">Here a sample where the native format type is
described by COBOL:</font></p>
<pre> <format:typeMapping encoding="COBOL" style="COBOL"
>
<format:typeMap typename="Customer"
formatType="CustomerInfo.ccp:CUSTINF"/>
</format:typeMapping></pre>
<h3><a name="Web Service Invocation Framework (WSIF)">Runtime</a></h3>
<p><font FACE="Verdana" SIZE="2">This standard way for describing the services that
reside in an EIS
using WSDL simplifies the current client programming model (CCI)
by using Web Service Invocation Framework (WSIF), a WSDL based service invocation
runtime. </font></p>
<h4>Architecture</h4>
<p><font FACE="Verdana" SIZE="2">The first thing necessary to set up for a service
invocation is a
port. Ports are factored from services (implementations of
the WSIFService interface). WSIF ships the base service factory
(WSIFServiceFactory)
which is
configured using the WSDL document, the service name, and the portType name from
which you want to create a port to access an operation.</font></p>
<p><font FACE="Verdana" SIZE="2">Additionally, the WSIFService
is configured using a binding specific dynamic providers (implementations of the
WSIFProvider interface). These providers are the actual
factories of the binding specific ports (implementations of the WSIFPort
interface)</font></p>
<p><font FACE="Verdana" SIZE="2">The actual port implementation is not visible
to the client.
The client uses the WSIFPort interface to create a specific
operation for driving an execution. </font></p>
<p>
<img border="0" src="wsif_j1.gif" width="666" height="495"></p>
<h4>WSIF and J2C</h4>
<p><font FACE="Verdana" SIZE="2">Enabling a J2C connector for WSIF is very
straightforward. The element that
a Resource Adapter must implement is the dynamic provider. Depending on
the native
format, a Resource Adapter may need to provide a specific message implementation.
In general the Resource Adapter does not have to provide a specific port and
operation implementation, since the WSIF Extensions for J2C provide a generic one
that is based on
J2C CCI.</font></p>
<p>
<img border="0" src="wsif_j2.gif" width="575" height="467"></p>
<p> </p>
<p><font FACE="Verdana" SIZE="2">If the Resource Adapter's native format is stream
based then
it can use the
provided WSIFMessage_JCAStreamable as it's message implementation. This class
extends a class named WSIFMessage_JCA. If a specific message
implementation is required, it should extend WSIFMessage_JCA.</font></p>
<p><font face="Verdana" size="2">The J2C WSIF Provider runtime implementation
contains the following classes/interfaces in the package </font><font FACE="Helv"
COLOR="#0000ff" size="2">
org.apache.wsif.providers.jca.</font></p>
<dir>
<font FACE="Helv" size="2">
<li>WSIFMessage_JCA.java - Top level superclass for all J2C WSIF messages
which implements javax.resource.cci.Record interface and is extended by the
connector specific messages.</li>
<li>WSIFMessage_JCAStreamable.java - Specialization of WSIFMessage_JCA for
connectors that use the Streamable interface.</li>
<li>WSIFOperation_JCA.java - Implementation of the WSIFOperation interface, which
executes the interaction with the EIS.</li>
<li>WSIFPort_JCA.java - JCA specific implementation of the WSIFPort, which is
used to
create an operation.</li>
<li>WSIFProviderJCAExtensions.java - Interface implemented by the specific
connector to provide creation of the Connection and InteractionSpec objects</li>
<li>WSIFFormatHandler_JCA.java - Interface implemented by FormatHandlers for
connectors that use the Streamable record interface. </li>
<li>WSIFBindingOperation_JCAProperty.java - Interface used to expose the
InteractionSpec properties as parts in the WSIF message.</li>
<li>WSIFUtils_JCA.java - A utility class which contains methods to lookup
ConnectionFactory in the JNDI context</li>
<li>WSIFResource_JCA.java - Resource implementation for error messages</li>
<li>WSIFResource_JCA.properties - Separated Error Messages</li>
<dir>
</font><font FACE="Helv" SIZE="1">
<dir>
<p> </p>
</dir>
</font>
</dir>
</dir>
<h4><a name="Format Handling">Format Handling</a></h4>
<p><font FACE="Verdana" SIZE="2">Format handling is about marshalling the Java
representation of a data
structure described by XML Schema to/from its binding dependent native format.
Separating the Java representation and format handling enables late binding, and
prevents the service client logic from using objects that are binding
specific.</font></p>
<h5>FormatHandler</h5>
<p><font FACE="Verdana" SIZE="2">On service invocation, messages (input, output,
fault) get exchanged with the
provider of the service. Messages consist of typed parts. In order
for the provider to understand them the invocation runtime has to transform
them into the providers native format.</font></p>
<p><font FACE="Verdana" SIZE="2">Looking at the WSDL, it can be seen that a binding
section defines type mappings
that map the XML Schema types to respective native types. Given the meta
information from the WSDL the user can generate two runtime elements. One is
a bean as the Java representation of the structure described by XML Schema. The
other is a FormatHandler which is generated based on the defined format
typeMapping.</font></p>
<p>
<img border="0" src="WSIFForm.gif" alt="Format handler" width="471"
height="340"></p>
<p><font FACE="Verdana" SIZE="2">In order for a message implementation to produce
its native format it uses
the format handlers for its respective part types. The message is a generic
implementation for a particular provider. So how does the message know which
format handler to use for its parts? A runtime message knows about the meta
information of the concrete message it was factored for. So it knows what type
its parts have. These types have qualified names (namespace and localname).The rule
for constructing the name of the format handler is:</font></p>
<pre><reversed xsd typenamespace>.<binding shortname>.<format
encoding+style>.<xsd typelocalname>"FormatHandler"</pre>
<p><font FACE="Verdana" SIZE="2">The WSIFUtil class, in WSIF, provides a set of
utility methods that
can be
used in the message implementation (for example to use the above formula) as well
as in the implementation of the
format handler generator. Besides being able to handle a bean derived from the XSD
Schema type, the
format handler can in addition also support instance of the XSD Schema type in form
of a
DOMSource or SAXSource. This allows for direct usage of XML in your service
invocation if required.</font></p>
<h5>FormatHandler Generator</h5>
<p><font FACE="Verdana" SIZE="2">To support EIS native formats the Resource
Adapter has to provide format handler generators with its WSIF J2C Extensions. Each
format handler generator generates format handlers for
a specific encoding and style, possibly using the type mapping information from
the FormatBinding. The generator implements FormatHandlerGenerator interface
described later. </font></p>
<h3><a name="Import Service">Import Service</a></h3>
<p><font FACE="Verdana" SIZE="2">Many EIS's have very rich metadata support
describing the services they
offer. EIS's provide programmatic access to this meta information. This poses a
problem for tools in that
the form of the metadata and the access to it is proprietary
for each EIS. The EIS import service solves this problem by providing a
standard interface for accessing the meta information, and it delivers the meta
information in the standard
form of WSDL. The EIS implements (i.e. provides bindings and service of the
import service) the import service with its EIS Resource Adapter. </font></p>
<h4>Interface</h4>
<p><font FACE="Verdana" SIZE="2">The Import interface consists of three operations
getPortTypes, getDefinition
and </font><font SIZE="2">getRawEISMetaData. </font></p>
<p><font FACE="Verdana" SIZE="2">The getPortTypes operation allows you to get an
overview about the
interfaces and operations the EIS offers. The operation returns an array of
portTypes, the number of portTypes returned can be controlled through the
queryString input argument (supporting the queryString is optional).</font></p>
<p><font FACE="Verdana" SIZE="2">Note, if your EIS does not have the notion of
interfaces you can just
return one portType containing all the operations your EIS offers.</font></p>
<p><font FACE="Verdana" SIZE="2">The getDefinition operation allows you to retrieve
the complete service
definition for a chosen portType selection. Besides selecting the portType, the
portType selection allows a subset of the portType by identifying the operations
that you are interested in. The operation returns the WSDL definition, and an
array of XML Schema sources for the case when the portType uses XML Schema complex
types.</font></p>
<p><font face="Verdana" size="2">The optional operation, </font><font SIZE="2">
getRawEISMetaData returns a binary data that may be used by the Resource
Adapter to cache the EIS metadata repository. </font></p>
<h4><b>Import.wsdl file</b></h4>
<font SIZE="2">
<p><?xml version="1.0" encoding="UTF-8"?></p>
<p><definitions name="ImportRemoteInterface"</p>
<p>
targetNamespace="http://importservice.jca.providers.wsif.apache.org/"</p>
<p>
xmlns="http://schemas.xmlsoap.org/wsdl/"</p>
<p>
xmlns:tns="http://importservice.jca.providers.wsif.apache.org/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"></p>
<p> <import
location="Import.xsd"
namespace="http://importservice.jca.providers.wsif.apache.org/"/></p>
<p> <message
name="getDefinitionRequest"></p>
<p> <part
name="portTypeSelection" type="tns:PortTypeSelection"/></p>
<p> </message></p>
<p> <message
name="getDefinitionResponse"></p>
<p> <part
name="result" type="tns:ImportDefinition"/></p>
<p> </message></p>
<p> <message
name="getPortTypesRequest"></p>
<p> <part
name="queryString" type="xsd:string"/></p>
<p> </message></p>
<p> <message
name="getPortTypesResponse"></p>
<p> <part
name="result" type="tns:PortTypeArray"/></p>
<p> </message></p>
<p> <message
name="getRawEISMetaDataRequest"></p>
<p> <part
name="queryString" type="xsd:string"/></p>
<p> </message></p>
<p> <message
name="getRawEISMetaDataResponse"></p>
<p> <part
name="result" type="xsd:base64"/></p>
<p> </message></p>
<p> <portType
name="Import"></p>
<p>
<operation name="getDefinition"
parameterOrder="portTypeSelection"></p>
<p>
<input message="tns:getDefinitionRequest"
name="getDefinitionRequest"/></p>
<p>
<output message="tns:getDefinitionResponse"
name="getDefinitionResponse"/></p>
<p>
</operation></p>
<p>
<operation name="getPortTypes"
parameterOrder="queryString"></p>
<p>
<input message="tns:getPortTypesRequest"
name="getPortTypesRequest"/></p>
<p>
<output message="tns:getPortTypesResponse"
name="getPortTypesResponse"/></p>
<p>
</operation></p>
<p>
<operation name="getRawEISMetaData"
parameterOrder="queryString"></p>
<p>
<input message="tns:getRawEISMetaDataRequest"
name="getRawEISMetaDataRequest"/></p>
<p>
<output message="tns:getRawEISMetaDataResponse"
name="getRawEISMetaDataResponse"/></p>
<p>
</operation></p>
<p> </portType></p>
<p></definitions></p>
</font>
<pre> </pre>
<h5>Import Service support classes</h5>
<p><font FACE="Verdana" SIZE="2">To simplify the implementation of the Import
service, the WSIF Extensions for J2C include a set of convenience classes in
the </font><font FACE="Helv" COLOR="#0000ff" size="2">
org.apache.wsif.providers.jca.toolplugin </font><font size="2" face="Verdana">
package. These classes provide Java representation of the XSD types used in the
import service and simplify the development of the Import Service. </p>
</font>
<dir>
<font FACE="Helv" size="2">
</dir>
<blockquote>
<ul>
<li>ImportDefinition.java</li>
<li>ImportResource.java</li>
<li>ImportXSD.java</li>
<li>OperationSelection.java</li>
<li>PortTypeArray.java</li>
<li>PortTypeSelection.java</li>
</ul>
</blockquote>
</font>
<h3> </h3>
<h3>Deployment Descriptor</h3>
<p><font FACE="Verdana" SIZE="2">To allow an arbitrary tools environment to
detect this additional capability a connector implementation has to provide the
following deployment descriptor xml file (j2c_plugin.xml) in its rar file. It
describes
details of the implementation, for example the names of classes implementing
extensibility
elements or the name of the WSDL file providing bindings for the Import service
interface. A sample of the xml file is shown below: </font></p>
<p> </p>
<blockquote>
<blockquote>
<pre><font face="Courier New"><j2c_plugin
tns="http://schemas.xmlsoap.org/wsdl/myeis/"
name="MyEIS"></font></pre>
<pre><font face="Courier
New"><Description>MyEIS</Description></font></pre>
<pre><font face="Courier New"><version>1.0</version></font></pre>
<pre><font face="Courier New"> <wsdl_extensions></font></pre>
<pre><font face="Courier New"> <address
classname="com.myeis.wsdl.extensions.j2c.myeis.MyEISAddress"/></font></pre>
<blockquote>
<blockquote>
<blockquote>
<pre><font face="Courier New"> <binding
classname="com.myeis.wsdl.extensions.j2c.myeis.MyEISBinding"/>
</font></pre>
</blockquote>
</blockquote>
</blockquote>
<pre><font face="Courier New"> <operation
classname="com.myeis.wsdl.extensions.j2c.myeis.MyEISOperation"/></font></pre>
<pre><font face="Courier New"> <extension_registry
classname="com.myeis.wsdl.extensions.j2c.myeis.MyEISExtensionRegistry"
/></font></pre>
<pre><font face="Courier New"> </wsdl_extensions></font></pre>
<pre><font face="Courier New"> <wsif_extensions
classname="com.myeis.wsif.providers.j2c.myeis.WSIFProvider_MyEIS"
/></font></pre>
<pre><font face="Courier New"> <import></font></pre>
<pre><font face="Courier New"> <service
wsdlfile="com/myeis/j2c/importservice/myeis/ImportMyEIS.wsdl"
servicename="ImportService" ></font></pre>
<pre><font face="Courier New"> </service></font></pre>
<pre><font face="Courier New"> </import> </font></pre>
</blockquote>
<pre><font face="Courier New"> <formathandler</font></pre>
<blockquote>
<pre><font face="Courier New"> <generator encoding="myeis"
classname="com.myeis.j2c.myeis.formathandler.MyEISFormatHandlerGenerator"
/></font></pre>
<pre><font face="Courier New"> </formathandler></font></pre>
<pre><font face="Courier New"></j2c_plugin></font></pre>
</blockquote>
</blockquote>
<h3>Sample Resource Adapter</h3>
<p><font size="2">The distribution of the WSIF Extensions for Connector
Architecture includes a sample Resource Adapter, MyEIS, illustrating how to
extend the Connector to enable it for pluggability into tool environments,
implement model and runtime extensions and the Import Service. </font></p>
</body>
</html>
1.1
xml-axis-wsif/java/doc/wsdl_extensions/j2c_extensions/WSIFForm.gif
<<Binary file>>
1.1
xml-axis-wsif/java/doc/wsdl_extensions/j2c_extensions/WSDLConn.gif
<<Binary file>>
1.1
xml-axis-wsif/java/doc/wsdl_extensions/j2c_extensions/wsif_j1.gif
<<Binary file>>
