rsitze 2002/10/04 16:12:16
Modified: java/docs integration-guide.html
Log:
Added general details that covers most of the pluggable components.
This, in addition to the existing details for the more complicated
pluggable stories, should complete the overall picture for pluggability
in AXIS.
Revision Changes Path
1.14 +151 -41 xml-axis/java/docs/integration-guide.html
Index: integration-guide.html
===================================================================
RCS file: /home/cvs/xml-axis/java/docs/integration-guide.html,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- integration-guide.html 1 Oct 2002 21:32:31 -0000 1.13
+++ integration-guide.html 4 Oct 2002 23:12:15 -0000 1.14
@@ -29,6 +29,7 @@
Table of Contents</h3>
<a href="#Introduction">Introduction</a>
<br><a href="#Pluggable APIs">Pluggable APIs</a>
+<br> <a href="#Components">Components</a>
<!-- <br> <a href="#System Management Plug">System Management</a>
-->
<br> <a href="#Logging/Tracing Plug">Logging/Tracing</a>
@@ -37,7 +38,6 @@
<br> <a href="#Internationalization Plug">Internationalization</a>
<br> <a href="#Performance Monitoring Plug">Performance Monitoring</a>
<br> <a href="#Encoding Plug">Encoding</a>
-<br> <a href="#Compiler">Compiler</a>
<br> <a href="#WSDL plug">WSDL Parser and Code Generator Framework</a>
<h2>
<a NAME="Introduction"></a>Introduction</h2>
@@ -53,6 +53,155 @@
<a NAME="Pluggable APIs"></a>Pluggable APIs</h2>
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.
+
+<h3>
+<a NAME="Components"></a>Components</h3>
+This section describes in general how to plug specializations
+of various components into AXIS.
+
+<h4>
+General Strategy
+</h4>
+To override the default behavior for a pluggable component:
+<ul>
+<li>Develop implementation of components interface</li>
+<br>
+<li>Define the implementation class to AXIS by either creating
+a service definition file (prefered)
+or by setting a system property.
+<ul>
+<br>
+<li><strong>PREFERED:</strong> To create a service definition file:</li>
+<ul>
+<li>The name of the service definition file is derived from the interface
+or abstract class which the service implements/extends:
+<br>
+<code>/META-INF/services/<componentPackage>.<interfaceName></code>.</li>
+<li>Put the fully qualified class name of the implementation class on a line by
itself
+in the service definition file.</li>
+</ul>
+<br>
+<li>Set system property:
+<ul>
+<li>The name of the system property is the name of the interface.</li>
+<li>The value of the system property is the name of the implementation.</li>
+<li>The optional system property name (in table, below) may be also be used.</li>
+<br>
+<li>Setting a system property is not prefered, particularly in a J2EE or other
application
+hosting environment, because it imposes a directive across all applications.
+This may or may not be appropriate behavior.
+If it is to be done, it should never be done from within a Web Application at
runtime.
+</li>
+</ul>
+</li>
+</ul>
+<br>
+<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>
+
+<h4>
+Example 1
+</h4>
+To override the default behavior for the Java Compiler:
+<ul>
+<li>An implementation of the <code>Compiler</code> interface is already provided
for the <code>Jikes</code> compiler.</li>
+<br>
+<li>Create the service definition file named:
+<br>
+<code>/META-INF/services/org.apache.axis.components.compiler.Compiler</code></li>
+<br>
+<li>Add the following line to the service definition file:
+<br>
+<code>org.apache.axis.components.compiler.Jikes</code></li>
+<br>
+<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>
+
+<h4>
+Example 2
+</h4>
+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:
+<ul>
+<li>Provide an implementation of the <code>SocketFactory</code> interface,
+for example <code>your.package.YourSocketFactory</code></li>
+<br>
+<li>Set the system property named
+<br>
+<code>org.apache.axis.components.net.SocketFactory</code>
+<br>
+to the value
+<br>
+<code>your.package.YourSocketFactory</code>
+<br>
+<p>This can be done by using the JVM commandline
+<br>
+<code>-Dorg.apache.axis.components.net.SocketFactory=your.package.YourSocketFactory</code>
+<br>
+</li>
+<li>Ensure that the implementation class is loadable by a class loader.
+</li>
+</ul>
+
+<h4>
+Reference
+</h4>
+
+<table border="1">
+<tr>
+<th>Component/Package</th>
+<th>Factory</th>
+<th>Interface</th>
+<th>Optional System Property</th>
+<th>Default Implementation</th>
+</tr>
+<tr>
+<td><code>org.apache.axis.components.compiler</code></td>
+<td><code>CompilerFactory.getCompiler()</code></td>
+<td><code>Compiler</code></td>
+<td><code>axis.Compiler</code></td>
+<td><code>Javac</code></td>
+</tr>
+<tr>
+<td><code>org.apache.axis.components.image</code></td>
+<td><code>ImageIOFactory.getImageIO()</code></td>
+<td><code>ImageIO</code></td>
+<td><code>axis.ImageIO</code></td>
+<td><code>MerlinIO, JimiIO, JDK13IO</code></td>
+</tr>
+<tr>
+<td><code>org.apache.axis.components.jms</code></td>
+<td><code>JMSVendorAdapterFactory.getJMSVendorAdapter()</code></td>
+<td><code>JMSVendorAdapter</code></td>
+<td><code></code></td>
+<td><code>JNDIVendorAdapter</code></td>
+</tr>
+<tr>
+<td><code>org.apache.axis.components.net</code></td>
+<td><code>SocketFactoryFactory.getFactory()</code></td>
+<td><code>SocketFactory</code></td>
+<td><code>axis.socketFactory</code></td>
+<td><code>DefaultSocketFactory</code></td>
+</tr>
+<tr>
+<td><code>org.apache.axis.components.net</code></td>
+<td><code>SocketFactoryFactory.getSecureFactory()</code></td>
+<td><code>SocketFactory</code></td>
+<td><code>axis.socketSecureFactory</code></td>
+<td><code>JSSESocketFactory</code></td>
+</tr>
+</table>
+
<!--
<h3>
<a NAME="System Management Plug"></a>System Management</h3>
@@ -227,7 +376,7 @@
which currently provides methods that return client and server
configurations.
-<p>Our focus will be how to define the implemenation class for
+<p>Our focus will be how to define the implementation class for
<code>EngineConfigurationFactory</code>.
<ul>
@@ -606,45 +755,6 @@
<a NAME="Encoding Plug"></a>Encoding</h3>
AXIS does not yet include an Encoding Plug.
<!--
-How can a system integrator plug in other encoding mechanisms such as SOAP
-1.2 or optimized XML-based encoding?
-<ul>
-<li>
-Justification/Rationale - why is this plug point necessary? Spec
-compliance?</li>
-
-<li>
-Interfaces</li>
-
-<li>
-Mechanism</li>
-
-<ul>
-<li>
-Life cycle</li>
-
-<li>
-Exception handling - in general; plug-in shouldn't throw any exceptions
-- does runtime ignore? Log?)</li>
-
-<li>
-Multiple thread support? Ie., is synchronization required?</li>
-</ul>
-
-<li>
-Configuration/reconfiguration</li>
-
-<li>
-Default behavior if not plugged.</li>
-
-<li>
-Example</li>
-</ul>
--->
-
-<!--
-<h3>
-<a NAME="Compiler"></a>Compiler</h3>
How can a system integrator plug in other encoding mechanisms such as SOAP
1.2 or optimized XML-based encoding?
<ul>
