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. WebSphere Business Integration Adapters 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 C++ connector library methods in the GenGlobals 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
GenGlobals 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:

char * msg;
  //retrieve the message numbered '100'
  msg = generateMsg(100, CxMsgFormat::XRD_INFO, NULL, 0, NULL);
  MyClassObject::formatMsg(msg); // 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
GenGlobals getLocale()

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.

However, a C++ connector works with a C++ application (or technology). This application (or technology) might not have data already in the Unicode code set. Therefore, the application-specific component of the connector (written in C++, and converted by the connector framework to Java) might need to perform character conversion on application data for the application-specific business object. Figure 23 shows the character encoding for a C++ connector.

Figure 23. Character encoding with a C++ 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.

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

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

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 Corp. 1997, 2003