nmukhi 2002/12/16 10:29:05
Modified: java/doc tests.htm
Added: java/doc developers-guide.html mail.html news.html
overview.html quick-start.html references.html
user-guide.html
java/doc/wsdl_extensions jms_bindings.htm
Removed: java/doc jms_bindings.htm
Log:
Misc doc changes: restructuring for new WSIF home page
Revision Changes Path
1.2 +2 -1 xml-axis-wsif/java/doc/tests.htm
Index: tests.htm
===================================================================
RCS file: /home/cvs/xml-axis-wsif/java/doc/tests.htm,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- tests.htm 25 Nov 2002 06:32:56 -0000 1.1
+++ tests.htm 16 Dec 2002 18:29:05 -0000 1.2
@@ -10,6 +10,7 @@
<h1>
Web Services Invocation Framework: Unit Tests</h1>
+<p>See <a href="run.htm">the Tests document</a> for a guide to the tests and how to
run them.</p>
<h2>How to build tests?</h2>
1.1 xml-axis-wsif/java/doc/developers-guide.html
Index: developers-guide.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: Developer's Guide</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: Developer's Guide</h1>
<hr>
<ul>
<li><a href="cvs.html">Accessing source code</a></li>
<li><a href="build.htm">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="bugs.html">Reporting Bugs</a></li>
<li><a href="mail.html">Mailing lists</a></li>
</ul>
<hr width="100%">
</body></html>
1.1 xml-axis-wsif/java/doc/mail.html
Index: mail.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">
<meta http-equiv="Content-Style-Type" content="text/css">
<title>Web Services Invocation Framework: Mailing lists</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>Mailing lists</h2>
<p>WSIF uses the <a href="http://xml.apache.org/axis/mail.html";>Axis mailing
lists</a>. So you can post to <tt>axis-dev</tt> or <tt>axis-user</tt>, following the
prescribed <a href="http://xml.apache.org/axis/mailguide.html";>guidelines</a>. Please
also prefix the subject of each of your emails with <tt>[WSIF]</tt> so it is easy to
identify WSIF-related posts on the Axis lists.</p>
<hr width="100%">
</body></html>
1.1 xml-axis-wsif/java/doc/news.html
Index: news.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: News</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">
<H2>What is new with WSIF?</H2>
<p>WSIF has it's own home at <a
href="http://xml.apache.org/axis/wsif";>http://xml.apache.org/axis/wsif</a>.</p>
<p>The first Apache WSIF release candidate is currently being worked on and
should be available in the near future. Check back here and watch the
<A href="http://xml.apache.org/axis/mail.html";>mailing lists</A> for news.</p>
<p>You can download interim releases from <a
href="http://cvs.apache.org/dist/axis/wsif/";>http://cvs.apache.org/dist/axis/wsif/</a>.
</p>
<hr>
</body></html>
1.1 xml-axis-wsif/java/doc/overview.html
Index: overview.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">
Web Services Invocation Framework: Overview</a></h1>
<p>WSIF stands for the Web Services Invocation Framework. It supports a simple
Java
API for invoking Web services, no matter how or where the
services are provided. The framework allows maximum
flexibility for the invocation of any WSDL-described service.</p>
<p>In the WSDL specification, Web service binding descriptions are
<em>extensions</em> to the specification. So the SOAP binding,
for example, is one way to expose the abstract functionality
(<em>and there could be others</em>). Since WSIF mirrors WSDL
very closely, it also views SOAP as just one of several ways you
might wish to expose your software's functionality. WSDL thus
becomes a normalized description of software, and WSIF is the
natural client programming model.</p>
<p>The WSIF API allows clients to invoke services focusing on the
abstract service description - the
portion of WSDL that covers the port types, operations and
message exchanges without referring to real protocols. The
<em>abstract invocations</em> work because they are backed up by
protocol-specific pieces of code called <em>providers</em>. A
provider is what conducts the actual message exchanges according
to the specifics of a particular protocol - for example, the
SOAP provider that is packaged with WSIF uses a specific SOAP
engine like Axis to do the real work.</p>
<p>The decoupling of the abstract invocation from the real
provider that does the work results in a flexible programming
model that allows dynamic invocation, late binding, clients
being unaware of large scale changes to services - such as
service migration, change of protocols, etc. WSIF also allows
new providers to be registered dynamically, so you could enhance
your client's capability without ever having to recompile its
code or redeploy it.</p>
<p>Using WSIF, WSDL can become the centerpiece of an integration
framework for accessing software running on diverse platforms and
using widely varying protocols. The only precondition is that you
need to describe your software using WSDL, and include in its
description a binding that your client's WSIF framework has a
provider for. WSIF defines and comes packaged with providers for
local java, EJB, JMS, and JCA protocols. That means you can define
an EJB or a JMS-accessible service directly as a WSDL binding and
access it transparently using WSIF, using the same API you would
for a SOAP service or even a local java class.</p>
<p>TODO: Put a picture showing WSIF client with pluggable providers to
access service using different protocols.</p>
<H3>WSIF Structure</H3>
In WSDL a binding defines how to map between the abstract PortType and a
real service format and protocol. For example, the SOAP binding defines
the encoding style, the SOAPAction header, the namespace of the body
(the targetURI), and so forth.<BR>
<BR>
WSDL allows there to be multiple implementations for a Web Service,
and multiple Ports that share the same PortType. In other words, WSDL
allows the same interface to have bindings to for example, SOAP and
IIOP.<BR>
<BR>WSIF provides an API to allow the same client code to access any
available binding. As the client code can then be written to the PortType
it can be a deployment or configuration setting (or a code choice)
which port and binding it uses.<BR>
<BR>
WSIF uses 'providers' to support these multiple WSDL bindings. A provider
is a piece of code that supports a WSDL extension and allows invocation of
the service through that particular implementation. WSIF providers use the
J2SE JAR service provider specification making them discoverable at runtime.<BR>
<BR>Clients can then utilize any new implementations and can delegate the
choice of port to the infrastructure and runtime, which allows the
implementation to be chosen on the basis of quality of service
characteristics or business policy.
<h3>WSDL bindings for EJBs, JMs, JCA...</h3>
<p>WSIF defines additional 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_extensions.htm">Local java binding
extensions for WSDL</a></li>
<li><a href="wsdl_extensions/ejb_extensions.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>
</ul>
</p>
<hr width="100%">
<address>$Id: overview.html,v 1.1 2002/12/16 18:29:05 nmukhi Exp $ </address>
</body></html>
1.1 xml-axis-wsif/java/doc/quick-start.html
Index: quick-start.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: Quick Start</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">
<h2>Web Services Invocation Framework: Quick Start</h2>
<p><b>Preliminaries</b>: Download the WSIF distribution from <a
href="http://cvs.apache.org/dist/axis/wsif/";>
http://cvs.apache.org/dist/axis/wsif/</a>. It comes in three flavors: the binary
distribution ("bin"), the source-only distribution ("src%quot;) or
everything
included ("all"). If you are familiar with CVS and
want to work with the latest code <a href="doc/cvs.html">use cvs</a>. Using CVS
you can also retrieve any past release by using tag (for example
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="doc/faq.htm">WSIF FAQ</a>. Then read about <a
href="doc/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="doc/requirements.html">check that all
prerequisites</a> are available. Then <a href="doc/build.htm">proceed with
building</a>.</p>
<p>After you have successfully downloaded and installed WSIF, you
can test your installation by <a href="doc/samples.html">running the
samples</a>. If you are able to run all the samples
successfully you should have a very good idea of what you can do
with WSIF. Essentially once you have a WSDL file with a binding
that WSIF understands (such as SOAP, EJB, Java, JMS, JCA, etc.)
you can write a client that uses WSIF's APIs - the dynamic
invocation API or the stub-based invocation - to use this
service.</p>
<p>Traditionally, the burden of dealing with new protocols has
been a carried by the server-side. Software has to morph itself
(through the addition of wrappers) to look like something the
client expects to see. With WSIF, the software remains exactly
the same - we just get the client to use WSIF's binding
independent API, and through the addition of providers, we can
mix and match protocols as we please.</p>
<p><em>Service</em> is a very liberal term for WSIF!
Anything that can be described in WSDL qualifies as a service
and is something you can access using the WSIF API. Moreover,
since WSDL is extensible, potentially everything can be
described using WSDL. The next section describes how you can
define your own bindings and write your own WSIF providers.</p>
<hr>
</body></html>
1.1 xml-axis-wsif/java/doc/references.html
Index: references.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, Aleksander Slominski, Nirmal Mukhi">
<meta http-equiv="Content-Style-Type" content="text/css">
<title>Web Services Invocation Framework: References</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">
<h2>Web Services Invocation Framework: References</h2>
<ul>
<li><a href="http://www.research.ibm.com/people/b/bth/OOWS2001/duftler.pdf";>WSIF
Framework proposal</a>
</li><LI><A href="http://www.alphaworks.ibm.com/tech/wsif";>IBM's original
alphaWorks WSIF site</A></LI>
<LI>The W3C <A href="http://www.w3.org/TR/wsdl";>Web Services Description
Language (WSDL) specification</A>,
<A href="http://www.jcp.org/jsr/detail/110.jsp";>JSR110</A> describing the
Java APIs for WSDL, and the
<A
href="http://oss.software.ibm.com/developerworks/projects/wsdl4j";>WSDL4J</A> open
source site.</LI>
<LI>IBM developerWorks articles <A
href="http://www-106.ibm.com/developerworks/webservices/library/ws-appwsif.html?loc=dwmain";>Applying
the Web services invocation framework</A> and <A
href="http://www-106.ibm.com/developerworks/webservices/library/ws-wsif.html";>Web
service invocation sans SOAP Part 1</A> and <A
href="http://www-106.ibm.com/developerworks/webservices/library/ws-wsif2.html";>Part
2</A>.</LI>
<LI><A
href="http://www.ericleach.com/sa2002/presentations/PFremantle-IBM.pdf";>A presentation
from Paul Fremantle at the 2002 Software Architecture conference</A></LI>
<LI><A
href="http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-axis-wsif/java/docs/apidocs/index.html";>Javadoc
for the wsif API classes</A><BR>
[<B>Note:</B> This link will work only after this package has been built.]</LI>
</ul>
<hr>
</body></html>
1.1 xml-axis-wsif/java/doc/user-guide.html
Index: user-guide.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: User's Guide</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: User's Guide</h1>
<hr>
<ul>
<li><a href="#whatisit">What is WSIF?</a></li>
<li><a href="#usingit">How to I use WSIF to invoke various WSDL-described
services, including SOAP services, EJBs, JMS, and legacy apps via the java connector
framework?</a></li>
<li><a href="bugs.html">Reporting Bugs</a></li>
<li><a href="mail.html">Mailing lists</a></li>
</ul>
<hr>
<a name="whatisit"><h2>What is WSIF?</h2></a>
<p><em>WSIF</em> stands for the <em>Web Services Invocation
Framework</em>. It supports a simple, WSDL-driven Java API for
invoking Web services, no matter how or where the services are
provided. The framework allows maximum flexibility for the
invocation of any WSDL-described service.</p>
<p>For more information, read the <a href="overview.html">WSIF overview</a>.</p>
<hr>
<a name="usingit"><h2>Using WSIF</h2>
<p>WSIF is capable of invoking any WSDL-described service. The <a
href="http://www.w3.org/TR/wsdl12/";>WSDL 1.2 specification</a> defines the current
WSDL standard, and an associated document, <a
href="http://www.w3.org/TR/2002/WD-wsdl12-bindings-20020709/";>WSDL 1.2 bindings</a>,
defines standard binding extensions that describe how to use the SOAP, HTTP and MIME
protocols to invoke services described using WSDL.</p>
<p>WSIF defines additional 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_extensions.htm">Local java binding
extensions for WSDL</a></li>
<li><a href="wsdl_extensions/ejb_extensions.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>
</ul>
</p>
<p>The WSIF distribution includes samples that show you how to invoke such
services using the WSIF API. The <a href="saples.html">Samples documentation</a>
describes them.</p>
<hr>
<a name="reportingbugs"><h2>Bugs</h2>
<p>You can find a list of outstanding bugs from <a
href="http://nagoya.apache.org/bugzilla/buglist.cgi?long_desc=wsif&long_desc_type=allwordssubstr";>Bugzilla</a>.</p>
<p>You can get yourself a Bugzilla login and register a new bug using the same
web site.</p>
<hr>
<a name="mailinglist"><h2>Getting help</h2>
<P>WSIF shares the Apache AXIS <a
href="http://xml.apache.org/axis/mail.html";>mailing list</a>
axis-user. To aid identifying posts about WSIF, the prefix <b>[wsif]</b> should be
added to each posts subject line.</P>
<hr width="100%">
</body></html>
1.1 xml-axis-wsif/java/doc/wsdl_extensions/jms_bindings.htm
Index: jms_bindings.htm
===================================================================
<!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>
