aslom 2002/12/10 10:33:52
Modified: java readme.htm
Log:
factored out readme into smaller pieces
Revision Changes Path
1.9 +160 -161 xml-axis-wsif/java/readme.htm
Index: readme.htm
===================================================================
RCS file: /home/cvs/xml-axis-wsif/java/readme.htm,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- readme.htm 7 Dec 2002 12:33:57 -0000 1.8
+++ readme.htm 10 Dec 2002 18:33:52 -0000 1.9
@@ -3,209 +3,208 @@
<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="README_files/wsif.txt" type="text/css"></head>
+<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,
+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>
<BR>WSIF enables developers to interact with representations
-of Web services instead of working directly with the Simple Object Access
+of Web services 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. It frees the developer from the constraints of having
-to develop services for particular transport protocols or service environments.
+can work with the same programming model regardless of how the Web service is
+implemented and accessed. It frees the developer from the constraints of having
+to develop services for particular transport protocols or service environments.
Thus, it has an API that provides binding-independent access to any Web service.<BR>
-<BR>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
+<BR>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. <BR>
-<BR>Finally, WSIF is closely based upon WSDL, so it can invoke any service
-that can be described in WSDL.
+<BR>Finally, WSIF is closely based upon WSDL, so it can invoke any service
+that can be described in WSDL.
-<H3>Whats new with WSIF?</H3>
+<H3>What is new with WSIF?</H3>
-The first Apache WSIF realease candidate is currently being worked on and
+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<BR>
<BR>
-The WSIF documentation is slowly coming together with descriptions of the WSIF
-<A
href="http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-axis-wsif/java/README_files/wsdl_extensions/java_extension.html";>Java</A>
-and
-<A
href="http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-axis-wsif/java/README_files/wsdl_extensions/ejb_extension.html";>EJB</A>
-bindings now available.<BR>
-<BR>
-WSIF has been changed so the Apache Axis provider is now used for the default SOAP
binding.
-WSIF has two SOAP providers, one based on Apache SOAP, the other on Apache Axis.
+WSIF has been changed so the Apache Axis provider is now used for the default SOAP
binding.
+WSIF has two SOAP providers, one based on Apache SOAP, the other on Apache Axis.
+
+ <a name="WhatIsIt"></a><h2>What is WSIF?</h2>
+ <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
+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>
+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
+<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)
+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
+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.<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.<h2>WSIF User Guide</h2>
+<p><b>Quick start: </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. 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>
+
+
+<h2>WSIF Developer Guide</h2>
+<h3>
+
+ <a name="CustomisingIt"></a>How can I customize my WSIF
+ installation?</h3>
+<p>This part of documentation is meant to help developers who want to modify
+WSIF by adding or changing its providers and implementing new protocols.</p>
+ <p>There are many points within the WSIF API that allow for
+ customization. <a href="doc/samples.html">An advanced WSIF sample</a>
+ demonstrates how to write your own WSIF service factory so that
+ dynamic binding selection follows your own customized
+ algorithm. The user can discover other customization points by
+ examining <a
+
href="http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-axis-wsif/java/docs/apidocs/index.html";>WSIF's
core API</a>.</p>
+ <p>Larger scale customization involves finding ways to expose
+ software that uses your proprietary protocols through WSDL, so
+ 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="doc/how_to_wsdl_extensions.htm">Writing your own WSDL
+ extensions to support new protocols</a></li>
+ <li><a href="doc/how_to_provider.htm">Writing your own WSIF
+ providers to support customized WSIF extensions</a></li>
+ </ol>
+<p>You may find also useful read WSIF documentation is with descriptions of
the WSIF
+<a href="doc/wsdl_extensions/java_extension.html">Java</a>
+and <a href="doc/wsdl_extensions/ejb_extension.html">EJB</a>
+bindings.</p>
+<p>You may find also useful to read about using <a
href="doc/mime_attachments.htm">Soap
+ Attachments using WSIF</a> and always important when debugging on <a
href="doc/trace.htm">
+how to use tracing in WSIF</a>.<BR>
<BR>
-<h3>Prerequisites</h3>
-<P>A J2SE v1.3 SDK (eg from <A href="http://java.sun.com/j2se";>Java J2SE site</A>)
and the Apache Jakarta Ant tool to build wsif. Ant is available at the <A
href="http://jakarta.apache.org/ant";>Apache ANT website</A>.
-To build WSIF the jars from the following packages are
required:</P><BLOCKQUOTE><TABLE width="90%">
- <TBODY>
-
- <TR>
- <TD width="573">JAXP compliant XML parser, such as <A
href="http://xml.apache.org/xerces2-j/index.html";>Apache Xerces</A>.</TD>
- <TD width="367">xercesImpl.jar xmlParserAPIs.jar</TD>
- </TR>
- <TR>
- <TD width="573">WSDL for Java API (WSDL4J), from the <A
href="http://www-124.ibm.com/developerworks/projects/wsdl4j/";>IBM developerWorks
site</A>.
- </TD>
- <TD width="367">wsdl4j.jar qname.jar</TD>
- </TR>
- <TR>
- <TD width="573">Apache SOAP, from the <A
href="http://xml.apache.org/soap";>Apache SOAP site</A></TD>
- <TD width="367">soap.jar</TD>
- </TR>
- <TR>
- <TD width="573">Apache Axis, from the <A
href="http://xml.apache.org/axis";>Apache Axis site</A></TD>
- <TD width="367">axis.jar saaj.jar jaxrpc.jar
commons-logging.jar</TD>
- </TR>
- <TR>
- <TD width="573">J2EE 1.3 from the <A
href="http://java.sun.com/j2ee/";>Java J2EE site</A></TD>
- <TD width="367">j2ee.jar</TD>
- </TR>
-
- </TBODY>
-</TABLE>
-</BLOCKQUOTE>
-<P>Currently, in order to successfully build WSIF, all the above prerequisites
-are required no matter which providers are going to be used.</P>
-
-<h2><a name="sourcecode">Accessing Builds and Source Code</a></h2>
-<p>The source code for this package is available on the Apache web site. Individual
-files can be accessed using the web-based
-<a href="http://cvs.apache.org/viewcvs.cgi/xml-axis-wsif/"; target="_blank">CVS
interface</a>.
-The entire package can be downloaded using the following instructions.</p>
-
-<h3><b><font size="+1">Accessing the Nightly Builds</font></b></h3>
-<p>This package is built nightly along with Axis. The build will create two
-zip files: wsif-bin-1.2.zip and xml-axis.wsif-src.zip. The first file contains a
-complete build image, which includes wsif.jar and the API Javadoc. The second file
contains a copy of the source code, which could
-be built using Ant. Both of these files can be accessed at the same location
-as the <a href="http://cvs.apache.org/dist/axis/nightly/"; target="_blank">Axis
nightly builds</a>.</p>
-
-<H3><B><FONT size="+1">Accessing the Source Tree (AnonCVS)</FONT></B></H3>
-<p>So, you've decided that you need access to the source tree to see the latest
-and greatest code. There's two different forms of CVS access. The first
-is anonymous and anybody can use it. The second is not and you must have
-a login to the development server. If you don't know what this means, join
-the <a href="http://xml.apache.org/axis/mail.html";>mailing list</a> and find
out.</p>
-<p>Anyone can checkout source code from our anonymous CVS server. To do so,
-simply use the following commands (if you are using a GUI CVS client, configure
-it appropriatly):
-
-</p><blockquote>
-<table width="90%">
-<tbody>
-<tr bgcolor="#f2c0f6">
-<td>
- <pre>cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic login
-password: anoncvs
-
-cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic checkout xml-axis-wsif</pre>
- </td>
- </tr>
- </tbody>
-</table>
-</blockquote>
-<h3><b><font size="+1">Full Remote CVS Access</font></b> </h3>
-<p>If you are a <i>Committer</i> and have a login on the
-Apache development server, this section is for you. If you are not a Committer,
-but you want to submit patches or even request commit privelages, please see the
-<a href="http://jakarta.apache.org/site/guidelines.html"; target="newone">Jakarta
-GuideLines </a>page (we follow the same rules) for more information.
</p>
-<p>To have full access to the CVS server, you need to follow the links depending
-on the operating system you are using:
-
-</p><ul>
-<li><a href="http://jakarta.apache.org/site/cvsonunix.html"; target="new">Unix</a>
-</li><li><a href="http://jakarta.apache.org/site/cvsonwin32.html";
target="new">Windows</a> </li>
-</ul>
-<h2>Building wsif</h2>
-<ul>
- <li>Obtain all the necessary jar files as listed in the prerequisites.
- </li><li>Set required environment variables, including,
- JAVA_HOME, ANT_HOME.
- </li><li>From the root directory of wsif (where build.xml is located), run
- <pre>ant -Dwsif.build.classpath=<classpath> <target></pre>
- where <classpath> contains the location of the preequisite JAR files<br>
- <br>
- and, where <target> is one of the following:
- <ul>
- <li>compile: Compiles the API
- </li><li>samples: Compiles the samples
- </li><li>javadocs: Builds the javadoc
- </li><li>srcdist: Creates the source distribution
- zip file.
- </li><li>dist: Creates the binary distribution zip
- file.
- </li><li>clean: Removes built files.
- </li><li>all: Cleans, creates source and binary distribution
- zip files.
- </li></ul>
-</li></ul>
<h2>More documentation</h2>
<P>More documentation is available in <a href="doc">doc/ subdirectory</a> and
includes:</P>
-<ul>
- <li><a href="doc/faq.htm">WSIF FAQ</a></li>
- <li><a href="doc/build.htm">How to build WSIF</a></li>
- <li>How to run tests WSIF</li>
- <li><a href="doc/how_to_provider.htm">How To Write WSIF Provider</a></li>
- <li><a href="doc/how_to_wsdl_extensions.htm">How to write your own WSDL
- extensions and plug them into WSDL4J</a></li>
- <li>Information about using <a href="doc/mime_attachments.htm">Soap
- Attachments using WSIF</a> and about <a href="doc/trace.htm">using trace</a></li>
- <li><a href="doc/samples.html">How to run the samples</a></li>
-</ul>
-
<h2>Getting help</h2>
-<P>WSIF shares the Apache AIXS <A
href="http://xml.apache.org/axis/mail.html";>mailing lists</A>
-axis-user and axis-dev. To aid identifying posts about WSIF, the prefix [WSIF]
should be added to each posts subject line.</P>
+<P>WSIF shares the Apache AXIS <a
href="http://xml.apache.org/axis/mail.html";>mailing lists</a>
+axis-user and axis-dev. To aid identifying posts about WSIF, the prefix
<b>[wsif]</b> should be added to each posts subject line.</P>
+
+ <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="http://xml.apache.org/axis/mail.html";>axis-user and
+ axis-dev mailing lists</A>. Be sure to prefix the subject of your
+ WSIF-related emails with <tt>[wsif]</tt>. If you find something
+ that outstanding issue or bug that interests you, feel free to
+ download WSIF's source code and work on it. Below you will find
+ instructions for accessing the source code.</p>
+ <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>
<h2>Reference</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>
opensource site.</LI>
+ </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-wsif.html";>Web
service invocation sans SOAP</A>
and <A
href="http://www-106.ibm.com/developerworks/webservices/library/ws-appwsif.html?loc=dwmain";>Applying
the Web services invocation framework</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>
