nmukhi 2002/12/09 14:51:42
Added: java/doc index.html
Log:
New main page for WSIF, better organized and with more info - still needs work
Revision Changes Path
1.1 xml-axis-wsif/java/doc/index.html
Index: index.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 name="Author" content="Nirmal Mukhi">
<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>
<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>
<ul>
<li><a href="#WhatIsIt">What is WSIF?</a>
<li><a href="#InstallingIt">How do I download and install WSIF?</a></li>
<li><a href="#UsingIt">How do I use WSIF?</a></li>
<li><a href="#CustomisingIt">How can I customise my WSIF installation?</a></li>
<li><a href="#ContributingToIt">How can I contribute to
WSIF?</a></li>
<li><a href="#Refs">References</a></li>
</ul>
<hr width="100%">
<a name="WhatIsIt"/><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>For more information, take a look at the <a href="faq.htm">WSIF
FAQ</a>.
<p>Put a picture showing WSIF client with pluggable providers to
access service using different protocols.</p>
<hr width="100%">
<a name="InstallingIt"/><h2>How do I download and install
WSIF?</h2>
<hr width="100%">
<a name="UsingIt"/><h2>How do I use WSIF?</h2>
<p>After you have successfully downloaded and installed WSIF, you
can test your installation by <a href="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 acess 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 width="100%">
<a name="CustomisingIt"/><h2>How can I customise my WSIF
installation?</h2>
<p>There are many points within the WSIF API that allow for
customisation. <a href="samples.html">An advanced WSIF sample</a>
demonstrates how to write your own WSIF service factory so that
dynamic binding selection follows your own customised
algorithm. The user can discover other customisation 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 customisation involves finding ways to expose
software that uses your properietary 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="how_to_wsdl_extensions.htm">Writing your own WSDL
extensions to support new protocols</a></li>
<li><a href="how_to_provider.htm">Writing your own WSIF
providers to support customised WSIF extensions</a></li>
</ol>
<hr width="100%">
<a name="ContributingToIt"/><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>
<h3>Prerequisites for building WSIF</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>
<h3><a name="sourcecode">Accessing Builds and Source Code</a></h3>
<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>
<h3>Building wsif</h3>
<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>
<hr width="100%">
<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>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>
<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 width="100%">
</body></html>
