About Business Hosts and Adapters
This chapter discusses information that applies to all business hosts and adapters written in Java or .NET. For implementation details about a specific production component, refer to that component’s chapter.
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. For information about which methods are abstract, see “PEX API Reference.”
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 Gateway 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.
Setting Runtime Variables
The Java and .NET code of a custom production component can contain properties that will be set at runtime based on values defined in the Management Portal. At runtime, the values specified in the remoteSettings field of the built-in PEX component are assigned to the corresponding Java or .NET component. Values are defined in the format: property=value. More than one property/value pair can be specified as long as each pair is on its own line. Do not include any spaces on the line.
For example, suppose your inbound adapter needs a username and password at runtime. In your code, you create public string variables called username and pw. Then, in the Management Portal, you can define the following in the remoteSettings field of the business service that uses the adapter:
Within the PEX framework, most messages sent between business hosts are objects instantiated from a subclasses of com.intersystems.enslib.pex.Message in Java and InterSystems.EnsLib.PEX.Message in .NET. You simply add properties to your subclass, and then pass instantiated objects of the subclass using methods like SendRequestAsync() and SendRequestSync(). Within InterSystems IRIS, the Java or .NET message object corresponds to an object of class EnsLib.PEX.Message, which makes the message persistent and dynamic. By manipulating the object of type EnsLib.PEX.Message, you can reference any property in the Java or .NET object. Internally, the Java or .NET object is represented as JSON as it passes between business hosts, so viewing the messages in the Management Portal are displayed in JSON format.
Though you can use other message objects, they must still be persistent if they are being passed between business hosts. To pass an object to a built-in ObjectScript component, you use the type IRISObject and map it to the persistent object expected by that component. For example, if you are sending a message to the EnsLib.PubSub.PubSubOperation, you would map the IRISObject to EnsLib.PubSub.Request. Trying to pass a non-persistent object as a message between business hosts results in a runtime error.
Objects sent from an inbound adapter to a business service are arbitrary and do not need to be persistent.