This section describes operations that affect the collaboration as a whole. It includes these operations:
Each collaboration template must have an associated message file. The message file contains the text for the collaboration's exception and logging messages. A unique number identifies each message in the message file. The text of the message may also include placeholder variables.
When the collaboration calls a method that displays a particular message, it passes the method the message's identifying number and potentially additional parameters. The method uses the identifying number to locate the correct message in the message file, and it inserts the values of the additional parameters into the message text's placeholder variables.
For example, a collaboration's message file might include a message identified as number 23, whose text includes two placeholder variables, marked as {1} and {2}:
23 Customer ID {1} could not be changed: {2}
When the collaboration wants to display or log this message, it passes the appropriate method, such as raiseException(), the identifying number of the message (23) and two additional parameters, the customer ID number (6701) and a String variable containing some additional explanatory text, such as greater than maximum length. The method locates the correct message, substitutes the parameter values for the message's placeholders, and displays or logs the following message:
Customer ID 6701 could not be changed: greater than maximum length
A collaboration template can log a message whenever something occurs that
might be of interest to an administrator. To log a message, use the
logInfo(),
logWarning(), and
logError() methods in your collaboration template. Each method is
associated with a different message severity level. Table 33 lists the
severity levels and their associated methods.
Table 33. Message levels for log methods
The message text that these methods send to the log destination is prefixed with the severity level.
This section provides the following information about logging messages:
Every collaboration template must have a message file to hold its log messages. When a collaboration logs an error, the text of the error message can come from the collaboration's message file. The following example logs an error message whose text is contained in the collaboration's message file:
logError(10, customer.get("LName"), customer.get("FName");
The text of error message 10 has two message parameters and appears as follows in the message file:
10 Credit report error for {1} {2}.
When the logError() method executes, it obtains the text for message 10 from the message file, substituting the customer's last name and first name substituted for message parameters 1 and 2, and prefixing the message with a severity of "Error". It then writes this error message to the collaboration's log destination.
For example, the logged message for a customer named John Davidson looks like this:
Error: Credit report error for Davidson John.
If the collaboration is configured for email notification, logError() also sends this error message to the designated email recipient (or recipients). Refer to Creating a message file, for information on how to set up a message file.
When creating messages, keep in mind that the way that administrators use the logging feature.
It is important to be precise when assigning error levels to messages. The InterChange Server email notification feature sends a message to a designated person, usually the administrator, when it detects the generation of an error message or fatal error message (logError()). Administrators use this InterChange Server email notification feature, and they additionally might link it to an email pager to send a page when an error occurs. By being precise when assigning error levels to messages, you can reduce the number of critical messages.
You can revise the text of a message at any time, such as to clarify or expand the text. However, after you assign a message number to a certain type of error, it is important that you do not reassign the number. Many administrators depend on scripts to filter log messages, and these scripts rely on the message numbers. Thus, it is important that the numbers in the message file do not change meaning. If they do, users can lose messages or receive inadvertent messages.
You can use the logInfo() method to create temporary messages for your own debugging. However, be sure to remove these debugging method calls when you are finished with development.
Resist the temptation to use the logInfo() method to document the normal operation of the collaboration. Doing so fills the administrator's log files with messages that are not of interest. Instead, use the trace() method to give the administrator detailed information for debugging.
You can add trace messages to your collaboration template so that when a collaboration object runs, it generates a detailed description of its actions. Trace messages are useful for your own debugging and for on-site troubleshooting by administrators.
Trace messages differ from log messages in that trace messages are suppressed by default, whereas log messages cannot be suppressed. Trace messages are generally more detailed and are meant to be viewed only under certain circumstances, such as when someone intentionally configures the collaboration object's trace level to a number higher than zero. You can send trace messages and log messages to different files.
There are two types of trace messages for a collaboration:
Use the Collaboration Object Properties dialog box in System Manager to set the trace levels for both types of trace messages.
The collaboration template developer creates the levels for which you can request collaboration-generated tracing, as the next section describes. System-generated tracing levels are the same for all collaboration objects. They are described under "InterChange Server Express-generated trace messages".
You can add trace messages to a collaboration template to report operations that are specific to that collaboration. Below are some examples of information that the collaboration can write to the trace file:
Each trace message must be associated with a trace level between 1 and 5. The trace level usually correlates to a level of detail: messages at level 1 typically contain less detail than messages at level 2, which contain less detail than those at level 3, and so forth. Thus, if you turn on tracing at level 1, you see messages that contain less detail than the messages at level 5. However, you can assign levels in any way that is useful to you. Here are some suggestions:
When you turn on tracing at a particular level, the messages associated with the specified level and those associated with all lower levels appear. For example, tracing at level 2 displays messages associated with both level 2 and level 1.
The following is an example of a message and the method call that generates the message. The message appears in the message file as follows:
20 Configuration property DO_VERIFICATION = {1}
The method call obtains the value of the configuration property
DO_VERIFICATION, then uses the value to replace the parameter in
the message. The
code appears in the collaboration as follows, and the message appears when the
user sets tracing to level 3:
String validateProp = getConfigProperty("DO_VERIFICATION"); trace(3, 20, validateProp); |
The following example obtains the value of an Employee business object's Salary attribute and makes a branching decision based on the amount of the salary. The message in the message file is:
15 Salary {1} {2}
The example sends a trace message documenting the salary amount and the
path taken.
int newsalary = employee.getInt("Salary"); String sal = Integer.toString(newsalary); if (newsalary <150000) { trace (3, 15, sal, "do extra check"); } else { trace (3, 15, sal, "take normal path"); } |
The InterChange Server Express collaboration runtime environment has a tracing component that provides messages about its execution of a collaboration.
The runtime environment tracing component uses six numbers to represent trace levels. The first level, zero, is the default setting, and it indicates that no tracing is occurring. Levels 1 through 5 each indicate an increasing level of detail. A level 1 trace provides the least detail and a level 5 trace provides the most detail.
To turn on tracing, change the collaboration object's trace level from
zero to a higher number. Individual trace messages are associated with
each level. Table 34 describes the types of messages that appear at each
level.
Table 34. Trace levels for system-generated tracing
To retrieve the collaboration's configuration property, use the getConfigProperty() method.
The following example shows how a collaboration can use a configuration
property to determine the code path.
if (getConfigProperty("CONVERT_NEGQTY").equals("true")) { // take this code path } else { // take this code path } |
To compare a property value with a specific value, always use an equals() method, as shown in the example. Do not use the conditional equality operator ==, which tests whether two variables refer to the same object, rather than that two objects contain the same values.
Note that the value is case-sensitive. The case of the configuration parameter must be the same as the case in the code that tests for equality. In the preceding example, a value of True would fail the comparison.
A configuration property can also take an array of values, separated by semicolons. For more information, refer to getConfigPropertyArray().
Typically, InterChange Server Express creates an instance of a collaboration object to process each triggering event. When the instance completes the handling of the triggering event, the system frees up its resources and returns them to the Java free pool. However, the JDK does not always clean up these instances efficiently, which can lead to excessive memory usage.
To reduce memory usage, InterChange Server Express uses the Collaboration Instance Reuse option, which allows the system to recycle an instance of a collaboration object by caching it and reusing it when the same type of collaboration object is instantiated at some later time. When InterChange Server Express can recycle an existing collaboration instance, it can avoid:
The system automatically uses the Collaboration Instance Reuse option as long as the collaboration template meets both of the following requirements:
If either of these conditions is not met, the Collaboration Instance Reuse option is not used. Therefore, to take advantage of this option, avoid use of template (global) variables in the collaboration-template code. A template variable is a variable you declare whose scope is the entire collaboration template. You declare a template variable in the area labelled "Global Variables:" in the Declarations tab of the Definitions window.
If your collaboration requires template variables and you still wish to use the Collaboration Instance Reuse option, ensure that the collaboration template meets the following programming requirements:
Important |
---|
A collaboration template containing template variables that are not initialized at the first node cannot safely be recycled because the variable values in the cached collaboration object instance persist when the instance is reused. When the cached collaboration instance is reused and begins execution, each template variable contains the value from the end of the previous use of the collaboration instance. |
After you have coded your collaboration template to correctly initialize its template variables, perform the following tasks to enable the Collaboration Instance Reuse option:
You define collaboration-specific configuration properties in the Template Definition window. Set the default value of EnableInstanceReuse according to the desired behavior of the collaboration objects:
You set the values of collaboration-specific configuration properties in the Properties tab of the Collaboration Object Properties window of System Manager. For more information, see the System Administration Guide.
If you cannot code your collaboration so that it meets the preceding programming requirements, do not use the Collaboration Instance Reuse option. To disable this option, do not define the EnableInstanceReuse collaboration configuration property for the collaboration template.
The software uses a cache, called the collaboration-instance cache, to hold instances of collaboration objects. It derives the size of the collaboration-instance cache from the value of the "Maximum number of concurrent events," which you configure in the General tab of the Collaboration Object Properties window of System Manager. You might need to resize the collaboration-instance cache depending on whether you are using the event-triggered or call-triggered flow-processing model to execute collaborations.
Resizing the collaboration-instance cache involves defining a collaboration configuration property called CollaborationInstanceCacheSize. You define this property with other collaboration properties, in the area labelled "Properties" in the General tab of the Template Definition window. After you define CollaborationInstanceCacheSize, set its value to a reasonable default value for the number of collaboration instances. For more information, see the description of the Collaboration Instance Reuse option in the System Administration Guide.
Normally, calling maps and submaps is done only from within a map. However, sometimes your collaboration might need to call a InterChange Server Express native map directly. Calling a native map from a collaboration provides a number of benefits:
Calling the native map from a collaboration template involves the following steps:
You can create a collaboration property that contains the name of the map to call. This step is not required but it frees the collaboration code from needing to be recompiled if the map name changes. Instead, if the map name changes, you only have to change the value of this collaboration property. For example, you could define a collaboration property called MAP_NAME to hold the name of the map you need to call. Collaboration properties are defined in the Template Definitions window. For more information, see "Defining collaboration configuration properties (the Properties tab)".
Initializing the collaboration template to call the map involves importing Java classes of the Mapping API into the collaboration template. InterChange Server Express maps require certain Java classes to execute. Some of these classes are not automatically included in a collaboration template. For the map to be able to execute, you must explicitly import the following map class and packages:
Import each of these items in the Imports section of the Declarations tab in the Template Definitions window. For example, add the following entries to the import table to import map classes into the collaboration template:
CxCommon.CxExecutionContext CxCommon.Exceptions.* CxCommon.Dtp.* CxCommon.BaseRunTimes.* DLM.*
For general information about how to import Java classes, see "Importing Java packages".
To call a map, use the runMap() method of the Mapping API class, DtpMapService. The runMap() method requires the following information to be passed in as arguments:
Therefore, you must initialize this information within the collaboration before the call to runMap().
To pass in the name of the map to execute, you can hardcode the map name in the call to runMap(). However, a more flexible design is to use a collaboration property to contain the name of the map. This design involves the following steps:
Figure 64 shows a line of code obtains the map name stored in the collaboration property MAP_NAME.
Figure 64. Obtaining the Name of the Map to Execute
String map_name = getConfigProperty("MAP_NAME");
The runMap() method requires an input array, which contains the source business objects for the map. Usually, a map transforms a single source business object. For such a map, this input array has only one element. When calling a map from within a collaboration, you usually want to put a copy of the triggering business object into this input array. You then pass this input array as the third argument to runMap().
Figure 65 shows a line of code that initializes the input array with a copy of the collaboration's triggering business object.
Figure 65. Initializing the Input Array with the Triggering Business Object
BusObj[] sourceBusObjs = { inputBusObj };
A map instances executes within a specific map execution context, which contains information that the map needs, such as the following:
The Mapping API represents a map execution context as a MapExeContext object. Within map code, you can always obtain the map's execution context from the system-generated variable, cwExecCtx. However, no such system-generated variable is accessible from within the collaboration template. Instead, your collaboration must take the following steps:
The CxExecutionContext class represents the global execution context for the collaboration. Therefore, to initialize the map execution context, you must take the following steps:
The setInitiator() method of the MapExeContext class sets the calling context (its deprecated term is "map initiator"). For more information on map execution contexts and the methods of the MapExeContext class, see the Map Development Guide.
Figure 66 shows a code fragment that initializes the map execution context with a calling context of EVENT_DELIVERY (converting from an application-specific business object to a generic business object) and an original-request business object of the triggering business object.
Figure 66. Initializing the map execution context
// Instantiate objects for the map execution context and the global // execution context map_exe_context = new MapExeContext(); global_exe_context = new CxExecutionContext(); // Assign the map execution context to the global execution context global_exe_context.setContext( CxExecutionContext.MAPCONTEXT, map_exe_context); // Initialize the map execution context map_exe_context.setInitiator(MapExeContext.EVENT_DELIVERY);
After the collaboration template has initialized the map information, it can call the map. Calling the runMap() method involves two steps:
This method is a static method within the Mapping API class, DtpMapService. Therefore, you do not need to instantiate a DtpMapService instance.
In addition to the input array, the runMap() method also requires an output array, which runMap() populates with the map's destination business objects and returns to the calling code. Usually, a map generates a single destination business object. For such a map, this output array has only one element.
Figure 67 shows the call to runMap() to execute the map with the following characteristics:
Figure 67. Calling runMap() to execute the map
BusObj[] destinationBusObjs = DtpMapService.runMap( map_name, CWMAPTYPE, sourceBusObjs, global_exe_context);
The map's destination business objects are available in the output array that runMap() returns. To send a destination business object out of the collaboration, you must copy it from the output array and into the appropriate collaboration variable. This collaboration variable is usually associated with the collaboration's To port. Therefore, the destination business object is usually copied to the ToBusObj collaboration variable.
Figure 68 uses the BusObj.copy() method to copy the single destination business object returned by the runMap() call in Figure 67 to the ToBusObj collaboration variable.
Figure 68. Populating the collaboration variable
ToBusObj.copy(destinationBusObjs[0]);