An internationalized collaboration

An internationalized collaboration is a collaboration 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 collaboration that handles locale-sensitive data is called the internationalization (I18N) of the collaboration. Preparing an internationalized collaboration for a particular locale is called the localization (L10N) of the collaboration.

This section provides the following information on an internationalized collaboration:

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 collaboration

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

Locale-sensitive design principles

To be internationalized, a collaboration 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 collaboration should obtain its error messages from an English-language message file.

IBM InterChange Server Express provides you with an internationalized version of InterChange Server and the collaboration runtime environment. However, you must ensure that any custom code that you create is internationalized.

Note:
The collaboration code that Process Designer Express creates is not internationalized. Once Process Designer Express generates your collaboration code, you must take the steps outlined in this section to internationalize your collaboration template.

Table 9 lists the locale-sensitive design principles that an internationalized collaboration must follow.

Table 9. Locale-sensitive design principles for collaborations
Design principle For more information
The text of all error and status messages needs to be isolated from the collaboration template 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 collaboration. Business object locales
Properties of collaboration configuration properties must be handled to include possible inclusion of multibyte characters. Collaboration configuration properties
Other locale-specific tasks must be considered. Other locale-sensitive tasks

Text strings

It is good programming practice to design an internationalized collaboration so that it refers to an external message file when it needs to obtain text strings rather than hardcoding text strings in the collaboration code. When a collaboration 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. For more information on globalized message files, see Creating a message file.

To globalize the logging, exception, and email operations, 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 10 lists the types of operations that use a message file and the associated Collaboration API methods in the BaseCollaboration class that the collaboration template uses to retrieve their messages from a message file.

Table 10. Methods to retrieve messages from a message file
Message-file operation BaseCollaboration method
Logging logInfo() , logError() , logWarning()
Exception Handling raiseException()
Email Notification sendMail()

Note:
InterChange Server standards recommend that trace messages are not included in a collaboration message file. Trace messages do not need to display in the language of the customer's locale because they are intended for the product debugging process.

Handling logging and exception messages

To ensure that logging and exception-handling are always obtained from the collaboration message file, do not use the forms of the methods in Table 10 that allow you to specify the message string directly within the call. For example, to log an error to the log destination, do not use the following call to logError():

logError("Log this message to the log destination");
 

Instead, create a unique identifier for the message and place the text within the collaboration message file. If this message were assigned a unique identifier of 712, its entry in the message file would appear as follows:

712 
 Log this message to the log destination. 
 

You can optionally add message parameters to this message as needed.

In an internationalized collaboration, the preceding call to logError() should be replaced with the following call, which obtains the log message from the collaboration message file:

logError(712);
 

Similarly, you should obtain all exception messages from the collaboration message file by avoiding use of the following form of raiseException():

void raiseException(String exceptionType, String message)
 

Instead, use one of the raiseException() forms that includes a message number.

Handling email messages

The sendEmail() method allows you to send a message to specified email recipients. In an internationalized collaboration, email messages should go in the collaboration message file. However, the sendEmail() method does not provide a form that allows you to specify the unique identifier of a message. Therefore, to send an email message, you must first extract the message from the message file and then use sendEmail() to send the retrieved message string. Table 11 shows the method that the collaboration can use to retrieve a message from a message file.

Table 11. Method to retrieve a message from the message file
Collaboration library class BaseCollaboration method
BaseCollaboration getMessage()

The following code fragment retrieves message 100 from the collaboration message file and includes this message as part of an email message:

String retrievedMsg = getMessage(100);
 sendEmail(retrievedMsg, subjectLine, recipientList);
 

Handling miscellaneous strings

In addition to handling the message-file operations in Table 10, an internationalized collaboration template should not contain any miscellaneous hardcoded strings. You should isolate these strings into the message file as well.

To globalize hardcoded strings, take the following steps:

For example, suppose your collaboration template contains the following line of code with a hardcoded string:

String imsg100 = "********Before entering order-to-ATP map********";
 

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

