You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-commits@axis.apache.org by ve...@apache.org on 2012/01/11 10:39:45 UTC
svn commit: r1229940 - in /axis/axis1/java/trunk:
docs/integration-guide.html src/site/xdoc/integration-guide.xml
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:axis-dev@ws.apache.org">axis-dev@ws.apache.org</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>