PEX API Reference
This reference lists the methods for PEX components written in any of the external languages that are supported by the PEX framework. The ObjectScript proxy classes generated for remote classes inherit from ObjectScript classes in the EnsLib.PEX package.
General Notes about Methods
As you override methods to implement a production component, keep the following in mind:
-
Each production component must override all abstract methods.
-
While native interoperability methods use one input argument and one output argument and return a status, the corresponding PEX methods take one input argument and return the output argument as a return value.
-
All error handling for PEX methods are done with exceptions.
-
For native interoperability methods that don't require persistent objects as input and output arguments, the corresponding PEX methods can also use arbitrary objects as arguments and return values. PEX utilizes forward proxy and reverse proxy of the external language server to map the arbitrary object appropriately.
-
For native interoperability methods that require persistent objects as arguments, such as the methods that send messages to other processes, the corresponding PEX methods can use PEX Messages as arguments and return values. Examples of such methods are SendRequestSync, SendRequestAsync, OnRequest, OnResponse and OnMessage.
-
When overriding callback methods, you should not change the formal spec of the methods even if you have customized the message class. The argument types should remain as objects.
Business Operations
The business operation can optionally use an adapter to handle the outgoing message. If the business operation has an adapter, it uses the adapter to send the message to the external system. The adapter can either be a PEX adapter or an ObjectScript adapter.
OnMessage() Method
The OnMessage() message is called when the business operation receives a message from another production component. Typically, the operation will either send the message to the external system or forwards it to a business process or another business operation. If the operation has an adapter, it uses the Adapter.invoke() method to call the method on the adapter that sends the message to the external system. If your operation is forwarding the message to another production component, it uses the SendRequestAsync() or the SendRequestSync() method.
Abstract method: you must implement.
Parameters: (request)
-
request—of type Object, this contains the incoming message for the business operation.
You must implement an OnMessage method with a single parameter of type Object. Within the method you can cast the parameter to the actual type passed by the caller.
Returns: Object
OnInit() Method
The OnInit() is called when the component is started. Use OnInit() to initialize any structures needed by the component.
Abstract method: you must implement.
Parameters: none
Returns: void
OnTearDown() Method
The OnTearDown() method is called before the component is terminated. Use OnTeardown() to free any structures.
Abstract method: you must implement.
Parameters: none
Returns: void
SendRequestAsync() Method
The SendRequestAsync() method sends the specified message to the target business process or business operation asynchronously.
Parameters: (target, request [ , description ])
-
target—a string that specifies the name of the business process or operation to receive the request. The target is the name of the component as specified in the Item Name property in the production definition, not the class name of the component.
-
request—specifies the message to send to the target. The request can either have a class that is a subclass of Message class or have the IRISObject class. If the target is a built-in ObjectScript component, you should use the IRISObject class. The IRISObject class enables the PEX framework to convert the message to a class supported by the target. Otherwise, you can use a subclass of the Message class.
-
description—an optional string parameter that sets a description property in the message header.
Returns: void
SendRequestSync() Method
The SendRequestSync() method sends the specified message to the target business process or business operation synchronously.
Parameters: (target, request [ ,timeout [ , description ]])
-
target—a string that specifies the name of the business process or operation to receive the request. The target is the name of the component as specified in the Item Name property in the production definition, not the class name of the component.
-
request—specifies the message to send to the target. The request can either have a class that is a subclass of Message class or have the IRISObject class. If the target is a built-in ObjectScript component, you should use the IRISObject class. The IRISObject class enables the PEX framework to convert the message to a class supported by the target. Otherwise, you can use a subclass of the Message class.
-
timeout—an optional integer that specifies the number of seconds to wait before treating the send request as a failure. The default value is -1, which means wait forever.
-
description—an optional string parameter that sets a description property in the message header.
LOGINFO(), LOGALERT(), LOGWARNING(), LOGERROR(), and LOGASSERT() Methods
The log methods write to the production log, which can be viewed in the management portal in the component’s Log tab. These methods have the same parameter and differ only in the type of the log message:
-
LOGINFO() has an info type.
-
LOGALERT() has an alert type.
-
LOGWARNING() has a warning type.
-
LOGERROR() has an error type.
-
LOGASSERT() has an assert type.
Parameters: (message)
-
message—a string that is written to the log.
Business Process
A Business Process class typically contains most of the logic in a production. A business process can receive messages from a business service, another business process, or a business operation. It can modify the message, convert it to a different format, or route it based on the message contents. The business process can route a message to a business operation or another business process. For information on making properties of a business process persistent, see Persistent Properties.
OnRequest() Method
The OnRequest() method handles requests sent to the business process. A production calls this method whenever an initial request for a specific business process arrives on the appropriate queue and is assigned a job in which to execute.
Abstract method: you must implement.
Parameters: (request)
-
request—an object that contains the request message sent to the business process.
OnResponse() Method
The OnResponse() method handles responses sent to the business process in response to messages that it sent to the target. A production calls this method whenever a response for a specific business process arrives on the appropriate queue and is assigned a job in which to execute. Typically this is a response to an asynchronous request made by the business process where the request’s responseRequired parameter has a true value.
Abstract method: you must implement.
Parameters: (request, response, callRequest, callResponse, completionKey)
-
request—an object that contains the initial request message sent to business process.
-
response—an object that contains the response message that this business process can return to the production component that sent the initial message.
-
callRequest—an object that contains the request that the business process sent to its target.
-
callResponse—an object that contains the incoming response.
-
completionKey—a string that contains the completionKey specified in the completionKey parameter of the outgoing SendAsync() method.
OnComplete() Method
The OnComplete() method is called after the business process has received and handled all responses to requests it has sent to targets.
Abstract method: you must implement.
Parameters: (request, response)
-
request—an object that contains the initial request message sent to business process.
-
response—an object that contains the response message that this business process can return to the production component that sent the initial message.
OnInit() Method
The OnInit() method is called when the component is started.
Abstract method: you must implement.
Parameters: none
Returns: void
OnTearDown() Method
The OnTearDown() method is called before the component is terminated.
Abstract method: you must implement.
Parameters: none
Returns: void
Reply() Method
The Reply() method sends the specified response to the production component that sent the initial request to the business process.
Parameters: (response)
-
response—an object that contains the response message.
SendRequestAsync() Method
The SendRequestAsync() method sends the specified message to the target business process or business operation asynchronously.
Parameters: (target, request [ , responseRequired [, completionKey [ , description ]]])
-
target—a string that specifies the name of the business process or operation to receive the request. The target is the name of the component as specified in the Item Name property in the production definition, not the class name of the component.
-
request—specifies the message to send to the target. The request can either have a class that is a subclass of Message class or have the IRISObject class. If the target is a built-in ObjectScript component, you should use the IRISObject class. The IRISObject class enables the PEX framework to convert the message to a class supported by the target. Otherwise, you can use a subclass of the Message class.
-
responseRequired—a boolean value that specifies if the target must send a response message.
-
completionKey—a string that will be sent with the response message.
-
description—an optional string parameter that sets a description property in the message header.
SendRequestSync() Method
The SendRequestSync() method sends the specified message to the target business process or business operation synchronously.
Parameters: (target, request [ ,timeout [ , description ]])
-
target—a string that specifies the name of the business process or operation to receive the request. The target is the name of the component as specified in the Item Name property in the production definition, not the class name of the component.
-
request—specifies the message to send to the target. The request can either have a class that is a subclass of Message class or have the IRISObject class. If the target is a built-in ObjectScript component, you should use the IRISObject class. The IRISObject class enables the PEX framework to convert the message to a class supported by the target. Otherwise, you can use a subclass of the Message class.
-
timeout—an optional integer that specifies the number of seconds to wait before treating the send request as a failure. The default value is -1, which means wait forever.
-
description—an optional string parameter that sets a description property in the message header.
SetTimer() Method
The SetTimer() method specifies the maximum time the business process will wait for all responses.
Parameters: (timeout [ , completionKey ] )
-
timeout—an integer that specifies a number of seconds or a string that specifies a time period, such as “PT15S”, which represents 15 seconds of processor time.
-
completionKey—a string that will be returned with the response if the maximum time is exceeded.
LOGINFO(), LOGALERT(), LOGWARNING(), LOGERROR(), and LOGASSERT() Methods
The log methods write to the production log, which can be viewed in the management portal in the component’s Log tab. These methods have the same parameter and differ only in the type of the log message:
-
LOGINFO() has an info type.
-
LOGALERT() has an alert type.
-
LOGWARNING() has a warning type.
-
LOGERROR() has an error type.
-
LOGASSERT() has an assert type.
Parameters: (message)
-
message—a string that is written to the log.
Business Service
The Business Service class is responsible for receiving the data from the external system and sending it to business processes or business operations in the production. The business service can use an adapter to access the external system.
OnProcessInput() Method
The OnProcessInput() method receives the message from the inbound adapter via the adapter’s ProcessInput() method and is responsible for forwarding it to target business processes or operations. If the business service does not specify an adapter, then the default adapter calls the OnProcessInput() method with no message and the business service is responsible for receiving the data from the external system and validating it.
Abstract method: you must implement.
Parameters: (message)
-
message—an object containing the data that the inbound adapter sent to the business service. The message can have any structure agreed upon by the inbound adapter and the business service. The message does not have to be a subclass of Message or IRISObject and is typically not persisted in the database.
OnInit() Method
The OnInit() method is called when the component is started. Use the OnInit() method to initialize any structures needed by the component.
Abstract method: you must implement.
Parameters: none
Returns: void
OnTearDown() Method
The OnTearDown() method is called before the business host is terminated. Use the OnTeardown() method to free any structures.
Abstract method: you must implement.
Parameters: none
Returns: void
ProcessInput() Method
The inbound adapter calls the ProcessInput0 method of the business service and the ProcessInput() method in turn calls the OnProcessInput() method that is your custom code.
Parameters: (input)
-
input—an object with an arbitrary structure by agreement with the inbound adapter. The parameters passed to the ProcessInput() method do not need to be persistent objects.
Returns: object
SendRequestAsync() Method
The SendRequestAsync() method sends the specified message to the target business process or business operation asynchronously.
Parameters: (target, request [ , description ])
-
target—a string that specifies the name of the business process or operation to receive the request. The target is the name of the component as specified in the Item Name property in the production definition, not the class name of the component.
-
request—specifies the message to send to the target. The request can either have a class that is a subclass of Message class or have the IRISObject class. If the target is a built-in ObjectScript component, you should use the IRISObject class. The IRISObject class enables the PEX framework to convert the message to a class supported by the target. Otherwise, you can use a subclass of the Message class.
-
description—an optional string parameter that sets a description property in the message header.
SendRequestSync() Method
The SendRequestSync() method sends the specified message to the target business process or business operation synchronously.
Parameters: (target, request [ ,timeout [ , description ]])
-
target—a string that specifies the name of the business process or operation to receive the request. The target is the name of the component as specified in the Item Name property in the production definition, not the class name of the component.
-
request—specifies the message to send to the target. The request can either have a class that is a subclass of Message class or have the IRISObject class. If the target is a built-in ObjectScript component, you should use the IRISObject class. The IRISObject class enables the PEX framework to convert the message to a class supported by the target. Otherwise, you can use a subclass of the Message class.
-
timeout—an optional integer that specifies the number of seconds to wait before treating the send request as a failure. The default value is -1, which means wait forever.
-
description—an optional string parameter that sets a description property in the message header.
LOGINFO(), LOGALERT(), LOGWARNING(), LOGERROR(), and LOGASSERT() Methods
The log methods write to the production log, which can be viewed in the management portal in the component’s Log tab. These methods have the same parameter and differ only in the type of the log message:
-
LOGINFO() has an info type.
-
LOGALERT() has an alert type.
-
LOGWARNING() has a warning type.
-
LOGERROR() has an error type.
-
LOGASSERT() has an assert type.
Parameters: (message)
-
message—a string that is written to the log.
Director
The Director class is used for nonpolling business services, that is, business services which are not automatically called by the production framework (through the inbound adapter) at the call interval. Instead these business services are created by a custom application by calling the Director.CreateBusinessService() method.
CreateBusinessService() Method
The CreateBusinessService() method initiates the specified business service.
Parameters: (connection, target)
-
connection—an IRISConnection object that specifies the connection to the external language server for your language.
-
target—a string that specifies the name of the business service in the production definition.
Return value: businessService—the return value contains the Business Service instance that has been created.
Inbound Adapter
The InboundAdapter is responsible for receiving the data from the external system, validating the data, and sending it to the business service by calling the ProcessInput() method.
OnTask() Method
The OnTask() method is called by the production framework at intervals determined by the business service CallInterval property. The OnTask() method is responsible for receiving the data from the external system, validating the data, and sending it in a message to the business service OnProcessInput() method. The message can have any structure agreed upon by the inbound adapter and the business service.
Abstract method: you must implement.
Parameters: none
OnInit() Method
The OnInit() method is called when the component is started. Use the OnInit() method to initialize any structures needed by the component.
Abstract method: you must implement.
Parameters: none
Returns: void
OnTearDown() Method
The OnTearDown() method is called before the business host is terminated. Use the OnTeardown() method to free any structures.
Abstract method: you must implement.
Parameters: none
Returns: void
LOGINFO(), LOGALERT(), LOGWARNING(), LOGERROR(), and LOGASSERT() Methods
The log methods write to the production log, which can be viewed in the management portal in the component’s Log tab. These methods have the same parameter and differ only in the type of the log message:
-
LOGINFO() has an info type.
-
LOGALERT() has an alert type.
-
LOGWARNING() has a warning type.
-
LOGERROR() has an error type.
-
LOGASSERT() has an assert type.
Parameters: (message)
-
message—a string that is written to the log.
Outbound Adapter
The Outbound Adapter class is responsible for sending the data to the external system.
OnInit() Method
The OnInit() method is called when the component is started. Use the OnInit() method to initialize any structures needed by the component.
Abstract method: you must implement.
Parameters: none
Returns: void
OnTearDown() Method
The OnTearDown() method is called before the business host is terminated. Use the OnTeardown() method to free any structures.
Abstract method: you must implement.
Parameters: none
Returns: void
Invoke() Method
The Invoke() method allows the BusinessOperation to execute any public method defined in the OutboundAdapter.
Parameters: (methodname, arguments )
-
methodname — specifies the name of the method in the outbound adapter to be executed.
-
arguments — contains the arguments of the specified method.
LOGINFO(), LOGALERT(), LOGWARNING(), LOGERROR(), and LOGASSERT() Methods
The log methods write to the production log, which can be viewed in the management portal in the component’s Log tab. These methods have the same parameter and differ only in the type of the log message:
-
LOGINFO() has an info type.
-
LOGALERT() has an alert type.
-
LOGWARNING() has a warning type.
-
LOGERROR() has an error type.
-
LOGASSERT() has an assert type.
Parameters: (message)
-
message—a string that is written to the log.
Message
The Message class is the abstract class that is the superclass class for persistent messages sent from one component to another. The Message class has no properties or methods. Users subclass the Message class in order to add properties. The PEX framework provides the persistence to objects derived from the Message class.