Return-Path: Delivered-To: apmail-xml-axis-dev-archive@xml.apache.org Received: (qmail 47485 invoked by uid 500); 5 Nov 2001 14:20:04 -0000 Mailing-List: contact axis-dev-help@xml.apache.org; run by ezmlm Precedence: bulk Reply-To: axis-dev@xml.apache.org list-help: list-unsubscribe: list-post: Delivered-To: mailing list axis-dev@xml.apache.org Received: (qmail 47476 invoked by uid 500); 5 Nov 2001 14:20:04 -0000 Delivered-To: apmail-xml-axis-cvs@apache.org Date: 5 Nov 2001 14:09:02 -0000 Message-ID: <20011105140902.73413.qmail@icarus.apache.org> From: butek@apache.org To: xml-axis-cvs@apache.org Subject: cvs commit: xml-axis/java/docs integration-guide.html X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N 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 =================================================================== Axis System Integration Guide

Axis System Integration Guide

Alpha 2 Version

Table of Contents

Introduction
Architectural Overview
Pluggable APIs
  System Management
  Logging/Tracing
  Configuration
  Handlers
  Internationalization
  Performance Monitoring
  Encoding

Introduction

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.  AXIS has a number of Pluggable APIs that are necessary for such an integration.

Architectural Overview

 

Pluggable APIs

The following are the points that are pluggable in order to integrate AXIS into a web application server.

System Management

What points are necessary to manage AXIS?
  • Justification/Rationale - why is this plug point necessary?  Spec compliance?
  • Interfaces
  • Mechanism
    • Life cycle
    • Exception handling - in general; plug-in shouldn't throw any exceptions - does runtime ignore? Log?)
    • Multiple thread support?  Ie., is synchronization required?
  • Configuration/reconfiguration
  • Default behavior if not plugged.
  • Example

Logging/Tracing

How can AXIS fit into existing logging/tracing systems other than log4j?
  • Justification/Rationale - why is this plug point necessary?  Spec compliance?
  • Interfaces
  • Mechanism
    • Life cycle
    • Exception handling - in general; plug-in shouldn't throw any exceptions - does runtime ignore? Log?)
    • Multiple thread support?  Ie., is synchronization required?
  • Configuration/reconfiguration
  • Default behavior if not plugged.
  • Example

Configuration

How can AXIS fit into existing configuration systems?
  • Justification/Rationale - why is this plug point necessary?  Spec compliance?
  • Interfaces
  • Mechanism
    • Life cycle
    • Exception handling - in general; plug-in shouldn't throw any exceptions - does runtime ignore? Log?)
    • Multiple thread support?  Ie., is synchronization required?
  • Configuration/reconfiguration
  • Default behavior if not plugged.
  • Example

Handlers

What new handlers might a system integrator wish to implement?
  • Justification/Rationale - why is this plug point necessary?  Spec compliance?
  • Interfaces
  • Mechanism
    • Life cycle
    • Exception handling - in general; plug-in shouldn't throw any exceptions - does runtime ignore? Log?)
    • Multiple thread support?  Ie., is synchronization required?
  • Configuration/reconfiguration
  • Default behavior if not plugged.
  • Example

Internationalization

The plug point for internationalization isn't a framework, but simply a property file of the strings used in AXIS.
 
  • Justification/Rationale

    • 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.  We do not provide any translations in AXIS; we merely provide a means by which translators can easily plug in their translations.
     
  • Interfaces

    • AXIS uses the standard Java internationalization class:  PropertyResourceBundle.  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.

    public static java.util.ResourceBundle getMessageResourceBundle();

    public static String getMessage(String key) throws java.util.MissingResourceException;

    public static String getMessage(String key, String var) throws java.util.MissingResourceException;

    public static String getMessage(String key, String var1, String var2) throws java.util.MissingResourceException;

    public static String getMessage(String key, String[] vars) throws java.util.MissingResourceException;

    AXIS programmers can work with the resource bundle directly via a call to JavaUtils.getMessageResourceBundle, but the getMessage methods should be used instead for two reasons:
     

    1. It's a shortcut.  It is cleaner to call
        2. JavaUtils.getMessage("myMsg00");
      than
        JavaUtils.getMessageResourceBundle().getString("myMsg00");
    2. The getMessage methods enable messages with variables.

    The getMessage methods

    If you have a message with no variables
      myMsg00=This is a string.
    then simply call
      JavaUtils.getMessage("myMsg00");


    If you have a message with variables, use the syntax "{X}" where X is the number of the variable, starting at 0.  For example:

      myMsg00=My {0} is {1}.
    then call:
      JavaUtils.getMessage("myMsg00", "name", "Russell");
    and the resulting string will be:  "My name is Russell."

    You could also call the String array version of getMessage:

      JavaUtils.getMessage("myMsg00", new String[] {"name", "Russell"});


    The String array version of getMessage is all that is necessary, but the vast majority of messages will have 0, 1 or 2 variables, so the other getMessage methods are provided as a convenience to avoid the complexity of the String array version.

    Note that the getMessage methods throw MissingResourceException if the resource cannot be found.  And ParseException if there are more {X} entries than arguments.  These exceptions are RuntimeException's, so the caller doesn't have to explicitly catch them.

    The resource bundle properties file is org/apache/axis/utils/resources.properties.
     

  • Mechanism

    • The Java internationalization mechanism - i.e., a ResourceBundle backed by a properties file - and the java.text.MessageFormat class, are sufficient for our needs.

    Entries in the properties file must follow the pattern:  <string><2-digit suffix>.

    Entries should be ordered in the properties file alphabetically by key.

    Entries in the properties file must never be changed.  If a code change requires a message change, don't change the existing message; instead create a new entry, incrementing the 2-digit suffix.  This must be done for two reasons:  1.  You don't know whether the message is being used elsewhere.  2.  So the translator only has to be aware of, and translate, the new strings.  Without this restriction, every time translators are given the properties file to translate, they would have to translate all strings all the time.

       
    We may occasionally want to trim the properties file of old data, but this should only be done on major releases.
       
  • Default behavior

    • 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.  If that file doesn't exist (unlikely unless something is seriously wrong), AXIS with throw an exception with an English-language reason message.
     
  • Examples

    • In org.apache.axis.client.Call.invoke, there is the following statement:

            if ( operationName == null )
                throw new AxisFault( "No operation name specified" );

    We will have to add an entry into org/apache/axis/utils/resources.properties.  Something like:

    noOperation=No operation name specified.

    And change the code to read:

            if ( operationName == null )
                throw new AxisFault(JavaUtils.getMessage("noOperation"));

Performance Monitoring

How can we monitor the performance of AXIS?
  • Justification/Rationale - why is this plug point necessary?  Spec compliance?
  • Interfaces
  • Mechanism
    • Life cycle
    • Exception handling - in general; plug-in shouldn't throw any exceptions - does runtime ignore? Log?)
    • Multiple thread support?  Ie., is synchronization required?
  • Configuration/reconfiguration
  • Default behavior if not plugged.
  • Example

Encoding

How can a system integrator plug in other encoding mechanisms such as SOAP 1.2 or optimized XML-based encoding?
  • Justification/Rationale - why is this plug point necessary?  Spec compliance?
  • Interfaces
  • Mechanism
    • Life cycle
    • Exception handling - in general; plug-in shouldn't throw any exceptions - does runtime ignore? Log?)
    • Multiple thread support?  Ie., is synchronization required?
  • Configuration/reconfiguration
  • Default behavior if not plugged.
  • Example