An internationalized connector

An internationalized connector is a connector that has been written so that it can be customized for a particular locale. A locale is the part of a user's environment that brings together information about how to handle data that is specific to the end user's particular country, language, or territory. The locale is typically installed as part of the operating system. Creating a connector that handles locale-sensitive data is called the internationalization (I18N) of the connector. Preparing an internationalized connector for a particular locale is called the localization (L10N) of the connector.

This section provides the following information on an internationalized connector:

What is a locale?

A locale provides the following information for the user environment:

A locale name has the following format:

ll_TT.codeset

where ll is a two-character language code (usually in lower case), TT is a two-letter country and territory code (usually in upper case), and codeset is the name of the associated character code set. The codeset portion of the name is often optional. The locale is typically installed as part of the installation of the operating system.

Design considerations for an internationalized connector

This section provides the following categories of design considerations for internationalizing a connector:

Locale-sensitive design principles

To be internationalized, a connector must be coded to be locale-sensitive; that is, its behavior must take the locale setting into consideration and perform the task appropriate to that locale. For example, for locales that use English, the connector should obtain its error messages from an English-language message file. The WebSphere Business Integration Adapters product provides you with an internationalized version of the connector framework. To complete the internationalization (I18N) of a connector you develop, you must ensure that your application-specific component is internationalized.

Table 15 lists the locale-sensitive design principles that an internationalized application-specific component must follow.

Table 15. Locale-sensitive design principles for application-specific components
Design principle For more information
The text of all error, status, and trace messages should be isolated from the application-specific component in a message file and translated into the language of the locale. Text strings
The locale of a business object must be preserved during execution of the connector. Business object locales
Properties of connector configuration properties must be handled to include possible inclusion of multibyte characters. Connector configuration properties
Other locale-specific tasks must be considered. Other locale-sensitive tasks
Text strings

It is good programming practice to design a connector so that it refers to an external message file when it needs to obtain text strings rather than hardcoding text strings in the connector code. When a connector needs to generate a text message, it retrieves the appropriate message by its message number from the message file. Once all messages are gathered in a single message file, this file can be localized by having the text translated into the appropriate language or languages.

This section provides the following information on how to internationalize text strings:

Handling logging and tracing

To internationalize the logging and tracing, make sure that all these operations use message files to generate text messages. By putting message strings in a message file, you assign a unique identifier to each message. Table 16 lists the types of operations that use a message file and the associated Java connector library methods in the CWConnectorUtil class that the application-specific component uses to retrieve their messages from a message file.

Table 16. Methods to log and trace messages from a message file
Message-file operation Connector library method
Logging generateAndLogMsg()
Tracing generateAndTraceMsg() or traceWrite()

Log messages should display in the language of the customer's locale. Therefore, log messages should always be isolated into a connector message file and retrieved with the generateAndLogMsg() method.

Because trace messages are intended for the product debugging process, they often do not need to display in the language of the customer's locale. Therefore, whether trace messages are contained in a message file is left at the discretion of the developer:

Handling miscellaneous strings

In addition to handling the message-file operations in Table 16,, an internationalized connector must not contain any miscellaneous hardcoded strings. You must isolate these strings into the message file as well. Table 17 shows the method that the application-specific component can use to retrieve a message from a message file.

Table 17. Method to retrieve a message from the message file
Connector library class Method
CWConnectorUtil generateMsg()

To internationalize hardcoded strings, take the following steps:

For example, suppose your application-specific component contains the following hardcoded string in a line of code:

********Before updating the event status********

To isolate this hardcoded string from the connector code, create a message in the message file and assign it a unique message number (100):

100
********Before updating the event status********
[EXPL]
Hardcoded message in pollForEvents()

The application-specific component retrieves the isolated string (message 100) from the message file and replaces the hardcoded string with this retrieved string:

//retrieve the message numbered '    100'
String msg100 = generateMsg(100, CWConnectorLogAndTrace.XRD_INFO,
    CWConnectorLogAndTrace.CONNECTOR_MESSAGE_FILE, 0);  
MyClassObject.formatMsg(msg100);  //send retrieved message to a custom method

For more information on the use of message files, see Message logging.

Business object locales

The connector might need to perform locale-sensitive processing (such as data format conversions) when it converts from application data to the application-specific business object. During processing of a business object in a connector, there are two different locale settings:

Table 18 shows the method that the connector can use to retrieve the locale associated with the connector framework.

Table 18. Method to retrieve the connector framework's locale
Connector Library Class Method
CWConnectorUtil getGlobalLocale()

When a business object is created, it can have a locale associated with its data. Your connector can access this business-object locale in either of the following ways:

Connector configuration properties

As discussed in Using connector configuration property values,, an application-specific component can use two types of configuration properties to customize its execution:

The names of all connector configuration properties must use only characters defined in the code set associated with the U.S English (en_US) locale. However, the values of these configuration properties can contain characters from the code set associated with the connector framework locale.

The application-specific component obtains the values of configuration properties with the methods described in Retrieving connector configuration properties. These methods correctly handle characters from multibyte code sets. However, to ensure that your connector is internationalized, its code must correctly handle these configuration-property values once it retrieves them. The application-specific component must not assume that configuration-property values contain only single-byte characters.

Other locale-sensitive tasks

An internationalized connector must also handle the following locale-sensitive tasks:

Character-encoding design principles

If data transfers from a location that uses one code set to a location that uses a different code set, some form of character conversion needs to be performed for the data to retain its meaning. The Java runtime environment within the Java Virtual Machine (JVM) represents data in Unicode. The Unicode character set is a universal character set that contains encodings for characters in most known character code sets (both single-byte and multibyte). There are several encoding formats of Unicode. The following encodings are used most frequently within the integration business system:

Most components in the WebSphere business integration system, including the connector framework, are written in Java. Therefore, when data is transferred between most system components, it is encoded in the Unicode code set and there is no need for character conversion.

Figure 23. Character encoding with a C++ connector

Because a Java connector works with a Java application (or technology), its application-specific component is written in Java, which handles data in the Unicode code set. The Java application (or technology) also has data already in Unicode. Therefore, a Java connector does not normally need to perform character conversion on application data for the application-specific business object. If some data is not in Unicode, the Java environment automatically supports character conversion between UCS-2 and a native encoding. However, if the application data includes data from some other external source (such as an operating-system file), the Java connector might need to handle character conversion. Figure 24 shows the character encoding for a Java connector.

Note:
A connector obtains the character encoding of its application from the CharacterEncoding connector configuration property. If your connector performs character conversion, make sure you instruct the connector end user to set this connector property to the correct value.
Figure 24. Character encoding with a Java connector

To obtain the character encoding at runtime, Table 19 shows the method in the Java connector library that the connector can use.

Table 19. Method to retrieve the connector framework's character encoding
Connector library class Method
CWConnectorUtil getGlobalEncoding()

A Java String is UCS-2 encoded. Therefore, the connector can get and set attribute values (those represented as Java Strings), default attribute values, and application-specific information in their native encoding by performing a simple conversion:

nativeEncodedAppSpecInfo = busObj.getAppText(attrName).getBytes(nativeEncoding);
Note:
Connector configuration properties with String values do not require character conversion because they originate from the InterChange Server repository and are therefore in the UCS-2 encoding.

Copyright IBM Corporation 1997, 2004. All Rights Reserved.