Author: veithen
Date: Wed Jan 11 09:39:44 2012
New Revision: 1229940
URL: http://svn.apache.org/viewvc?rev=1229940&view=rev
Log:
Migrated the Integration Guide to XDoc.
Added:
axis/axis1/java/trunk/src/site/xdoc/integration-guide.xml
- copied, changed from r1229765,
webservices/axis/trunk/site/src/java/src/documentation/content/xdocs/java/integration-guide.xml
Removed:
axis/axis1/java/trunk/docs/integration-guide.html
Copied: axis/axis1/java/trunk/src/site/xdoc/integration-guide.xml (from
r1229765,
webservices/axis/trunk/site/src/java/src/documentation/content/xdocs/java/integration-guide.xml)
URL:
http://svn.apache.org/viewvc/axis/axis1/java/trunk/src/site/xdoc/integration-guide.xml?p2=axis/axis1/java/trunk/src/site/xdoc/integration-guide.xml&p1=webservices/axis/trunk/site/src/java/src/documentation/content/xdocs/java/integration-guide.xml&r1=1229765&r2=1229940&rev=1229940&view=diff
==============================================================================
---
webservices/axis/trunk/site/src/java/src/documentation/content/xdocs/java/integration-guide.xml
(original)
+++ axis/axis1/java/trunk/src/site/xdoc/integration-guide.xml Wed Jan 11
09:39:44 2012
@@ -1,43 +1,37 @@
<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN"
"./dtd/document-v12.dtd">
-<document>
- <header>
- <title>WebServices - Axis</title>
- </header>
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you under the Apache License, Version 2.0 (the
+ ~ "License"); you may not use this file except in compliance
+ ~ with the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing,
+ ~ software distributed under the License is distributed on an
+ ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~ KIND, either express or implied. See the License for the
+ ~ specific language governing permissions and limitations
+ ~ under the License.
+ -->
+<document xmlns="http://maven.apache.org/XDOC/2.0";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0
http://maven.apache.org/xsd/xdoc-2.0.xsd";>
+ <properties>
+ <title>Integration Guide</title>
+ </properties>
<body>
-<a name="AxisSystemIntegrationGuide"/>
-<section>
-<title>Axis System Integration Guide</title>
-
-<p><i>1.2 Version</i><br/>
-<i>Feedback: <a
href="mailto:[email protected]";>[email protected]</a></i></p>
+<section name="Table of Contents">
-<a name="TableOfContents"/>
-<section>
-<title>Table of Contents</title>
-
-<ul>
- <li><a href="#Introduction">Introduction</a></li>
- <li><a href="#PluggableAPIs">Pluggable APIs</a></li>
- <ul>
- <li><a href="#Components">Components</a></li>
- <li><a href="#LoggingTracing">Logging/Tracing</a></li>
- <li><a href="#Configuration">Configuration</a></li>
- <li><a href="#Handlers">Handlers</a></li>
- <li><a href="#Internationalization">Internationalization</a></li>
- <li><a href="#PerformanceMonitoring">Performance Monitoring</a></li>
- <li><a href="#Encoding">Encoding</a></li>
- <li><a href="#WSDLParserAndCodeGeneratorFramework">WSDL Parser and Code
Generator Framework</a></li>
- </ul>
- <li><a href="#ClientSSL">Client SSL</a></li>
-</ul>
+<macro name="toc"/>
</section>
-<a name="Introduction"/>
-<section>
-<title>Introduction</title>
+<section name="Introduction">
<p>The primary purpose of this guide is to present how Axis can be integrated
into an existing web application server, such as Tomcat or WebSphere, for
example. Axis has a number of Pluggable APIs that are necessary for such an
integration.</p>
@@ -45,20 +39,15 @@
</section>
-<a name="PluggableAPIs"/>
-<section>
-<title>Pluggable APIs</title>
+<section name="Pluggable APIs">
<p>The following are the points that are pluggable in order to integrate Axis
into a web application server. The first subsection details a number of
pluggable components in general. More details are provided for other components
in the remaining subsections.</p>
-<a name="Components"/>
-<section>
-<title>Components</title>
+<subsection name="Components">
<p>This section describes in general how to plug specializations of various
components into Axis.</p>
-<section>
-<title>General Strategy</title>
+<h4>General Strategy</h4>
<p>To override the default behavior for a pluggable component:</p>
@@ -86,10 +75,7 @@
<li>Package the implementation class and, if used, the service definition
file in a JAR file and/or place it where it can be picked up by a class loader
(CLASSPATH).</li>
</ul>
-</section>
-
-<section>
-<title>Example 1</title>
+<h4>Example 1</h4>
<p>To override the default behavior for the Java Compiler:</p>
@@ -102,10 +88,7 @@
<li>Since <code>org.apache.axis.components.compiler.Jikes</code> is packaged
with Axis, all that needs to be done is to ensure that the service definition
file is loadable by a class loader.</li>
</ul>
-</section>
-
-<section>
-<title>Example 2</title>
+<h4>Example 2</h4>
<p>To override the default behavior for the SocketFactory in an environment
that does not allow resources to be located/loaded appropriately, or where the
behavior needs to be forced to a specific implementation:</p>
@@ -120,17 +103,14 @@
<li>Ensure that the implementation class is loadable by a class loader.</li>
</ul>
-</section>
-
-<section>
-<title>Reference</title>
+<h4>Reference</h4>
<p>(Component/Package: org.apache.axis.components.*)</p>
<table>
<tr>
- <th>Component Package</th>
+ <th>Component/Package</th>
<th>Factory</th>
<th>Interface</th>
<th>Optional System Property</th>
@@ -139,7 +119,7 @@
<tr>
<td>compiler</td>
- <td>CompilerFactory getCompiler()</td>
+ <td>CompilerFactory.getCompiler()</td>
<td>Compiler</td>
<td>axis.Compiler</td>
<td>Javac</td>
@@ -147,7 +127,7 @@
<tr>
<td>image</td>
- <td>ImageIOFactory getImageIO()</td>
+ <td>ImageIOFactory.getImageIO()</td>
<td>ImageIO</td>
<td>axis.ImageIO</td>
<td>MerlinIO, JimiIO, JDK13IO</td>
@@ -155,7 +135,7 @@
<tr>
<td>jms</td>
- <td>JMSVendorAdapterFactory getJMSVendorAdapter()</td>
+ <td>JMSVendorAdapterFactory.getJMSVendorAdapter()</td>
<td>JMSVendorAdapter</td>
<td></td>
<td>JNDIVendorAdapter</td>
@@ -163,7 +143,7 @@
<tr>
<td>net</td>
- <td>SocketFactoryFactory getFactory()</td>
+ <td>SocketFactoryFactory.getFactory()</td>
<td>SocketFactory</td>
<td>axis.socketFactory</td>
<td>DefaultSocketFactory</td>
@@ -171,7 +151,7 @@
<tr>
<td>net</td>
- <td>SocketFactoryFactory getSecureFactory()</td>
+ <td>SocketFactoryFactory.getSecureFactory()</td>
<td>SecureSocketFactory</td>
<td>axis.socketSecureFactory</td>
<td>JSSESocketFactory</td>
@@ -196,25 +176,17 @@ What points are necessary to manage Axis
</ul>
-->
-</section>
-
-</section>
+</subsection>
-<a name="LoggingTracing"/>
-<section>
-<title>Logging/Tracing</title>
+<subsection name="Logging/Tracing">
<p>Axis logging and tracing is based on the Logging component of the <a
href="http://jakarta.apache.org/commons/index.html";>Jakarta Commons</a>
project, or the Jakarta Commons Logging (JCL) SPI. The JCL provides a Log
interface with thin-wrapper implementations for other logging tools, including
<a href="http://jakarta.apache.org/log4j/docs/index.html";>Log4J</a>, <a
href="http://jakarta.apache.org/avalon/logkit/index.html";>Avalon LogKit</a>,
and <a>JDK 1.4</a>. The interface maps closely to Log4J and LogKit.</p>
-<section>
-<title>Justification/Rationale</title>
+<h4>Justification/Rationale</h4>
<p>A pluggable logging/trace facility enables Axis to direct logging/trace
messages to a host web application server's logging facility. A central logging
facility with a single point of configuration/control is superior to distinct
logging mechanisms for each of a multitude of middleware components that are to
be integrated into a web application server.</p>
-</section>
-
-<section>
-<title>Integration</title>
+<h4>Integration</h4>
<p>The minimum requirement to integrate with another logger is to provide an
implementation of the <code>org.apache.commons.logging.Log</code> interface. In
addition, an implementation of the
<code>org.apache.commons.logging.LogFactory</code> interface can be provided to
meet specific requirements for connecting to, or instantiating, a logger.</p>
@@ -255,10 +227,7 @@ What points are necessary to manage Axis
</li>
</ul>
-</section>
-
-<section>
-<title>Mechanism</title>
+<h4>Mechanism</h4>
<ul>
<li><b>Life cycle</b>
@@ -272,10 +241,7 @@ What points are necessary to manage Axis
</li>
</ul>
-</section>
-
-<section>
-<title>Logger Configuration</title>
+<h4>Logger Configuration</h4>
<ul>
<li><b>Log</b>
@@ -291,13 +257,9 @@ What points are necessary to manage Axis
</li>
</ul>
-</section>
-
-</section>
+</subsection>
-<a name="Configuration"/>
-<section>
-<title>Configuration</title>
+<subsection name="Configuration">
<p>The internal data model used by Axis is based on an Axis specific data
model: Web Services Deployment Descriptor (WSDD). Axis initially obtains the
WSDD information for a service from an instance of
<code>org.apache.axis.EngineConfiguration</code>.</p>
@@ -355,24 +317,19 @@ AxisClient = new AxisClient(config);</so
</li>
</ul>
-</section>
+</subsection>
-<a name="Handlers"/>
-<section>
-<title>Handlers</title>
+<subsection name="Handlers">
<p>See the <a href="architecture-guide.html">Architecture Guide</a> for
current information on Handlers.</p>
-</section>
+</subsection>
-<a name="Internationalization"/>
-<section>
-<title>Internationalization</title>
+<subsection name="Internationalization">
<p>Axis supports internationalization by providing both a property file of the
strings used in Axis, and an extension mechanism that facilitates accessing
internal Axis messages and extending the messages available to integration code
based on existing Axis code.</p>
-<section>
-<title>Translation</title>
+<h4>Translation</h4>
<ul>
<li>Justification/Rationale
@@ -383,7 +340,7 @@ AxisClient = new AxisClient(config);</so
<p>Axis makes use of the Java internationalization mechanism - i.e., a
java.util.ResourceBundle backed by a properties file - and the
java.text.MessageFormat class to substitute parameters into the message
text.</p>
<ul>
<li>java.util.ResourceBundle retrieves message text from a property file
using a key provided by the program. Entries in a message resource file are of
the form <key>=<message>.</li>
- <li>java.text.MessageFormat substitutes variables for markers in the
message text. Markers use the syntax "{X}" where <code>X</code> is the number
of the variable, starting at 0.</li>
+ <li>java.text.MessageFormat substitutes variables for markers in the
message text. Markers use the syntax <code>"{X}"</code> where <code>X</code> is
the number of the variable, starting at 0.</li>
</ul>
<p>For example: <code>myMsg00=My {0} is {1}.</code></p>
<p>Translation requires creating an alternate version of the property file
provided by Axis for a target language. The JavaDoc for
<code>java.utils.ResourceBundle</code> provides details on how to identify
different property files for different locales.</p>
@@ -394,10 +351,7 @@ AxisClient = new AxisClient(config);</so
</li>
</ul>
-</section>
-
-<section>
-<title>Extending Message Files</title>
+<h4>Extending Message Files</h4>
<p>Axis provides a Message file extension mechanism that allows Axis-based
code to use Axis message keys, as well as new message keys unique to the
extended code.</p>
@@ -435,13 +389,9 @@ AxisClient = new AxisClient(config);</so
</li>
</ul>
-</section>
-
-</section>
+</subsection>
-<a name="PerformanceMonitoring"/>
-<section>
-<title>Performance Monitoring</title>
+<subsection name="Performance Monitoring">
<p>Axis does not yet include specific Performance Monitoring Plugs.</p>
@@ -461,11 +411,9 @@ AxisClient = new AxisClient(config);</so
</ul>
-->
-</section>
+</subsection>
-<a name="Encoding"/>
-<section>
-<title>Encoding</title>
+<subsection name="Encoding">
<p>Axis does not yet include an Encoding Plug.</p>
@@ -486,11 +434,9 @@ How can a system integrator plug in othe
</ul>
-->
-</section>
+</subsection>
-<a name="WSDLParserAndCodeGeneratorFramework"/>
-<section>
-<title>WSDL Parser and Code Generator Framework</title>
+<subsection name="WSDL Parser and Code Generator Framework">
<p>WSDL2Java is Axis's tool to generate Java artifacts from WSDL. This tool is
extensible. If users of Axis wish to extend Axis, then they may also need to
extend or change the generated artifacts. For example, if Axis is inserted into
some product which has an existing deployment model that's different than
Axis's deployment model, then that product's version of WSDL2Java will be
required to generate deployment descriptors other than Axis's deploy.wsdd.</p>
@@ -504,12 +450,11 @@ How can a system integrator plug in othe
<li>The code generator back end (WSDL2Java itself)</li>
</ol>
-<section>
-<title>Symbol Table</title>
+<h4>Symbol Table</h4>
<p>The symbol table, found in org.apache.axis.wsdl.symbolTable, will contain
all the symbols from a WSDL document, both the symbols from the WSDL constructs
themselves (portType, binding, etc), and also the XML schema types that the
WSDL refers to.</p>
-<p>NOTE: Needs lots of description here.</p>
+<p><font color="#FF0000">NOTE: Needs lots of description here.</font></p>
<p>The symbol table is not extensible, but you <b>can</b> add fields to it by
using the Dynamic Variables construct:</p>
@@ -519,10 +464,7 @@ How can a system integrator plug in othe
<li>You get the value of the variable in your generators: Object myValue =
entry.getDynamicVar(MY_KEY);</li>
</ul>
-</section>
-
-<section>
-<title>Parser Front End and Generator Framework</title>
+<h4>Parser Front End and Generator Framework</h4>
<p>The parser front end and generator framework is located in
org.apache.axis.wsdl.gen. The parser front end consists of two files:</p>
@@ -572,7 +514,7 @@ parser.run("myfile.wsdl");</source>
<li>There are two run methods. The first, as shown above, takes a URI
string which represents the location of the WSDL file. If you've already parsed
the WSDL file into an XML Document, then you can use the second run method,
which takes a context and the WSDL Document.</li>
</ul>
<p>An extension of this class would ...</p>
- <p>NOTE: continue this sentiment...</p>
+ <p><font color="#FF0000">NOTE: continue this sentiment...</font></p>
</li>
<li>WSDL2
@@ -633,26 +575,17 @@ parser.run("myfile.wsdl");</source>
</li>
</ul>
-</section>
-
-<section>
-<title>Code Generator Back End</title>
+<h4>Code Generator Back End</h4>
<p>The meat of the WSDL2Java back end generators is in
org.apache.axis.wsdl.toJava. Emitter extends Parser.
org.apache.axis.wsdl.WSDL2Java extends WSDL2. JavaGeneratorFactory implements
GeneratorFactory. And the various JavaXXXWriter classes implement the Generator
interface.</p>
-<p>NOTE: Need lots more description here...</p>
-
-</section>
+<p><font color="#FF0000">NOTE: Need lots more description here...</font></p>
-<section>
-<title>WSDL Framework Extension Examples</title>
+<h4>WSDL Framework Extension Examples</h4>
<p>Everything above sounds rather complex. It is, but that doesn't mean your
extension has to be.</p>
-</section>
-
-<section>
-<title>Example 1 - Simple extension of WSDL2Java - additional artifact</title>
+<h5>Example 1 - Simple extension of WSDL2Java - additional artifact</h5>
<p>The simplest extension of the framework is one which generates everything
that WSDL2Java already generates, plus something new. Example 1 is such an
extension. It's extra artifact is a file for each service that lists that
service's ports. I don't know why you'd want to do this, but it makes for a
good, simple example. See samples/integrationGuide/example1 for the complete
implementation of this example.</p>
@@ -710,10 +643,7 @@ parser.run("myfile.wsdl");</source>
</li>
</ul>
-</section>
-
-<section>
-<title>Example 2 - Not quite as simple an extension of WSDL2Java - change an
artifact</title>
+<h5>Example 2 - Not quite as simple an extension of WSDL2Java - change an
artifact</h5>
<p>In this example, we'll replace deploy.wsdd with mydeploy.useless. For
brevity, mydeploy.useless is rather useless. Making it useful is an exercise
left to the reader. See samples/integrationGuide/example2 for the complete
implementation of this example.</p>
@@ -836,21 +766,15 @@ parser.run("myfile.wsdl");</source>
</li>
</ul>
-</section>
-
-</section>
+</subsection>
</section>
-<a name="ClientSSL"/>
-<section>
-<title>Client SSL</title>
+<section name="Client SSL">
<p>The default pluggable secure socket factory module (see <a
href="#PluggableAPIs">Pluggable APIs</a>) uses JSSE security. Review the JSSE
documentation for details on installing, registering, and configuring JSSE for
your runtime environment.</p>
</section>
-</section>
-
</body>
</document>
