You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by ow...@apache.org on 2003/01/14 15:19:10 UTC
cvs commit: xml-axis-wsif/java readme.html
owenb 2003/01/14 06:19:09
Modified: java/doc customising.html developers-guide.html
quick-start.html user-guide.html
Added: java/doc tests.html run.html faq.html trace.html build.html
how_to_wsdl_extensions.html how_to_provider.html
mime_attachments.html
java/doc/wsdl_extensions/j2c_extensions
wsif_j2c_extensions.html
java/doc/wsdl_extensions jms_bindings.html
java readme.html
Log:
- Change all HTML files to use the extension .html for consistency
- Update links to these files.
- Leave old .htm files in CVS until xml-site pages have been updated to point to the new .html files
Revision Changes Path
1.4 +8 -8 xml-axis-wsif/java/doc/customising.html
Index: customising.html
===================================================================
RCS file: /home/cvs/xml-axis-wsif/java/doc/customising.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- customising.html 20 Dec 2002 14:41:42 -0000 1.3
+++ customising.html 14 Jan 2003 14:19:08 -0000 1.4
@@ -21,19 +21,19 @@
that you can then access this software using WSIF's APIs. To do
this, you need to take care of the following:</p>
<ol>
- <li><a href="how_to_wsdl_extensions.htm">Writing your own WSDL
+ <li><a href="how_to_wsdl_extensions.html">Writing your own WSDL
extensions to support new protocols</a></li>
- <li><a href="how_to_provider.htm">Writing your own WSIF
+ <li><a href="how_to_provider.html">Writing your own WSIF
providers to support customized WSIF extensions</a></li>
</ol>
<p>WSIF defines binding extensions so that EJBs, local java classes, software accessible over message queues using the JMS API and software that can be invoked using the Java Connector architecture can also be described in WSDL. WSIF is packaged with providers that allow transparent invocation of such software given the corresponding WSDL description. Here are the documents that describe these bindings:
<ul>
- <li><a href="wsdl_extensions/java_extension.htm">Local java binding extensions for WSDL</a></li>
- <li><a href="wsdl_extensions/ejb_extension.htm">EJB binding extensions for WSDL</a></li>
- <li><a href="wsdl_extensions/jms_bindings.htm">JMS binding extensions for WSDL</a></li>
- <li><a href="wsdl_extensions/j2c_extensions/wsif_j2c_extensions.htm">JCA binding extensions for WSDL</a></li>
+ <li><a href="wsdl_extensions/java_extension.html">Local java binding extensions for WSDL</a></li>
+ <li><a href="wsdl_extensions/ejb_extension.html">EJB binding extensions for WSDL</a></li>
+ <li><a href="wsdl_extensions/jms_bindings.html">JMS binding extensions for WSDL</a></li>
+ <li><a href="wsdl_extensions/j2c_extensions/wsif_j2c_extensions.html">JCA binding extensions for WSDL</a></li>
</ul>
-<p>You may find also useful to read about using <a href="mime_attachments.htm">Soap
- Attachments using WSIF</a> and always important when debugging - <a href="trace.htm">
+<p>You may find also useful to read about using <a href="mime_attachments.html">Soap
+ Attachments using WSIF</a> and always important when debugging - <a href="trace.html">
how to use tracing in WSIF</a>.<BR>
<BR>
1.2 +3 -3 xml-axis-wsif/java/doc/developers-guide.html
Index: developers-guide.html
===================================================================
RCS file: /home/cvs/xml-axis-wsif/java/doc/developers-guide.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- developers-guide.html 16 Dec 2002 18:29:05 -0000 1.1
+++ developers-guide.html 14 Jan 2003 14:19:08 -0000 1.2
@@ -12,10 +12,10 @@
<hr>
<ul>
<li><a href="cvs.html">Accessing source code</a></li>
- <li><a href="build.htm">Building WSIF</a></li>
+ <li><a href="build.html">Building WSIF</a></li>
<li><a href="customising.html">Customising your WSIF installation</a></li>
- <li><a href="tests.htm">Testing WSIF</a></li>
- <li><a href="trace.htm">Configuring WSIF tracing</a></li>
+ <li><a href="tests.html">Testing WSIF</a></li>
+ <li><a href="trace.html">Configuring WSIF tracing</a></li>
<li><a href="bugs.html">Reporting Bugs</a></li>
<li><a href="mail.html">Mailing lists</a></li>
</ul>
1.4 +2 -2 xml-axis-wsif/java/doc/quick-start.html
Index: quick-start.html
===================================================================
RCS file: /home/cvs/xml-axis-wsif/java/doc/quick-start.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- quick-start.html 16 Dec 2002 22:12:17 -0000 1.3
+++ quick-start.html 14 Jan 2003 14:19:08 -0000 1.4
@@ -16,10 +16,10 @@
WSIF_2_0_ALPHA2).</p>
<p><b>Getting started: </b>If you have downloaded binary package then you are ready to use WSIF: the
very first thing to do is to check provided samples. However before you start
-please read <a href="faq.htm">WSIF FAQ</a>. Then read about <a href="samples.html">
+please read <a href="faq.html">WSIF FAQ</a>. Then read about <a href="samples.html">
how to run the samples</a>. Otherwise if you downloaded source code or accessed it from CVS you will need
to build WSIF. To do this, first <a href="requirements.html">check that all
-prerequisites</a> are available. Then <a href="build.htm">proceed with
+prerequisites</a> are available. Then <a href="build.html">proceed with
building</a>.</p>
<p>After you have successfully downloaded and installed WSIF, you
can test your installation by <a href="samples.html">running the
1.4 +2 -2 xml-axis-wsif/java/doc/user-guide.html
Index: user-guide.html
===================================================================
RCS file: /home/cvs/xml-axis-wsif/java/doc/user-guide.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- user-guide.html 16 Dec 2002 21:15:08 -0000 1.3
+++ user-guide.html 14 Jan 2003 14:19:08 -0000 1.4
@@ -30,8 +30,8 @@
<ul>
<li><a href="wsdl_extensions/java_extension.html">Local java binding extensions for WSDL</a></li>
<li><a href="wsdl_extensions/ejb_extension.html">EJB binding extensions for WSDL</a></li>
- <li><a href="wsdl_extensions/jms_bindings.htm">JMS binding extensions for WSDL</a></li>
- <li><a href="wsdl_extensions/j2c_extensions/wsif_j2c_extensions.htm">JCA binding extensions for WSDL</a></li>
+ <li><a href="wsdl_extensions/jms_bindings.html">JMS binding extensions for WSDL</a></li>
+ <li><a href="wsdl_extensions/j2c_extensions/wsif_j2c_extensions.html">JCA binding extensions for WSDL</a></li>
</ul>
</p>
<p>The WSIF distribution includes samples that show you how to invoke such services using the WSIF API. The <a href="samples.html">Samples documentation</a> describes them.</p>
1.1 xml-axis-wsif/java/doc/tests.html
Index: tests.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="Author" content="Aleksander Slominski">
<meta http-equiv="Content-Style-Type" content="text/css">
<title>Web Services Invocation Framework: How to Build</title>
<link rel="stylesheet" href="wsif.css" type="text/css"></head>
<body alink="#0000ff" bgcolor="#ffffff" leftmargin="2" topmargin="2" marginwidth="2" marginheight="2">
<h1>
Web Services Invocation Framework: Unit Tests</h1>
<p>See <a href="run.html">the Tests document</a> for a guide to the tests and how to run them.</p>
<h2>How to build tests?</h2>
<p>TODO</p>
<h2>How to set environment to run tests?</h2>
<p>TODO</p>
<h2>How to execute tests?</h2>
<p> </p>
<hr width="100%">
<p><font style='font-size: 8pt; font-family: sans-serif' size="-3">last modified $Id: tests.html,v 1.1 2003/01/14 14:19:08 owenb Exp $ </font></p>
</body></html>
1.1 xml-axis-wsif/java/doc/run.html
Index: run.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="Author" content="Aleksander Slominski">
<meta http-equiv="Content-Style-Type" content="text/css">
<title>Web Services Invocation Framework: How to Run</title>
<link rel="stylesheet" href="wsif.css" type="text/css"></head>
<body alink="#0000ff" bgcolor="#ffffff" leftmargin="2" topmargin="2" marginwidth="2" marginheight="2">
<h1>
Web Services Invocation Framework: How to Run</h1>
<h2>Tests</h2>
<p>
WSIF has a number of unit tests found in the tests directory. These use Junit (currently Junit 3.7).
WSIF unit tests are loosely themed and test function in multiple providers. For instance
jms.JmsTest tests jms:address, jms:property and jms:propertyValue tags across the SoapJms,
AxisJms and NativeJms providers. You can either run a specific unit test or run all of them by
running util.WSIFTestRunner. wsif.test.properties has
wsif.test.components=ejb=on,jms=on,remotewsdl=on,jndi=on,fix=on,async=on
which allows you to switch off areas across all unit tests. So because I rarely change the EJB provider,
I run with ejb=off so when I run WSIFTestRunner none of the EJB tests get run. This can be dangerous
and it is generally better to run all the unit tests. Individual unit tests can call
TestUtilities.areWeTesting("ejb") for instance. There are various listeners needed to run the unit
tests (JMS2HTTPBridge, JMSAsyncListener, NativeJMSRequestListener) and unit tests automatically start
and stop the listeners that they need. All the tests need to find WSDL and other files on the
local filesystem. This is done by looking for the WSIF src, samples and tests directories under
the directory specified by the wsif.path property in wsif.test.properties. So I have wsif.path=c:\\wsif.
The setup required to run the unit tests is based on the various providers being used.
</p>
<p>
For Soap and Axis over Http, find all files called DeploymentDescriptor.xml in the samples and tests
directories and deploy them to your favourite web server. The web server must be running on your
localhost using port 8080. In the future localhost:8080 should be a property loaded from
wsif.test.propeerties. The level of soap or axis used on your
server does not have to be the same as the level used by WSIF. I use soap 2.2 on tomcat so I issue
java org.apache.soap.server.ServiceManagerClient http://localhost:8080/soap/servlet/rpcrouter deploy "samples\services\addressbook\DeploymentDescriptor.xml"
</p>
<p>
There is no setup to do to run tests under the Java provider.
</p>
<p>
To run tests using the EJB provider, ... todo ???
</p>
<p>
There are three providers that are enabled for Jms : Soap, Axis and NativeJms. Asynchronous support is
currently only supported over Jms, so to test out async you need Jms. Obviously you need a Jms
implementation. WSIF uses JNDI to lookup Jms queues and queue connnection factories. Topics are
not supported at the moment. The batch files samples\wsifjmssetup.bat and samples\wsifjmstidy.bat create
and delete the JNDI definitions for the Jms queues and queue connection factory needed to run the samples
and some of the unit tests. I use IBM MQSeries as my Jms implementation so the batch files
samples\wsifmqsetup.bat and samples\wsifmqtidy.bat create and delete the MQSeries queues needed to
run the samples and some of the unit tests. The batch files tests\wsiftestjmssetup.bat and tests\wsiftestmqsetup.bat create the
JNDI definitions and the MQSeries queues needed to run the unit tests. No code in WSIF or in the unit
tests is MQ-specific, except for these mq batch files and WSIFJMSFinderForMq. The unit tests also
assume the local queue manager is being used. The unit tests also assume that the JNDI database is on
the filesystem in \JNDI-Directory.
</p>
<p>
WSIF provides a JMS2HTTPBridge which takes soap messages from a Jms queue, routes them to a url and sends
the response message back to a replyTo queue. The JMS2HTTPBridge is intended as a test tool only.
So unit tests that test SoapJms and AxisJms start the JMS2HTTPBridge automatically. NativeJms requests
are served by the NativeJMSRequestListener which implements the backend service for our unit tests.
</p>
<p>
Specifying remotewsdl=on in wsif.test.components will enable the tests in the wsdl package to be run. These
tests test out loading wsdl from a url, from a jar file and test out imports. So you need
wsdl\ClassLoaderTest.jar on your classpath, and http://localhost:8080/wsdl/AddressBook.wsdl needs
to be available.
</p>
<p>
The intention is for all unit tests to be run by WSIFTestRunner so everyone runs them all automatically.
Unfortunately there are a few tests which cannot be run in this way (or rather I could not make them
run automatically). An example of this is the translated.messages tests, because these need to set the
locale, and I could not reset the locale multiple times in the same test.
</p>
<p>
The intention is for everyone to make sure that all the unit tests are kept working all the time, so
no regressions find their way in. If you add in new code (or even fixes) into WSIF, please add in new
unit tests, or extend existing tests to cover the new code you've added. Otherwise tomorrow someone
may unknowingly break your code. If you add in new unit tests please add them to WSIFTestRunner so
that everyone will automatically run them as well. I guess when you make a change that requires a
service to be redeployed or a queue definition to be added or changed, please notify everyone on
axis-dev so that everyone can update their setup.
</p>
<h2>Samples</h2>
<p>
TBW: general infomraiton about running samples (including Dynamic invoker), links to sample docs
</p>
<hr width="100%">
</body></html>
1.1 xml-axis-wsif/java/doc/faq.html
Index: faq.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="Author" content="Aleksander Slominski">
<meta http-equiv="Content-Style-Type" content="text/css">
<title>Web Services Invocation Framework FAQ</title>
<link rel="stylesheet" href="wsif.css" type="text/css"></head>
<body alink="#0000ff" bgcolor="#ffffff" leftmargin="2" topmargin="2" marginwidth="2" marginheight="2">
<h1>
Web Services Invocation Framework FAQ</h1>
<p>based on questions posted on discussion forum at
<a href="http://www.alphaworks.ibm.com/tech/wsif">http://www.alphaworks.ibm.com/tech/wsif</a>
</p>
<h2>What is official version of WSIF? How to get the latest version?</h2>
<p>
The official version of
WSIF can now be found on the Apache web site since WSIF was donated to
Apache a few months ago.
Version available from
<a href="http://www.alphaworks.ibm.com/tech/wsif">Alphaworks</a>
is no longer maintained and will be soon retired.
<p>
The Apache WSIF homepage can be found at:
<a href="http://xml.apache.org/axis/wsif">http://xml.apache.org/axis/wsif
</a>
<p>
Nightly builds are available at
<a href="http://cvs.apache.org/dist/axis/nightly/" target="_blank">http://cvs.apache.org/dist/axis/nightly/</a>
The wsif-src*.zip contains source distribution, the
wsif-bin* zip file contains a built wsif.jar along with the API Javadoc and
the wsif-all*.zip contains the source, the JAR and the javadocs. (* will be
replaced by the current version number in the file names).
<h2>What are differences between WSIF and WSTK?</h2>
<p>WSIF is a framework for invoking WSDL-described services. WSTK is IBM's Web Services Toolkit, a preview technology for web services support in Websphere available from alphaworks. WSTK includes WSIF amongst other things.</p>
<h2>What are differences between WSIF and Axis?</h2>
<p>Axis is an implementation of SOAP. It includes on the server-side infrastructure for deploying web service implementations and then routing SOAP messages between clients and those implementations. It also implements the JAX-RPC specification for invoking SOAP services.</p>
<p>WSIF is similar to the client piece of Axis, in that it is used for invoking services. However, WSIF's API is WSDL-driven and protocol independent; it allows protocol-specific code ("providers") to be plugged in. For invoking SOAP services, WSIF is in fact packaged with an Axis provider, that uses Axis APIs (i.e. JAX-RPC) to do the invocation. So WSIF operates at a more abstract level than Axis.</p>
<h2>What are differences between WSIF and JAX-RPC?</h2>
<p>JAX-RPC is an API for invoking XML-based RPC services - essentially its current scope is limited to invocation of SOAP services. WSIF is an API for invoking WSDL-described services, whether they happen to be SOAP services or not (for example, WSIF defines WSDL bindings so that EJBs, enterprise software acessible using JMS or the Java Connector architecture as wel as local java classes can all be described as first class WSDL services and then invoked using the same, protocol-independent WSIF API).</p>
<h2>How to use and set HTTP proxy with WSIF and SOAP over HTTP</h2>
<p>TODO: describe here current support for system properties etc.
<h2>Where are extensions to WSDL that are supported by WSIF documented?</h2>
<p>WSIF defines and supports the following WSDL bindings (besides the standard SOAP binding which is supported):
<ul>
<li><a href="wsdl_extensions/java_extension.html">Local java binding extensions for WSDL</a></li>
<li><a href="wsdl_extensions/ejb_extension.html">EJB binding extensions for WSDL</a></li>
<li><a href="wsdl_extensions/jms_bindings.html">JMS binding extensions for WSDL</a></li>
<li><a href="wsdl_extensions/j2c_extensions/wsif_j2c_extensions.html">JCA binding extensions for WSDL</a></li>
</ul>
</p>
<p>This means that using the WSIF API you can invoke a service, independent of whether it is made available over SOAP, as an EJB, over JMS, using java connectors or as a local java class.</p>
<h2>How do I define my own WSDL binding extensions and write WSIF providers for them</h2>
Here's <a href="how_to_wsdl_extensions.html">how to write your own WSDL
extensions to support new protocols</a>, and then
<a href="how_to_provider.html">write your own WSIF
providers to support customized WSIF extensions</a>.
<h2>How do I report problems and request new features?</h2>
<p>Please subscribe and post your questions to
<a href="http://xml.apache.org/axis/mail.html">AXIS mailing list</a>
(make sure to add [wsif] prefix to mail subject).
<h2>How do I select SOAP provider used in WSIF?</h2>
WSIF comes with an Apache Axis provider so using axis with WSIF is easy.
WSIF has two SOAP providers, one using Apache SOAP 2.3 and the other using Axis,
by default WSIF will use the Axis provider. The default is controlled by the
org.apache.wsif.util.WSIFPluggableProviders class. The javadoc for this class
gives details of how the default is defined, but it can be overridden
programmatically, for example, the following call sets the axis provider to be
the
default:<br>
<tt>WSIFPluggableProviders.overrideDefaultProvider("http://schemas.xmlsoap.org/wsdl/soap/",</tt><br>
<tt>new WSIFDynamicProvider_ApacheSOAP() );</tt><br>
<h2>How to use dynamic invoker sample?</h2>
<pre>java clients.DynamicInvoker http://www.xmethods.net/sd/2001/TemperatureService.wsdl getTemp 10570
Reading WSDL document from 'http://www.xmethods.net/sd/2001/TemperatureService.wsdl'
Preparing WSIF dynamic invocation
- WSIF0006W: Multiple WSIFProvider found supporting the same namespace URI 'http://schemas.xmlsoap.org/wsdl/soap/'. Found ('org.apache.wsif.providers.soap.apachesoap.WSIFDynamicProvider_ApacheSOAP, org.apache.wsif.providers.soap.apacheaxis.WSIFDynamicProvider_ApacheAxis')
- WSIF0007I: Using WSIFProvider 'org.apache.wsif.providers.soap.apachesoap.WSIFDynamicProvider_ApacheSOAP' for namespaceURI 'http://schemas.xmlsoap.org/wsdl/soap/'
Executing operation getTemp
Result:
return=56.0
Done!
</pre>
<h2>Sample DynamicInvoker and Complex Type handling in WSIF?</h2>
<p>WSIF does support complex types - of course XML schema
support is limited (but very reasonable).
<p>The DynamicInvoker doesn't support invocation of services using
complex types since this requires that java representations of the
complex types be generated first.
<p>It is also possible to extend DynamicInvoker to support
complex types but it will require some kind of intermediate
representation of values that can handle any complex type
(such as <a href="http://www.alphaworks.ibm.com/tech/jrom">JROM</a>...)
<hr width="100%">
</body></html>
1.1 xml-axis-wsif/java/doc/trace.html
Index: trace.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="Author" content="Mark Whitlock">
<meta http-equiv="Content-Style-Type" content="text/css">
<title>Using Trace</title>
<link rel="stylesheet" href="wsif.css" type="text/css"></head>
<body alink="#0000ff" bgcolor="#ffffff" leftmargin="2" topmargin="2" marginwidth="2" marginheight="2">
<h1>Using trace</h1>
<h2>Quick summary</h2>
<p>To switch WSIF trace on,in your log4j.properties specify the following
settings to trace to wsif.log....</p>
<code>
log4j.rootCategory=INFO, CONSOLE, LOGFILE<br>
log4j.logger.org.apache.wsif.*=DEBUG<br>
log4j.logger.com.ibm.wsif.*=DEBUG<br>
log4j.appender.LOGFILE=org.apache.log4j.FileAppender<br>
log4j.appender.LOGFILE.File=wsif.log<br>
log4j.appender.LOGFILE.Append=true<br>
log4j.appender.LOGFILE.Threshold=DEBUG<br>
</code>
<h2>For those who want to know more</h2>
<p>
WSIF uses Apache commons-logging for its messages and trace. See
http://jakarta.apache.org/commons/logging.html for more information.
Commons-logging is an API which wraps various log implementations.
You can configure commons-logging to use other log implementations,
or even your own. So commons-logging.jar must be on the classpath,
and log4j is the default
log implementation, although commons-logging.jar contains other log
implementations. You can configure commons-logging.properties to use
a different log implementation. If using log4j, you configure
log4j.properties to redirect trace and switch it on. The log4j.properties
settings above are only a subset of all possibilities.
</p>
<h2>Interpreting trace</h2>
<p>
Here is a sample trace output...</p>
<samp>
<nobr>7951 [main] DEBUG org.apache.wsif.* - ENTRY WSIFServiceFactory.newInstance()</nobr><br>
<nobr>8122 [main] DEBUG org.apache.wsif.* - EXIT WSIFServiceFactory.newInstance(org.apache.wsif.base.WSIFServiceFactoryImpl@7df10a36)</nobr><br>
<nobr>8132 [main] DEBUG org.apache.wsif.* - ENTRY WSIFServiceFactoryImpl.getService<7df10a36>(C:\wsad-5\eclipse\workspace\xml-axis-wsif\java\samples\addressbook\wsifservice\AddressBook.wsdl, <null>, <null>, http://wsifservice.addressbook/, AddressBook)</nobr><br>
<nobr>8252 [main] DEBUG org.apache.wsif.* - ENTRY PrivateCompositeExtensionRegistry.<init><43000a37>()</nobr><br>
<nobr>8893 [main] DEBUG org.apache.wsif.* - ENTRY JavaBindingSerializer.registerSerializer<576c0a36>(com.ibm.wsdl.extensions.PopulatedExtensionRegistry@50450a37)</nobr><br>
<nobr>8913 [main] DEBUG org.apache.wsif.* - EXIT JavaBindingSerializer.registerSerializer()</nobr><br>
<nobr>8943 [main] DEBUG org.apache.wsif.* - ENTRY FormatBindingSerializer.<init><40b48a36>()</nobr><br>
<nobr>8943 [main] DEBUG org.apache.wsif.* - EXIT FormatBindingSerializer.<init>()</nobr><br>
<nobr>9223 [main] DEBUG org.apache.wsif.* - ENTRY FormatBindingSerializer.registerSerializer<40b48a36>(com.ibm.wsdl.extensions.PopulatedExtensionRegistry@50450a37)</nobr><br>
<nobr>9243 [main] DEBUG org.apache.wsif.* - EXIT FormatBindingSerializer.registerSerializer()</nobr><br>
<nobr>9293 [main] DEBUG org.apache.wsif.* - ENTRY EJBBindingSerializer.registerSerializer<55a24a36>(com.ibm.wsdl.extensions.PopulatedExtensionRegistry@50450a37)</nobr><br>
<nobr>9323 [main] DEBUG org.apache.wsif.* - EXIT EJBBindingSerializer.registerSerializer()</nobr><br>
<nobr>9333 [main] DEBUG org.apache.wsif.* - EXIT PrivateCompositeExtensionRegistry.<init>()</nobr><br>
<nobr>9353 [main] DEBUG org.apache.wsif.* - ENTRY WSIFDynamicTypeMap.<init><32128a36>()</nobr><br>
<nobr>9353 [main] DEBUG org.apache.wsif.* - EXIT WSIFDynamicTypeMap.<init>()</nobr><br>
<nobr>9363 [main] DEBUG org.apache.wsif.* - ENTRY WSIFServiceImpl.<init><31e38a36>(C:\wsad-5\eclipse\workspace\xml-axis-wsif\java\samples\addressbook\wsifservice\AddressBook.wsdl, <null>, <null>, http://wsifservice.addressbook/, AddressBook)</nobr><br>
<nobr>9363 [main] DEBUG org.apache.wsif.* - ENTRY WSIFUtils.readWSDL(<null>, C:\wsad-5\eclipse\workspace\xml-axis-wsif\java\samples\addressbook\wsifservice\AddressBook.wsdl)</nobr><br>
<nobr>9373 [main] DEBUG org.apache.wsif.* - ENTRY WSIFPluggableProviders.getProvider(/)</nobr><br>
<nobr>9384 [main] DEBUG org.apache.wsif.* - ENTRY WSIFPluggableProviders.getSupportingProviders(/, true)</nobr><br>
<nobr>9384 [main] DEBUG org.apache.wsif.* - ENTRY WSIFPluggableProviders.getAllDynamicWSIFProviders()</nobr><br>
<nobr>9414 [main] DEBUG org.apache.wsif.* - ENTRY WSIFPluggableProviders.readMETAINFClassNames(file:/C:/wsad-5/eclipse/workspace/xml-axis-wsif/bin/META-INF/services/org.apache.wsif.spi.WSIFProvider)</nobr><br>
<nobr>9424 [main] DEBUG org.apache.wsif.* - EVENT WSIFPluggableProviders.readMETAINFClassNames Reading provider class names from URL: file:/C:/wsad-5/eclipse/workspace/xml-axis-wsif/bin/META-INF/services/org.apache.wsif.spi.WSIFProvider</nobr><br>
<nobr>9434 [main] DEBUG org.apache.wsif.* - EVENT WSIFPluggableProviders.readMETAINFClassNames Found provider class name: org.apache.wsif.providers.ejb.WSIFDynamicProvider_EJB</nobr><br>
<nobr>9444 [main] DEBUG org.apache.wsif.* - EVENT WSIFPluggableProviders.readMETAINFClassNames Found provider class name: org.apache.wsif.providers.java.WSIFDynamicProvider_Java</nobr><br>
</samp>
<p>The columns before
the ENTRY/EXIT are configurable in log4j.properties. In the sample above,
the [main] shows that all these trace statements were made from the main
thread. In a multithreaded application, the trace statements from all
threads are interleaved. After the ENTRY/EXIT is the WSIF classname.methodname
indented according to stack depth. The hex number in angle brackets (<>)
after the method name is the java object id, so it is possible to tell
which object this method was run against. Methods which do not have an
object id are static methods. After the object id are the parameters
passed or returned from that method. Null parameters are represented as
<null>. Some WSDL objects are represented as their fully qualified name
and their object id. For instance
definition({http://mynamespace}MyDefinition,1128e5e0). Some parameters
may get traced over multiple lines.
</p>
<p>Occasionally a method will be indented by two (or more) spaces than
the method that called it, according to the trace. This is demonstrated
in the sample trace above, by readMETAINFClassNames being indented by 5
more spaces than getAllDynamicProviders. This is because
getAllDynamicProviders calls other private methods which aren't traced,
which in turn call readMETAINFClassNames. So the indentation is a true
reflection of the WSIF stack depth, but not all private methods get traced.
</p>
<p>ENTRY trace statement represents a call to a method. An EXIT statement
represents the return from a method. An EVENT statement represents other
interesting information which may prove useful when diagnosing problems.
An EXCEPTION trace statement represents a java exception at the moment
that it is caught by WSIF. An ignored exception also represents a java
exception at the moment that it caught by WSIF. The difference between
an EXCEPTION and an ignored exception is that an EXCEPTION represents
an unexpected problem (in the application, the WSDL, in WSIF or elsewhere),
whereas an ignored exception represents an exception that was expected
to be thrown and caught routinely as part of WSIF mainline code and does
not represent a problem in itself. EXCEPTIONs are accompanied by their
stack trace.
</p>
<p>WSIF trace statements can be made from classes that are not part of WSIF.
Such trace statements have their classname prefixed with their fully
qualified package name. Commons-logging supports package-level tracing.
That enables trace to be switched on or off for individual packages. This
is not supported by WSIF. The only exception to this is tracing of WSIF
logging itself. Tracing org.apache.wsif.logging.* enables trace to trace
itself. This should be used with caution since traces produced this way
are huge and difficult to use to diagnose problems that aren't in trace
itself. A trace statement that contains "**** Exception in WSIF trace
statement *******" represents a trace statement that itself has a bug in
it. Such bad trace statements should not affect the normal operation of
WSIF, whether or not trace is on.
</p>
<hr width="100%">
</body></html>
1.1 xml-axis-wsif/java/doc/build.html
Index: build.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="Author" content="Aleksander Slominski">
<meta http-equiv="Content-Style-Type" content="text/css">
<title>Web Services Invocation Framework: How to Build</title>
<link rel="stylesheet" href="wsif.css" type="text/css"></head>
<body alink="#0000ff" bgcolor="#ffffff" leftmargin="2" topmargin="2" marginwidth="2" marginheight="2">
<h1>
Web Services Invocation Framework: How to Build</h1>
<h2>What are requirements?</h2>
<p>WSIF generally requires WSDL4J and XML parser that implements JAXP (such as
Xerces2). For detailed list of required and optional JAR files and how to obtain
them please take a look in lib/ subdirectories. Each subdirectory has short
README file that explains how to get needed JAR file if you do not have them
already on your CLASSPATH. Check detailed <a href="requirements.html">list of
requirements</a>.</p>
<h2>How to build?</h2>
<p>There are two possibilities: use your preferred verion of ANT but you are
responsible for setting CLASSPATH or use provided scripts that automate building
and CLASSPATH setting.</p>
<h2>Building WSIF using ANT</h2>
<p>Obtain all the necessary jar files as listed in the
<a href="requirements.html">prerequisites</a>. </p>
<p>Set required environment variables, including,
JAVA_HOME, ANT_HOME. </p>
<p>From the root directory of wsif (where build.xml is located), run </p>
<pre>ant -Dwsif.build.classpath=<classpath> <target></pre>
<p>where <classpath> contains the location of the preequisite JAR files<br>
<br>
and, where <target> is one of the following:
<ul>
<li><b>compile</b>: Compiles the API
</li><li><b>samples</b>: Compiles the samples
</li><li><b>javadocs</b>: Builds the javadoc
</li><li><b>srcdist</b>: Creates the source distribution
zip file.
</li><li><b>dist</b>: Creates the binary distribution zip
file.
</li><li><b>clean</b>: Removes built files.
</li><li><b>all</b>: Cleans, creates source and binary distribution
zip files.
</li><li><b>tests</b>: Build tests</li></ul>
<h2>Building WSIF by using provided scripts and JAR files</h2>
<p>If you downloaded the source distribution you need to make sure you have all <a href="requirements.html">prerequisite jars</a> available under their respective subdirectories within the lib directory; the README files in each subdirectory will point you to a location where you can download the jar.</p>
<p>If you downloaded the binary distribution, most of necessary jar files are already included in lib directory. You will
only need to download <b>activation.jar</b> and put it into <b>lib/activation</b>
(<a href="../lib/activation/README.txt">see README</a>), <b>mail.jar</b> and put
it into <b>lib/javamail</b> (<a href="../lib/javamail/README.txt">see
README</a>) and <b>optionally</b> j2ee.jar or other jar file with J2EE APIs (<a href="../lib/j2ee/README.txt">see
README</a>) to compile EJB and JCA providers (all of those files must be
downloaded separately as they can not be distributed).</p>
<p>Then use <b>build script</b> (./build.sh on UNIX or build.bat on Windows) to
rebuilt WSIF (see list of targets above).</p>
<p>After building, if you want just to run samples you can simply call <b>classpath script</b>
(on Windows use classpath.bat on UNIX use source classpath.csh if you use TCSH
or source classpath.sh if you use BASH) and you will have all required jar files
on CLASSPATH, then you can proceed with <a href="samples.html">running samples</a>.</p>
<hr width="100%">
<address>$Id: build.html,v 1.1 2003/01/14 14:19:08 owenb Exp $ </address>
</body></html>
1.1 xml-axis-wsif/java/doc/how_to_wsdl_extensions.html
Index: how_to_wsdl_extensions.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="Author" content="Nirmal Mukhi, Aleksander Slominski">
<meta http-equiv="Content-Style-Type" content="text/css">
<title>Web Services Invocation Framework: How To Write Provider</title>
<link rel="stylesheet" href="wsif.css" type="text/css"></head>
<body alink="#0000ff" bgcolor="#ffffff" leftmargin="2" topmargin="2" marginwidth="2" marginheight="2">
<h2>How to write your own WSDL extensions and plug them into WSDL4J</h2>
<p>To Implement new WSDL extension using WSDL4J it is necessary to:</p>
<ul>
<li>decide on what namespace will be used for WSDL extension: for example
EJB provider is using <a href="http://schemas.xmlsoap.org/wsdl/ejb/">http://schemas.xmlsoap.org/wsdl/ejb/</a></li>
<li>write a subclass of javax.wsdl.extensions.ExtensibilityElement</li>
<li>write class which implements ExtensionSerializer and ExtensionDeserializer
and is responsible for converting Java object representing extension to
XML (serializer) and for converting XML into Java object (deserialize)</li>
<li>write new extension registry - this clss must extend javax.wsdl.extensions.ExtensionRegistry
and is used to inform WSDL4J on how to handle new extension</li>
</ul>
<p>You can find examples of all these for the existing providers in the various org.apache.wsif.wsdl.extensions.* packages</p>
<p> </p>
<p>TODO: more details based on example</p>
<hr width="100%">
<p><font style='font-size: 8pt; font-family: sans-serif' size="-3">last modified $Id: how_to_wsdl_extensions.html,v 1.1 2003/01/14 14:19:08 owenb Exp $ </font></p>
</body></html>
1.1 xml-axis-wsif/java/doc/how_to_provider.html
Index: how_to_provider.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="Author" content="Aleksander Slominski, Nirmal Mukhi">
<meta http-equiv="Content-Style-Type" content="text/css">
<title>Web Services Invocation Framework: How To Write Provider</title>
<link rel="stylesheet" href="wsif.css" type="text/css"></head>
<body alink="#0000ff" bgcolor="#ffffff" leftmargin="2" topmargin="2" marginwidth="2" marginheight="2">
<h1>
Web Services Invocation Framework:<br>
How To Write Provider?</h1>
<h2>What is WSIF Provider?</h2>
<p>WSIF, as its name suggests is an open-ended framework for invoking WSDL described
services. As long as a WSDL description of the endpoint exists, it should be possible
to use this framework to invoke that piece of software, whatever it may be.</p>
<p>As has been described in <a href="http://www-106.ibm.com/developerworks/webservices/library/ws-appwsif.html?loc=dwmain">this introductory article</a>, the WSIF API is driven by
the abstract WSDL description of the service, and thus operates at a protocol-independent
level. When an invocation takes place at runtime, the invocation of the abstract operation
offered by the service needs to be converted into a protocol-specific mechanism for contacting
the service endpoint, conveying the input message or other required information to the service,
and receiving the response if any that results from the invocation. This result is eventually
returned to the application that uses the high-level, protocol-independent WSIF API.</p>
<p>The protocol-specific piece of software that enables the invocation to take place
is the WSIF provider. There is one WSIF provider for each kind of WSDL binding supported
by a particular installation of WSIF. For example, a particular installation may include the
WSIF core along with the SOAP and EJB providers only. This would allow clients using WSIF
at that site to invoke WSDL-described service that have SOAP or EJB bindings. Providers
are pluggable and can be added to the installation at runtime.</p>
<p>So far we understand that when the code using the WSIF API (let's call it the application,
even though this code might actually be WSIF's dynamic proxy which provides an additional
layer of abstraction for the real application) to invoke a service with a SOAP binding, the
invocation takes place through a WSIF provider that supports this binding. How is a provider
discovered? What happens if multiple providers support the same binding? (This is indeed
the case for SOAP, since WSIF includes a SOAP provider based on Axis and one based on Apache
SOAP). We will not address these issues in this document, here we will concentrate on
the provider architecture itself, without regard to how WSIF knows about their existence.</p>
<h2>Writing your own WSIF provider</h2>
<p>A pre-condition for a working provider is that there should be a well-defined
WSDL binding that it supports, along with the associated WSDL4J code that is capable
of parsing the binding. Note that WSDL4J, by default, supports only the standard WSDL 1.1
bindings: SOAP, HTTP and MIME. To add support for other providers in WSIF, one would first
need to define the WSDL binding extensions, define the corresponding WSDL4J extensibility
elements, and then register the serializers and deserializers for these extensibility
elements with the WSDL4J extension registry. Details on this are available
<a href="how_to_wsdl_extensions.htm">here</a>. The WSIF provider will use the WSDL4J
extensibility elements defined since these are the in memory representation of the
data in the binding.</p>
<h3>The <tt>WSIFProvider</tt> interface</h3>
<p>Let's discuss the specifics of a WSIF provider. A provider must implement the following
interface:<br>
<pre> /**
* For the given WSDL definition, service and port
* try to provide dynamic port,
* or return null if this provider can not do it.
* It is required to pass definition and service in addition to port
* as in current WSDL4J it is not possible to retrieve service to
* which port belongs and definition in which it was defined.
*/
public WSIFPort createDynamicWSIFPort(
Definition def,
Service service,
Port port,
WSIFDynamicTypeMap typeMap)
throws WSIFException;
/**
* Returns the WSDL namespace URIs of any bindings this provider supports.
* The assumption is made that the provider supports all combinations of
* binding and address namespaces returned by this and the
* getAddressNamespaceURIs method.
* @return an array of all binding namespaces supported by this provider
*/
public String[] getBindingNamespaceURIs();
/**
* Returns the WSDL namespace URIs of any port addresses this provider supports.
* The assumption is made that the provider supports all combinations of
* binding and address namespaces returned by this and the
* getBindingNamespaceURIs method.
* @return an array of all address namespaces supported by this provider
*/
public String[] getAddressNamespaceURIs();
</pre>
</p>
<p>OK, that's all you need to know. What, you mean the above wasn't self-explanatory?</p>
<p>So let's get into a little more detail. Let's start with the simpler methods:
<tt>getBindingNamespaceURIs()</tt> and <tt>getAddressNamespaceURIs()</tt>. Each binding
extension in WSDL is defined in a particular XML namespace. For example, the SOAP binding
is defined in the namespace <tt>http://schemas.xmlsoap.org/wsdl/soap/</tt>, and similarly,
so are the extensions under the <tt><port></tt> section of a WSDL document (often, as in
the case with the SOAP extensions, the namespace is the same as the one in which binding
extensions are defined). So, as the javadoc comments suggest, the WSIF runtime assumes that
the provider supports invocation of any service with a namespace URI for binding extensions
that is one of those returned by <tt>getBindingNamespaceURIs()</tt> and a namespace URI
for address extensibility elements that is one of those returned by
<tt>getAddressNamespaceURIs()</tt>.</p>
<p>The core of the provider is the method <tt>createDynamicWSIFPort(..)</tt>. This returns
a <tt>WSIFPort</tt> object that is constructed dynamically using:
<ul>
<li>the definition of the service we are invoking (the <tt>javax.wsdl.Definition</tt>
parameter)</li>
<li>the service we are invoking within that particular WSDL (the <tt>javax.wsdl.Service</tt>
parameter)</li>
<li>the port offered by the service that lets us know the specific service endpoint, the
binding and the port type that is being invoked (the <tt>javax.wsdl.Port</tt> parameter)</li>
<li>a type map that maps abstract schema types in the WSDL messages for the operations in the
port type being invoked to java types that correspond to them. WSIF will expect messages
provided at the time of invocation to have parts that are java objects of the required type,
as specified by the type map (it of course allows the object used for the invocation to be of
a less specific type as well).</li>
</ul>
</p>
<p>Let's consider how a specific provider implements this and other interfaces. We will
concentrate on identifying patterns that most provider implementations follow. Consider,
for example, the Apache SOAP provider.
<a href="../src/org/apache/wsif/providers/soap/apacheaxis/WSIFDynamicProvider_ApacheAxis.java">
Here</a> is the source code for this implementation of the <tt>WSIFProvider</tt> interface.
It is fairly straightforward. The constructor usually does very little, in most cases nothing.
In this particular case it has a mechanism to set up the binding and address namespace URIs
supported by this provider. It also adds to the WSDL4J extension registry used by WSIF the
capability to parse JMS extensions. The capability to parse SOAP, EJB and java extensions are
pre-registered, all other binding extensions may be registered in this fashion. The
<tt>createDynamicWSIFPort</tt> method in the Apache Axis provider parses the binding associated
with the port being invoked and verifies that it is indeed a SOAP binding. If this is the case,
it creates a <tt>WSIFPort_ApacheAxis</tt> object, which implements the <tt>WSIFPort</tt>
interface.</p>
<h3>The <tt>WSIFPort</tt> interface</h3>
<p>The main function of the WSIF port that is to create a <tt>WSIFOperation</tt> object at
runtime when a WSDL operation needs to be invoked. At the minimum, the <tt>WSIFPort</tt> needs
to know the name of the operation. If there is a possibility of overloaded operations, the
application may invoke the form that takes the names of the input and output messages in
addition to the name of the operation. <tt>WSIFOperation</tt> objects are the brains of the
outfit; they actually perform the invocation based on a specific protocol. But more on that
later, first let's see how the Axis provider implements the <tt>WSIFPort</tt> interface. The
<a href="../src/org/apache/wsif/providers/soap/apacheaxis/WSIFPort_ApacheAxis.java">
implementation</a> in the constructor itself parses the binding being invoked, doing some
processing based on the transport being used (since WSIF's Axis provider supports SOAP messages
over HTTP or JMS). In addition, it also verifies that the binding is indeed supported (for
example WSIF does not support SOAP bindings that use document style instead of RPC style
invocations <em>using the Axis provider</em> (document style is supported when using the Apache
SOAP provider to handle SOAP bindings). Finally, the Axis implementation of the port actually
iterates through the binding, creating a <tt>WSIFOperation_ApacheAxis</tt> object (the
protocol-specific implementation of the <tt>WSIFOperation</tt> interface) for each operation
in the binding. These <tt>WSIFOperation</tt> objects are cached so that they don't have to be
created each time. Of course that is optional, a bare-bones version of a provider could do very
little in the constructor. The most useful method implemented here is <tt>createOperation</tt>,
which creates the appropriate <tt>WSIFOperation_ApacheAxis</tt> object (based on the operation
name and input and output names, if provided, to resolve the exact operation the application
wants to invoke). The method first looks up the cache containing previously created instances
and may reuse them or may create a new one.</p>
<h3>The <tt>WSIFOperation</tt> interface</h3>
<p>The real brains of the outfit is the <tt>WSIFOperation</tt> object. This interface has a
number of useful methods, so let's do it in some detail:<br>
<pre><tt>
/**
* A WSIFOperation is a handle on a particular operation of a portType
* that can be used to invoke web service methods. This interface is
* implemented by each provider. A WSIFOperation can be created using
* {@link WSIFPort#createOperation(String)}.
*
* @author Owen Burroughs <ow...@apache.org>
* @author Ant Elder <an...@apache.org>
* @author Jeremy Hughes <hu...@apache.org>
* @author Mark Whitlock <wh...@apache.org>
*/
public interface WSIFOperation extends Serializable {
/**
* Execute a request-response operation. The signature allows for
* input, output and fault messages. WSDL in fact allows one to
* describe the set of possible faults an operation may result
* in, however, only one fault can occur at any one time.
*
* @param op name of operation to execute
* @param input input message to send to the operation
* @param output an empty message which will be filled in if
* the operation invocation succeeds. If it does not
* succeed, the contents of this message are undefined.
* (This is a return value of this method.)
* @param fault an empty message which will be filled in if
* the operation invocation fails. If it succeeds, the
* contents of this message are undefined. (This is a
* return value of this method.)
*
* @return true or false indicating whether a fault message was
* generated or not. The truth value indicates whether
* the output or fault message has useful information.
*
* @exception WSIFException if something goes wrong.
*/
public boolean executeRequestResponseOperation(
WSIFMessage input,
WSIFMessage output,
WSIFMessage fault)
throws WSIFException;
/**
* Execute an asynchronous request
* @param input input message to send to the operation
*
* @return the correlation ID or the request. The correlation ID
* is used to associate the request with the WSIFOperation.
*
* @exception WSIFException if something goes wrong.
*/
public WSIFCorrelationId executeRequestResponseAsync(WSIFMessage input)
throws WSIFException;
/**
* Execute an asynchronous request
* @param input input message to send to the operation
* @param handler the response handler that will be notified
* when the asynchronous response becomes available.
*
* @return the correlation ID or the request. The correlation ID
* is used to associate the request with the WSIFOperation.
*
* @exception WSIFException if something goes wrong.
*/
public WSIFCorrelationId executeRequestResponseAsync(
WSIFMessage input,
WSIFResponseHandler handler)
throws WSIFException;
/**
* fireAsyncResponse is called when a response has been received
* for a previous executeRequestResponseAsync call.
* @param response an Object representing the response
* @exception WSIFException if something goes wrong
*/
public void fireAsyncResponse(Object response) throws WSIFException;
/**
* Processes the response to an asynchronous request.
* This is called for when the asynchronous operation was
* initiated without a WSIFResponseHandler, that is, by calling
* the executeRequestResponseAsync(WSIFMessage input) method.
*
* @param response an Object representing the response.
* @param output an empty message which will be filled in if
* the operation invocation succeeds. If it does not
* succeed, the contents of this message are undefined.
* (This is a return value of this method.)
* @param fault an empty message which will be filled in if
* the operation invocation fails. If it succeeds, the
* contents of this message are undefined. (This is a
* return value of this method.)
*
* @return true or false indicating whether a fault message was
* generated or not. The truth value indicates whether
* the output or fault message has useful information.
*
* @exception WSIFException if something goes wrong
*
*/
public boolean processAsyncResponse(
Object response,
WSIFMessage output,
WSIFMessage fault)
throws WSIFException;
/**
* Execute an input-only operation.
*
* @param input input message to send to the operation
* @exception WSIFException if something goes wrong.
*/
public void executeInputOnlyOperation(WSIFMessage input) throws WSIFException;
/**
* Allows the application programmer or stub to pass context
* information to the binding. The Port implementation may use
* this context - for example to update a SOAP header. There is
* no definition of how a Port may utilize the context.
* @param context context information
*/
public void setContext(WSIFMessage context);
/**
* Gets the context information for this binding.
* @return context
*/
public WSIFMessage getContext();
/**
* Create an input message that will be sent via this port.
* It is responsibility of caller to set message name.
* @return a new message
*/
public WSIFMessage createInputMessage();
/**
* Create an input message that will be sent via this port.
* @param name for the new message
* @return a new message
*/
public WSIFMessage createInputMessage(String name);
/**
* Create an output message that will be received into via this port.
* It is responsibility of caller to set message name.
* @return a new message
*/
public WSIFMessage createOutputMessage();
/**
* Create an output message that will be received into via this port.
*
* @param name for the new message
* @return a new message
*/
public WSIFMessage createOutputMessage(String name);
/**
* Create a fault message that may be received into via this port.
* It is responsibility of caller to set message name.
* @return a new message
*/
public WSIFMessage createFaultMessage();
/**
* Create a fault message that may be received into via this port.
*
* @param name for the new message
* @return a new message
*/
public WSIFMessage createFaultMessage(String name);
}
</tt></pre>
</p>
<p>Most of the above is self-explanatory. The important things to note is that the
invocation is achieved through this object. It also is capable of creating the messages
(input, output, fault) that are associated with any invocation; such messages can be
populated with data and then provided to methods such as
<tt>executeRequestResponseOperation</tt>. Note also that as operations are designed
right now, instances may not be reused since they often carry state that interferes
with subsequent invocations using the same object. To prevent such misuse, the default
implementation of the interface (which is extended by other implementations including
<tt>WSIFOperation_ApacheAxis</tt>) has a <tt>close</tt> method which must be invoked at
the end of an invocation and sets a flag preventing further use. Applications may create a
new operation instance using the <tt>WSIFPort</tt>. At some point we expect to modify
the way operation instances are handled to allow reuse except in specific cases, hopefully
simplifying the provider contract and improving performance.</p>
<p>The Axis provider implementation of this interface is
<a href="../src/org/apache/wsif/providers/soap/apacheaxis/WSIFOperation_ApacheAxis.java">
here</a>. Everything the class does boils down to the use of the
<tt>invokeRequestResponseOperation</tt> method. We won't get into detail, but this uses
a protocol-specific library (in this case JAX-RPC, which is the client programming model
supported by Axis) to invoke the service. Note how the provider code handles the type map that
was provided at the time of creating the <tt>WSIFPort</tt> for invoking this service.
For Axis, we need to register serializers and deserializers to marshall and unmarshall java
objects into SOAP messages. This must be done prior to an invocation for it to work. Other
providers may have to take similar steps to make sure they are capable of handling the
java-typed data that populate the input and output messages used for invocation.</p>
<p>So far we have not touched on <tt>WSIFMessage</tt> objects which are ubiquitous in the
provider code. It's enough to think of a <tt>WSIFMessage</tt> as a map of WSDL message
part names to java objects representing the value of that particular part. The type of the
java object must match the expected type according to the type mapping supplied to the
WSIF provider. WSIF also allows for creation of messages using primitive java types. The
WSIF message interface is available <a href="../src/org/apache/wsif/WSIFMessage.java">here</a>.
</p>
<h3>That's it!</h3>
<p>The protocol-specific implementation of the <tt>WSIFProvider</tt> interface, the
<tt>WSIFPort</tt> interface and the <tt>WSIFOperation</tt>interface are all that are generally
required to implement a WSIF provider. Supporting classes may also be included - for example
the SOAP providers (both, Apache SOAP and Apache Axis providers) have utility classes to
handle message exchanges using the JMS transport.</p>
<h2>Open Issues</h2>
<h3>performance and stateful operations (for example in JCA connectors)</h3>
<p>from Paul Fremantle email
<pre>How about explicitly identifying which providers require stateful operations
and which dont. Those that dont could reuse operations from a cache, ignore
closes etc. I'm not sure this will help us either. At the moment our HTTP
support is not efficient because we don't reuse HTTP connections. If we
updated it to be much more closely bound to the real HTTP interactions then
maybe close() might be useful?? I havent really thought this through, but I
know that close() was designed to allow long running connections.
</pre>
</p>
<hr width="100%">
<p><font style='font-size: 8pt; font-family: sans-serif' size="-3">last modified $Id: how_to_provider.html,v 1.1 2003/01/14 14:19:08 owenb Exp $ </font></p>
</body></html>
1.1 xml-axis-wsif/java/doc/mime_attachments.html
Index: mime_attachments.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="Author" content="Mark Whitlock">
<meta http-equiv="Content-Style-Type" content="text/css">
<title>Soap Attachments</title>
<link rel="stylesheet" href="wsif.css" type="text/css"></head>
<body alink="#0000ff" bgcolor="#ffffff" leftmargin="2" topmargin="2" marginwidth="2" marginheight="2">
<h1>
Soap Attachments using WSIF</h1>
<h2>Overview</h2>
<p>
WSIF supports passing attachments in a Mime message using the Axis
provider. The attachment is a javax.activation.DataHandler, The mime:multipartRelated,
mime:part and mime:content tags are used to describe the attachment
in the WSDL.</p>
<p>
The WSDL extensions...<br>
<code>
<binding name="MyBinding" type="tns:abc" ><br>
<soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/><br>
<operation name="MyOperation"><br>
<soap:operation soapAction=""/><br>
<input><br>
<mime:multipartRelated><br>
<mime:part><br>
<soap:body use="encoded" namespace="http://mynamespace"<br>
encodingStyle="http://schemas.xmlsoap.org/soap/encoding"/><br>
</mime:part><br>
<mime:part><br>
<mime:content part="attch" type="text/html"/><br>
</mime:part><br>
</mime:multipartRelated><br>
</input><br>
</operation><br>
</binding><br>
</code></p>
<p>The above WSDL demonstrates a simple operation that has one
attachment called <I>attch</I>. There must be a part called <I>attch</I> on
the input message for MyOperation. There may be other input parts
to MyOperation that are not attachments. In the binding input there
must either be a <soap:body or a <mime:multipartRelated, but not
both. For mime messages, the soap:body is inside a mime:part. There
must only be one mime:part that contains a soap:body in the binding
input and that must not contain a mime:content as well, since a
content type of text/xml is assumed for the soap:body. There can
be multiple attachments in a mime message, each described by a
mime:part. Each mime:part (that isn't a soap:body) contains a
mime:content that describes the attachment itself. The type field
inside the mime:content is not checked or used by WSIF. Instead it
is there to provide a hint to the application using WSIF as to what
the attachment is intended to contain. Multiple mime:contents inside
a single mime:part means that the backend service will expect a single
attachment with a type specified by one of the mime:contents inside
that mime:part. The parts="..." tag (optional) inside the soap:body
is assumed to contain the names of all the mime parts as well as the
names of all the soap parts in the message.
</p>
<h2>Passing attachments to WSIF</h2>
<p>The following code snippet could invoke the service described by the WSDL above...</p>
<code>
import javax.activation.DataHandler;<br>
. . .<br>
DataHandler dh = new DataHandler(new FileDataSource("axis.jpg"));<br>
WSIFServiceFactory factory = WSIFServiceFactory.newInstance();<br>
WSIFService service = factory.getService("my.wsdl",null,null,"http://mynamespace","abc");<br>
WSIFOperation op = service.getPort().createOperation("MyOperation");<br>
WSIFMessage in = op.createInputMessage();<br>
in.setObjectPart("attch",dh);<br>
op.executeInputOnlyOperation(in);<br>
</code>
<p>I use tomcat with soap 2.3 as my soap server so my
DeploymentDescriptor.xml contains the following type mapping..</p>
<code>
<isd:mappings><br>
<isd:map encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"<br>
xmlns:x="http://mynamespace"<br>
qname="x:datahandler"<br>
javaType="javax.activation.DataHandler"<br>
java2XMLClassName="org.apache.soap.encoding.soapenc.MimePartSerializer"<br>
xml2JavaClassName="org.apache.soap.encoding.soapenc.MimePartSerializer" /><br>
</isd:mappings>
</code>
<p>and my backend service gets invoked with the following signature ...</p>
<code>
public void MyOperation(DataHandler dh);
</code>
<p>Attachments can also be passed in to WSIF using stubs...</p>
<code>
DataHandler dh = new DataHandler(new FileDataSource("axis.jpg"));<br>
WSIFServiceFactory factory = WSIFServiceFactory.newInstance();<br>
WSIFService service = factory.getService("my.wsdl",null,null,"http://mynamespace","abc");<br>
MyInterface stub = (MyInterface)service.getStub(MyInterface.class);<br>
stub.MyOperation(dh);<br>
</code>
<p>Attachments can also be returned from an operation, but at present
only one attachment can be returned as the return parameter.
</p>
<h2>Types and type mappings</h2>
<p>
By default, attachments are passed into WSIF as DataHandlers. If
the part on the message which is the DataHandler maps to a mime:part
in the WSDL, then WSIF will automatically map the fully qualified
name of the WSDL type to DataHandler.class and set up that type mapping
with Axis. </p>
<p>In your WSDL you may have defined a schema for the attachment as a binary[]
for instance. Whether or not you have done this, WSIF silently ignores this
mapping and treats the attachment as a DataHandler, unless you have
explicitly issued mapType(). WSIF lets axis set the mime content type based
on the DataHandler's type, instead of the mime:content type specified in the WSDL.
</p>
<h2>Some restrictions.</h2>
<p> These are not supported...
<ul>
<li>Attachments using the Apache Soap provider</li>
<li>Mime/Axis/Jms</li>
<li>DIME</li>
<li>Passing in axis AttachmentParts</li>
<li>Passing in javax.xml.transform.Source and javax.mail.internet.MimeMultipart</li>
<li>The mime:mimeXml WSDL tag</li>
<li>Attachments over doc-style</li>
<li>Nesting a mime:multipartRelated inside a mime:part</li>
<li>Types that extend DataHandler, Image, etc</li>
<li>Types that contain DataHandler, Image, etc</li>
<li>Arrays or Vectors of DataHandlers, Images, etc</li>
<li>Multiple inout or output attachments</li>
</ul>
</p>
<hr width="100%">
</body></html>
1.1 xml-axis-wsif/java/doc/wsdl_extensions/j2c_extensions/wsif_j2c_extensions.html
Index: wsif_j2c_extensions.html
===================================================================
<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/jms_bindings.html
Index: jms_bindings.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="Author" content="Mark Whitlock">
<meta http-equiv="Content-Style-Type" content="text/css">
<title>JMS Bindings</title>
<link rel="stylesheet" href="wsif.css" type="text/css"></head>
<body alink="#0000ff" bgcolor="#ffffff" leftmargin="2" topmargin="2" marginwidth="2" marginheight="2">
<h1>WSDL Bindings for Jms</h1>
<h2>Overview</h2>
<p>
WSIF defines extra WSDL extensions that are not part of WSDL4J itself. Amongst
others, these WSDL extensions are needed for JMS. You should use WSIF to read
in your WSDL, rather than using WSDL4J directly, because WSIF adds in its
own extension registries that understand these extra WSDL extensions. For example
you can use WSIFUtils.readWSDL to do this. This page describes WSIF's WSDL
extensions for JMS. Currently, these WSDL extensions are valid for Soap over Jms,
Axis over Jms and NativeJms. The jms namespace must be
<code>
xmlns:jms="http://schemas.xmlsoap.org/wsdl/jms/"
</code>
</p>
<h2>Jms address</h2>
<p>
<jms:address describes a target port that is accessible via JMS.
</p>
<p><code>
<jms:address jmsVendorURI="xxx"<br>
jndiDestinationName="xxx"<br>
destinationStyle="xxx"<br>
jndiConnectionFactoryName="xxx"<br>
initialContextFactory="xxx"<br>
jndiProviderURL="xxx"<br>
jmsProviderDestinationName="xxx"<br>
jmsImplementationSpecificURI="xxx" />
</code>
<p>
<ul>
<li>this must go in the port</li>
<li>jmsVendorURI is optional and unused by WSIF. It allows to the client
to check the JMS implementation.</li>
<li>either destinationStyle or jmsImplementationSpecificURI must be
specified, but not both.</li>
<li>jmsImplementationSpecificURI specifies the queue manager and queues
in a implementation specific format. This is currently unimplemented by WSIF.</li>
<li>destinationStyle must either be queue or topic, but topics aren't yet
implemented by WSIF.</li>
<li>if destinationStyle is specified, then either jndiDestinationName or
jmsProviderDestinationName must be specified but not both.</li>
<li>jndiDestinationName is the JNDI name of the JMS queue that WSIF will
send requests to.</li>
<li>jmsProviderDestinationName is the JMS name of the JMS queue that WSIF
will send requests to.</li>
<li>if jndiDestinationName is specified then jndiConnectionFactoryName must
also be specified.</li>
<li>if jmsProviderDestinationName is specified then jndiConnectionFactoryName may
also be specified. jndiConnectionFactoryName would be needed if the JNDI name
of a replyTo queue is passed to WSIF.</li>
<li>jndiConnectionFactoryName is the JNDI name of the connection factory
that WSIF will use.</li>
<li>if destinationStyle is specified then either both jndiProviderURL and
initialContextFactory or neither must be specified.</li>
</ul></p>
<p>
WSIF uses the following order to lookup queues and queue managers in JNDI
<ul>
<li>Lookup java:comp/env/<name> in the default (local) JNDI</li>
<li>Lookup java:comp/env/<name> in the JNDI specified by the WSDL</li>
<li>Lookup <name> in the default (local) JNDI</li>
<li>Lookup <name> in the JNDI specified by the WSDL.</li>
</ul></p>
<p>
This allows a client administrator to override the JNDI definition specified
in the WSDL.
</p>
<h2>Jms binding</h2>
<p>
TODO
</p>
<h2>Jms property</h2>
<p><code>
<jms:property name="<name>" part="<part>" />
</code></p>
<p><ul>
<li>this must go in the input or output section of the binding operation.
Output jms properties are not yet implemented in WSIF.</li>
<li>the <name> may be the name of a property defined by JMS, or
the name of a property defined by the JMS implementation, or the name of
a user property.</li>
<li>the <part> must be the name of a part in the message.</li>
<li>JMS user properties that are objects are not implemented by WSIF.</li>
<li>When using stubs to invoke WSIF, this property appears as a parameter
on the stub's signature, but will not appear on the web service's
method signature.</li>
</ul></p>
<h2>Jms property value</h2>
<p><code>
<jms:propertyValue name="<name>" type="<type>"
value="<value>" />
</code></p>
<p><ul>
<li>this must go in either the <jms:address or in the input section
of the binding operation.</li>
<li>the <name> may be the name of a property defined by JMS, or
the name of a property defined by the JMS implementation, or the name of
a user property.</li>
<li>the <type> is the datatype of the <value> that hardcodes
the value of this property in the WSDL.</li>
<li>JMS user properties that are objects are not implemented by WSIF.</li>
</ul></p>
<p>
JMS properties can also be set on the message context, without being
defined in the WSDL.
</p>
<h2>Jms fault, fault property and fault indicator</h2>
<p>
TODO
</p>
<hr width="100%">
</body></html>
1.1 xml-axis-wsif/java/readme.html
Index: readme.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="Author" content="Ant Elder">
<meta http-equiv="Content-Style-Type" content="text/css"><title>Web Services Invocation Framework for Java API - Overview</title>
<link rel="stylesheet" href="doc/wsif.css" type="text/css"></head>
<body alink="#0000ff" bgcolor="#ffffff" leftmargin="2" topmargin="2" marginwidth="2" marginheight="2">
<h1><a name="WSIF Overview">WSIF: <br>
Web Services Invocation Framework</a></h1>
The Web Services Invocation Framework (WSIF) is a simple Java API for invoking Web services,
no matter how or where the services are provided.<BR>
<p>WSIF enables developers to interact with abstract representations
of Web services through their WSDL descriptions instead of working
directly with the Simple Object Access Protocol (SOAP) APIs, which is
the usual programming model. With WSIF, developers can work with the
same programming model regardless of how the Web service is
implemented and accessed.</p>
<p>WSIF allows stubless or completely dynamic invocation of a Web service, based
upon examination of the meta-data about the service at runtime. It also allows
updated implementations of a binding to be plugged into WSIF at runtime, and it
allows the calling service to defer choosing a binding until runtime.</p>
<p>Finally, WSIF is closely based upon WSDL, so it can invoke any service
that can be described in WSDL.</p>
<h2>Why should I use WSIF?</h2> <p>What does all this enable?
Imagine your complicated Enterprise software system consisting of
various pieces of software, developed over a period of tens of years -
EJBs, legacy apps accessed using Java's connector architecture, SOAP
services hosted on external servers, old code accessed through
messaging middleware. You need to write software applications that use
all these pieces to do useful things; yet the differences in
protocols, mobility of software, etc. comes in the way.</p>
<p>The software you use moves to a different server, so your code
breaks. The SOAP libraries you use change - say for example you moved
from using Apache SOAP to Apache Axis - so your code breaks since it
uses a now deprecated SOAP API. Something that was previously
accessible as an EJB is now available through messaging middleware via
JMS - again, you need to fix the code that uses the software. Or lets
suppose you have an EJB which is offered as a SOAP service to external
clients. Using SOAP obviously results in a performance penalty as
compared to accessing the EJB directly. Of course, SOAP is a great
baseline protocol for platform and language independence, but shouldn't
java clients be able to take advantage of the fact that the software
they are accessing is really an EJB? So your java customers pay a
performance penalty since you have to use SOAP for to accommodate you
non-java clients.</p>
<p>WSIF fixes these problems by letting you use WSDL as a
<em>normalized description</em> of disparate software, and allows you
to access this software in a manner that is independent of protocol or
location. So whether it is SOAP, an EJB, JMS (or potentially .NET and
other software frameworks), you have an API centered around WSDL which
you use to access the functionality. This lets you write code that
adapts to changes easily. The separation of the API from the actual
protocol also means you have flexibility - you can switch protocols,
location, etc. without having to even recompile your client code. So
if your an externally available SOAP service becomes available as an
EJB, you can switch to using RMI/IIOP by just changing the service
description (the WSDL), without having to make any modification in
applications that use the service. You can exploit WSDL's
extensibility, its capability to offer multiple bindings for the same
service, deciding on a binding at runtime, etc.</p>
<BR>You will find more details about WSIF and its architecture in the
<a href="doc/overview.html">overview</a>.
<a name="ContributingToIt"></a><h2>How can I contribute to WSIF?</h2>
<p>You can contribute to WSIF by participating in discussions on the
<a href="doc/mail.html">axis-user and axis-dev
mailing lists</a>. Be sure to prefix the subject of your WSIF-related
emails with <b> <tt>[wsif]</tt></b>. If you find something that outstanding
issue or bug that interests you, feel free to download WSIF's source
code and work on it. You will find instructions for accessing the
source code <a href="doc/cvs.html">here</a>.</p> <p>You can find a
list of outstanding bugs from <a href="doc/bugs.html">Bugzilla</a>.</p>
<h2>More information</h2>
<br><b>Basics</b>
<li> <a href="doc/overview.html">Overview</a>
<li> <a href="doc/news.html">News</a>
<li> <a href="doc/faq.htm">FAQ</a>
<li> <a href="doc/quick-start.html">A Quick Start to using WSIF</a>
<li> <a href="doc/user-guide.html">User's Guide</a>
<li> <a href="doc/developers-guide.html">Developer's Guide</a>
<li> <a href="doc/mail.html">Mailing Lists</a>
<li> <a href="doc/bugs.html">Bugs</a>
<li> <a href="doc/references.html">References</a>
<br>
<br><b>Downloads</b>
<li> <a href="http://cvs.apache.org/dist/axis/wsif/">Releases</a>
<br>
<br><b>Related Projects</b>
<li> <a href="http://xml.apache.org/axis">Axis</a>
<li> <a href="http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-axis-wsil/java/README.htm">WSIL</a>
<li> <a href="http://www-124.ibm.com/developerworks/projects/wsdl4j/">WSDL4J</a>
<br>
<br><b>Misc</b>
<li> <a href="../LICENSE">Legal</a>
<br>
<hr width="100%">
</body></html>