owenb 2002/12/17 07:02:07
Modified: proposals/website/src/documentation/content/xdocs book.xml
index.xml
Added: proposals/website/src/documentation/content/xdocs
overview.xml requirements.xml quickstart.xml
Log:
Update
Revision Changes Path
1.2 +4 -1
xml-axis-wsif/proposals/website/src/documentation/content/xdocs/book.xml
Index: book.xml
===================================================================
RCS file:
/home/cvs/xml-axis-wsif/proposals/website/src/documentation/content/xdocs/book.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- book.xml 17 Dec 2002 12:35:36 -0000 1.1
+++ book.xml 17 Dec 2002 15:02:07 -0000 1.2
@@ -8,16 +8,19 @@
<menu label="About">
<menu-item label="Introduction" href="index.html"/>
+ <menu-item label="Overview" href="overview.html"/>
<menu-item label="FAQ" href="faq.html"/>
</menu>
<menu label="Using WSIF">
+ <menu-item label="Quick Start" href="quickstart.html"/>
+ <menu-item label="Reqirements" href="requirements.html"/>
<menu-item label="Samples" href="wsif-samples/index.html"/>
</menu>
<menu label="Development">
- <menu-item label="To do" href="todo.html"/>
+ <menu-item label="To Do" href="todo.html"/>
<menu-item label="Changes" href="changes.html"/>
</menu>
</book>
1.2 +84 -1
xml-axis-wsif/proposals/website/src/documentation/content/xdocs/index.xml
Index: index.xml
===================================================================
RCS file:
/home/cvs/xml-axis-wsif/proposals/website/src/documentation/content/xdocs/index.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- index.xml 17 Dec 2002 12:35:36 -0000 1.1
+++ index.xml 17 Dec 2002 15:02:07 -0000 1.2
@@ -8,6 +8,89 @@
<section>
<title>Introduction</title>
<p>
+The Web Services Invocation Framework (WSIF) is a simple Java API for invoking Web
services,
+no matter how or where the services are provided.</p>
+
+<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>
+</section>
+
+<section>
+<title>Why should I use WSIF?</title>
+<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 andlanguage 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 accomodate 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>
+
+<p>You will find more details about WSIF and its architecture in the
+<link href="doc/overview.html">overview</link>.
+</p>
+</section>
+
+<section><title>How can I contribute to WSIF?</title>
+
+<p>You can contribute to WSIF by participating in discussions on the
+<link href="http://xml.apache.org/axis/mail.html";>axis-user and axis-dev
+mailing lists</link>. Be sure to prefix the subject of your WSIF-related
+emails with <code>[wsif]</code>. 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 <link href="doc/cvs.html">here</link>.
+</p>
+
+<p>You can find a list of outstanding bugs from <link
href="http://nagoya.apache.org/bugzilla/buglist.cgi?long_desc=wsif&long_desc_type=allwordssubstr";>Bugzilla</link>.
+</p>
+
+</section>
+
+<!--
The Web Services Invocation Framework (WSIF) is a simple Java API for invoking Web
services,
no matter how or where the services are provided. </p>
@@ -137,6 +220,6 @@
simply use the following commands (if you are using a GUI CVS client, configure
it appropriatly):
</p>
-</section>
+</section> -->
</body>
</document>
1.1
xml-axis-wsif/proposals/website/src/documentation/content/xdocs/overview.xml
Index: overview.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Web Services Invocation Framework: Overview</title>
</header>
<body>
<section>
<title>Overview</title>
<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>
</section>
<section>
<title>WSIF Structure</title>
<p>
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.</p>
<p>
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.</p>
<p>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.</p>
<p>
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.</p>
<p>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.</p>
</section>
<section><title>WSDL bindings for EJBs, JMs, JCA...</title>
<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:</p>
<ul>
<li><link href="wsdl_extensions/java_extensions.htm">Local java binding
extensions for WSDL</link></li>
<li><link href="wsdl_extensions/ejb_extensions.htm">EJB binding extensions for
WSDL</link></li>
<li><link href="wsdl_extensions/jms_bindings.htm">JMS binding extensions for
WSDL</link></li>
<li><link href="wsdl_extensions/j2c_extensions/wsif_j2c_extensions.htm">JCA
binding extensions for WSDL</link></li>
</ul>
</section>
</body>
</document>
1.1
xml-axis-wsif/proposals/website/src/documentation/content/xdocs/requirements.xml
Index: requirements.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Web Services Invocation Framework: Requirements</title>
</header>
<body>
<section>
<title>Prerequisites</title>
<p>A J2SE v1.3 SDK (eg from <link href="http://java.sun.com/j2se";>Java J2SE
site</link>) and the Apache Jakarta Ant tool to build wsif.
Ant is available at the <link href="http://jakarta.apache.org/ant";>Apache ANT
website</link>.
To build WSIF the jars from the following packages are required:</p>
<table>
<caption>Prerequisite jars</caption>
<tr>
<th>Description</th>
<th>Jar names</th>
</tr>
<tr>
<td>JAXP compliant XML parser, such as <link
href="http://xml.apache.org/xerces2-j/index.html";>Apache Xerces</link>.</td>
<td>xercesImpl.jar xmlParserAPIs.jar</td>
</tr>
<tr>
<td>WSDL for Java API (WSDL4J), from the <link
href="http://www-124.ibm.com/developerworks/projects/wsdl4j/";>IBM developerWorks
site</link>.</td>
<td>wsdl4j.jar qname.jar</td>
</tr>
<tr>
<td>Apache SOAP, from the <link href="http://xml.apache.org/soap";>Apache SOAP
site</link></td>
<td>soap.jar</td>
</tr>
<tr>
<td>Apache Axis, from the <link href="http://xml.apache.org/axis";>Apache Axis
site</link></td>
<td>axis.jar saaj.jar jaxrpc.jar commons-logging.jar</td>
</tr>
<tr>
<td>J2EE 1.3 from the <link href="http://java.sun.com/j2ee/";>Java J2EE
site</link></td>
<td>j2ee.jar</td>
</tr>
</table>
<p>Currently, in order to successfully build WSIF, all the above prerequisites
are required no matter which providers are going to be used.</p>
</section>
</body>
</document>
1.1
xml-axis-wsif/proposals/website/src/documentation/content/xdocs/quickstart.xml
Index: quickstart.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Web Services Invocation Framework: Quick Start</title>
</header>
<body>
<section>
<title>Preliminaries</title>
<p>Download the WSIF distribution from <link
href="http://cvs.apache.org/dist/axis/wsif/";>
http://cvs.apache.org/dist/axis/wsif/</link>. It comes in three flavors: the binary
distribution ("bin"), the source-only distribution ("src") or
everything
included ("all"). If you are familiar with CVS and
want to work with the latest code <link href="cvs.html">use cvs</link>. Using CVS
you can also retrieve any past release by using tag (for example
WSIF_2_0_ALPHA2).</p></section>
<section>
<title>Getting Started</title>
<p>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 <link href="faq.html">WSIF FAQ</link>. Then read about <link
href="wsif-samples/index.html">
how to run the samples</link>. Otherwise if you downloaded source code or accessed
it from CVS you will need
to build WSIF. To do this, first <link href="requirements.html">check that all
prerequisites</link> are available. Then <link href="build.html">proceed with
building</link>.</p>
<p>After you have successfully downloaded and installed WSIF, you
can test your installation by <link href="wsif-samples/index.html">running the
samples</link>. 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>
</section>
</body>
</document>