100
 ********Before entering order-to-ATP map********
 [EXPL]
 ATP Transaction: 162
 

In the collaboration template, replace the code that contains the hardcoded string with code that retrieves the isolated string (message 100) from the message file:

String imsg100 = getMessage(100);  
 //retrieve the message numbered '    100'
 String imsg100 = getMessage(100);       
 //display the retrieved message
 

For more information on the use of message files, see Creating a message file.

Business object locales

During execution of a collaboration object, there are two different locale settings:

When a business object is created, it always has a locale associated with its data. By default, every business object created in a collaboration uses the collaboration locale. However, a business object often needs to have the locale of the triggering business object (the flow locale). Because this collaboration locale might be different from the flow locale, you might need to assign the flow locale to business objects. Table 12 shows the method that the collaboration can use to retrieve the locale associated with the flow.

Table 12. Method to retrieve the collaboration's flow locale
Collaboration library class Method
BaseCollaboration getLocale()

Your collaboration template must ensure that the locales of the business objects are well maintained and properly used during the flow of any collaboration scenarios. Your collaboration can access this locale with the methods shown in Table 13.

Table 13. Methods to access the business object locale
Collaboration library class Method
BusObj getLocale() , setLocale()

When Process Designer Express creates a new port for a collaboration template, it creates a new BusObj object for the port with the name portNameBusObj, where portName is the name of the port. For example, if you create a port named To, Process Designer Express creates a BusObj object named ToBusObj with code that looks as follows:

BusObj ToBusObj = new BusObj("Item");
 

The constructor of the BusObj class creates a BusObj object with its locale set to the collaboration locale. If the business object needs to associate its data with the flow locale, the collaboration template must modify the business object's locale.

For example, suppose Process Designer Express generates code in Figure 19 to create BusObj objects for two ports, To and From.

Figure 19. Generated code to create business objects for ports

BusObj ToBusObj = new BusObj(triggeringBusObj.getType());
 BusObj FromBusObj = new BusObj(triggeringBusObj.getType());
 

The following code fragment internationalizes the generated code in Figure 19, by ensuring that the flow locale is set in these new BusObj objects:

BusObj ToBusObj = new BusObj(triggeringBusObj.getType());
 BusObj FromBusObj = new BusObj(triggeringBusObj.getType());
  
 // get flow locale from BaseCollaboration
 triggerLocale = getLocale();
  
 // set newly created BusObj objects' locale to flow locale
 ToBusObj.setLocale(triggerLocale);
 FromBusObj.setLocale(triggerLocale);
 

The BusObj() constructor also accepts a locale name as an argument. Therefore, an alternative way to rewrite the generated code in Figure 19 is to pass the flow locale directly to the constructor call, as follows:

// get flow locale from BaseCollaboration
 triggerLocale = getLocale();
  
 BusObj ToBusObj = new BusObj(triggeringBusObj.getType(), triggerLocale);
 BusObj FromBusObj = new BusObj(triggeringBusObj.getType(), triggerLocale);
 
Note:
The copy() and duplicate() methods of the BusObj class automatically handle assignment of the business object locale. Therefore, if the source business object has the correct locale, the target business object will have this locale as well.

Collaboration configuration properties

As discussed in Defining collaboration configuration properties (the Properties tab), a collaboration template can use two types of configuration properties to customize its execution:

The names of all collaboration 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 collaboration locale.

The collaboration template obtains the values of configuration properties with the getConfigProperty() or getConfigPropertyArray() method of the BaseCollaboration class. These methods correctly handle characters from multibyte code sets. However, to ensure that your collaboration template is internationalized, its code must correctly handle these configuration-property values once it retrieves them. The collaboration template must not assume that configuration-property values contain only single-byte characters.

Other locale-sensitive tasks

An internationalized collaboration 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 InterChange Server and its collaboration runtime environment, are written in Java. Therefore, when data is transferred between a collaboration and other components within InterChange Server, it is encoded in the Unicode code set and there is no need for character conversion.

Copyright IBM Corp. 2003, 2004