Skip to main content
Previous sectionNext section

PEX API Reference

This reference applies to all PEX-supported languages, Java and the .NET languages.

BusinessOperation

The BusinessOperation class to provide implementation for a business operation, which sends the message to the external system. This class corresponds to the PEX framework EnsLib.PEX.BusinessOperation class. The EnsLib.PEX.BusinessOperation RemoteClassName property identifies the Java or .NET class with the business operation implementation.

The business operation can optionally use an adapter to handle the outgoing message. Specify the adapter in the OutboundAdapter property. 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.

Adapter Instance Variable

The Adapter instance variable provides access to the outbound adapter. You specify the adapter in the production definition.

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 you 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.

BusinessProcess

The BusinessProcess classes 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.

Persistent Property

The Persistent property provides persistence of the specified public variable while the business process is handling a incoming message and all responses to the corresponding outgoing messages that it sends. An ObjectScript BusinessProcess instance is active from being initiated to being terminated and preserves property values across different function calls. For Java and .NET business processes, each method is called in a separate instance and the values of public variables are not be preserved unless you specify the Persistent property for them. In Java, specify the Persistent property as @Persistent before the declaration of the public variable. In .NET, specify the Persistent property as [Persistent] before the declaration of the public variable. The Persistent property only works for String, primitive types and their boxed types.

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 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.

BusinessService

The BusinessService 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. There are three ways of implementing a business service:

  1. Polling business service with an adapter — The production framework at regular intervals calls the adapter’s OnTask() method, which sends the incoming data to the the business service ProcessInput() method, which, in turn calls the OnProcessInput method with your code.

  2. Polling business service that uses the default adapter — In this case, the framework calls the default adapter's OnTask method with no data. The OnProcessInput() method then performs the role of the adapter and is responsible for accessing the external system and receiving the data.

  3. Nonpolling business service — The production framework does not initiate the business service. Instead custom code in either a long-running process or one that is started at regular intervals initiates the business service by calling the Director.CreateBusinessService() method.

Adapter Instance Variable

The Adapter instance variable provides access to the inbound adapter associated with the business service.

OnProcessInput() Method

The OnProcessInput() method receives the message from the inbound adapter via the 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 component 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 Object Gateway for Java or .NET.

  • 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.

InboundAdapter

he 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.

BusinessHost Instance Variable

The BusinessHost instance variable provides access to the business service associated with the inbound adapter. The adapter calls the ProcessInput() method of the business service.

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 component 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.

OutboundAdapter

The OutboundAdapter is responsible for sending the data to the external system.

BusinessHost Instance Variable

The BusinessHost instance variable provides access to the BusinessOperation associated with the OutboundAdapter.

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.

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 component 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.

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 proprties. The PEX framework provides the persistence to objects derived from the Message class.