Axis System Integration Guide

Table of Contents

Introduction

The reader may find useful background information in the Architecture Guide.

Pluggable APIs

System Management

• 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

• 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

• 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

• 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

• 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
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

• 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

• 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