axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bu...@apache.org
Subject cvs commit: xml-axis/java/docs integration-guide.html
Date Mon, 05 Nov 2001 14:09:02 GMT
butek       01/11/05 06:09:02

  Added:       java/docs integration-guide.html
  Log:
  Adding the skeleton integration guide.  The only section filled in is the internationalization
section.
  
  Revision  Changes    Path
  1.1                  xml-axis/java/docs/integration-guide.html
  
  Index: integration-guide.html
  ===================================================================
  <!doctype html public "-//w3c//dtd html 4.0 transitional//en">
  <html>
  <head>
     <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
     <meta name="GENERATOR" content="Mozilla/4.73 [en] (WinNT; U) [Netscape]">
     <title>Axis System Integration Guide</title>
  <!-- saved from url=(0022)http://internet.e-mail -->
  <style type="text/css">
  <!--
  .example { background:#ccccff }
  .xml { background:#eeeeee }
  body {  font-family: Verdana, Arial, Helvetica, sans-serif; margin-left: 40px}
  h2 {  text-decoration: underline; background-color: #DCE1FF; background-position: left;
margin-left: -30px}
  h3 {  margin-left: -10px}
  h1 {  margin-left: -30px}
  -->
  </style>
  </head>
  <body text="#000000" bgcolor="#FFFFFF">
  
  <center>
  <h1>
  <img SRC="axis.jpg" height=96 width=176></h1></center>
  
  <h1>
  Axis System Integration Guide</h1>
  <i>Alpha 2 Version</i>
  <h3>
  Table of Contents</h3>
  <a href="#Introduction">Introduction</a>
  <br><a href="#Architectural Overview">Architectural Overview</a>
  <br><a href="#Pluggable APIs">Pluggable APIs</a>
  <br>&nbsp; <a href="#System Management Plug">System Management</a>
  <br>&nbsp; <a href="#Logging/Tracing Plug">Logging/Tracing</a>
  <br>&nbsp; <a href="#Configuration Plug">Configuration</a>
  <br>&nbsp; <a href="#Handlers Plug">Handlers</a>
  <br>&nbsp; <a href="#Internationalization Plug">Internationalization</a>
  <br>&nbsp; <a href="#Performance Monitoring Plug">Performance Monitoring</a>
  <br>&nbsp; <a href="#Encoding Plug">Encoding</a>
  <h2>
  <a NAME="Introduction"></a>Introduction</h2>
  This guide presents a brief architectural overview of AXIS, but its primary
  purpose is to present how AXIS can be integrated into an existing web application
  server, such as Tomcat or WebSphere, for example.&nbsp; AXIS has a number
  of Pluggable APIs that are necessary for such an integration.
  <h2>
  <a NAME="Architectural Overview"></a>Architectural Overview</h2>
  &nbsp;
  <h2>
  <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.
  <h3>
  <a NAME="System Management Plug"></a>System Management</h3>
  What points are necessary to manage AXIS?
  <ul>
  <li>
  Justification/Rationale - why is this plug point necessary?&nbsp; 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?&nbsp; Ie., is synchronization required?</li>
  </ul>
  
  <li>
  Configuration/reconfiguration</li>
  
  <li>
  Default behavior if not plugged.</li>
  
  <li>
  Example</li>
  </ul>
  
  <h3>
  <a NAME="Logging/Tracing Plug"></a>Logging/Tracing</h3>
  How can AXIS fit into existing logging/tracing systems other than log4j?
  <ul>
  <li>
  Justification/Rationale - why is this plug point necessary?&nbsp; 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?&nbsp; Ie., is synchronization required?</li>
  </ul>
  
  <li>
  Configuration/reconfiguration</li>
  
  <li>
  Default behavior if not plugged.</li>
  
  <li>
  Example</li>
  </ul>
  
  <h3>
  <a NAME="Configuration Plug"></a>Configuration</h3>
  How can AXIS fit into existing configuration systems?
  <ul>
  <li>
  Justification/Rationale - why is this plug point necessary?&nbsp; 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?&nbsp; Ie., is synchronization required?</li>
  </ul>
  
  <li>
  Configuration/reconfiguration</li>
  
  <li>
  Default behavior if not plugged.</li>
  
  <li>
  Example</li>
  </ul>
  
  <h3>
  <a NAME="Handlers Plug"></a>Handlers</h3>
  What new handlers might a system integrator wish to implement?
  <ul>
  <li>
  Justification/Rationale - why is this plug point necessary?&nbsp; 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?&nbsp; Ie., is synchronization required?</li>
  </ul>
  
  <li>
  Configuration/reconfiguration</li>
  
  <li>
  Default behavior if not plugged.</li>
  
  <li>
  Example</li>
  </ul>
  
  <h3>
  <a NAME="Internationalization Plug"></a>Internationalization</h3>
  The plug point for internationalization isn't a framework, but simply a
  property file of the strings used in AXIS.
  <br>&nbsp;
  <ul>
  <li>
  Justification/Rationale</li>
  
  <br>In order for readers of languages other than English to be comfortable
  with AXIS, we provide a mechanism for the strings used in AXIS to be translated.&nbsp;
  We do not provide any translations in AXIS; we merely provide a means by
  which translators can easily plug in their translations.
  <br>&nbsp;
  <li>
  Interfaces</li>
  
  <br>AXIS uses the standard Java internationalization class:&nbsp; <font face="Courier
New,Courier"><font size=-1>PropertyResourceBundle</font></font>.&nbsp;
  To make this class easy to use, there are a number of methods on JavaUtils
  that are used to get the messages within the resource bundle.
  <p><font face="Courier New,Courier"><font size=-1>public static java.util.ResourceBundle
  getMessageResourceBundle();</font></font>
  <p><font face="Courier New,Courier"><font size=-1>public static String
  getMessage(String key) throws java.util.MissingResourceException;</font></font>
  <p><font face="Courier New,Courier"><font size=-1>public static String
  getMessage(String key, String var) throws java.util.MissingResourceException;</font></font>
  <p><font face="Courier New,Courier"><font size=-1>public static String
  getMessage(String key, String var1, String var2) throws java.util.MissingResourceException;</font></font>
  <p><font face="Courier New,Courier"><font size=-1>public static String
  getMessage(String key, String[] vars) throws java.util.MissingResourceException;</font></font>
  <p>AXIS programmers can work with the resource bundle directly via a call
  to <font face="Courier New,Courier"><font size=-1>JavaUtils.getMessageResourceBundle</font></font>,
  but the <font face="Courier New,Courier"><font size=-1>getMessage</font></font>
  methods should be used instead for two reasons:
  <br>&nbsp;
  <ol>
  <li>
  It's a shortcut.&nbsp; It is cleaner to call</li>
  
  <ol><font face="Courier New,Courier"><font size=-1>JavaUtils.getMessage("myMsg00");</font></font></ol>
  than
  <ol><font face="Courier New,Courier"><font size=-1>JavaUtils.getMessageResourceBundle().getString("myMsg00");</font></font></ol>
  
  <li>
  The <font face="Courier New,Courier"><font size=-1>getMessage</font></font>
  methods enable messages with variables.</li>
  </ol>
  
  <h4>
  The getMessage methods</h4>
  If you have a message with no variables
  <ol><font face="Courier New,Courier"><font size=-1>myMsg00=This is a string.</font></font></ol>
  then simply call
  <ol><font face="Courier New,Courier"><font size=-1>JavaUtils.getMessage("myMsg00");</font></font></ol>
  
  <p><br>If you have a message with variables, use the syntax <font face="Courier
New,Courier">"{X}"</font>
  where <font face="Courier New,Courier"><font size=-1>X</font></font>
is
  the number of the variable, starting at 0.&nbsp; For example:
  <ol><font face="Courier New,Courier"><font size=-1>myMsg00=My {0} is {1}.</font></font></ol>
  then call:
  <ol><font face="Courier New,Courier"><font size=-1>JavaUtils.getMessage("myMsg00",
  "name", "Russell");</font></font></ol>
  and the resulting string will be:&nbsp; "My name is Russell."
  <p>You could also call the String array version of <font face="Courier New,Courier"><font
size=-1>getMessage</font></font>:
  <ol><font face="Courier New,Courier"><font size=-1>JavaUtils.getMessage("myMsg00",
  new String[] {"name", "Russell"});</font></font></ol>
  
  <p><br>The String array version of <font face="Courier New,Courier"><font
size=-1>getMessage</font></font>
  is all that is necessary, but the vast majority of messages will have 0,
  1 or 2 variables, so the other <font face="Courier New,Courier"><font size=-1>getMessage</font></font>
  methods are provided as a convenience to avoid the complexity of the String
  array version.
  <p>Note that the <font face="Courier New,Courier"><font size=-1>getMessage</font></font>
  methods throw <font face="Courier New,Courier"><font size=-1>MissingResourceException</font></font>
  if the resource cannot be found.&nbsp; And ParseException if there are
  more {X} entries than arguments.&nbsp; These exceptions are <font face="Courier New,Courier"><font
size=-1>RuntimeException'</font></font>s,
  so the caller doesn't have to explicitly catch them.
  <p>The resource bundle properties file is org/apache/axis/utils/resources.properties.
  <br>&nbsp;
  <li>
  Mechanism</li>
  
  <br>The Java internationalization mechanism - i.e., a ResourceBundle backed
  by a properties file - and the java.text.MessageFormat class, are sufficient
  for our needs.
  <p>Entries in the properties file must follow the pattern:&nbsp; <font face="Courier
New,Courier"><font size=-1>&lt;string>&lt;2-digit
  suffix></font></font>.
  <p>Entries should be ordered in the properties file alphabetically by key.
  <p>Entries in the properties file must never be changed.&nbsp; If a code
  change requires a message change, don't change the existing message; instead
  create a new entry, incrementing the 2-digit suffix.&nbsp; This must be
  done for two reasons:&nbsp; 1.&nbsp; You don't know whether the message
  is being used elsewhere.&nbsp; 2.&nbsp; So the translator only has to be
  aware of, and translate, the new strings.&nbsp; Without this restriction,
  every time translators are given the properties file to translate, they
  would have to translate all strings all the time.
  <ul>&nbsp;</ul>
  We may occasionally want to trim the properties file of old data, but this
  should only be done on major releases.
  <ul>&nbsp;</ul>
  
  <li>
  Default behavior</li>
  
  <br>The default behavior, meaning what happens when a translated file doesn't
  exist for a given locale, is to fall back on the English-language properties
  file.&nbsp; If that file doesn't exist (unlikely unless something is seriously
  wrong), AXIS with throw an exception with an English-language reason message.
  <br>&nbsp;
  <li>
  Examples</li>
  
  <br>In <font face="Courier New,Courier"><font size=-1>org.apache.axis.client.Call.invoke</font></font>,
  there is the following statement:
  <p><font face="Courier New,Courier"><font size=-1>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  if ( operationName == null )</font></font>
  <br><font face="Courier New,Courier"><font size=-1>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  throw new AxisFault( "No operation name specified" );</font></font>
  <p>We will have to add an entry into org/apache/axis/utils/resources.properties.&nbsp;
  Something like:
  <p><font face="Courier New,Courier"><font size=-1>noOperation=No operation
  name specified.</font></font>
  <p>And change the code to read:
  <p><font face="Courier New,Courier"><font size=-1>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  if ( operationName == null )</font></font>
  <br><font face="Courier New,Courier"><font size=-1>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  throw new AxisFault(JavaUtils.getMessage("noOperation"));</font></font></ul>
  
  <h3>
  <a NAME="Performance Monitoring Plug"></a>Performance Monitoring</h3>
  How can we monitor the performance of AXIS?
  <ul>
  <li>
  Justification/Rationale - why is this plug point necessary?&nbsp; 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?&nbsp; Ie., is synchronization required?</li>
  </ul>
  
  <li>
  Configuration/reconfiguration</li>
  
  <li>
  Default behavior if not plugged.</li>
  
  <li>
  Example</li>
  </ul>
  
  <h3>
  <a NAME="Encoding Plug"></a>Encoding</h3>
  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?&nbsp; 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?&nbsp; Ie., is synchronization required?</li>
  </ul>
  
  <li>
  Configuration/reconfiguration</li>
  
  <li>
  Default behavior if not plugged.</li>
  
  <li>
  Example</li>
  </ul>
  
  </body>
  </html>
  
  
  

Mime
View raw message