In the Contract Repository, developers define one or more modules. The modules contain interfaces, which map to OLE Automation classes. Operations of interfaces are mapped to methods of the corresponding OLE Automation class. The mapping of data types (simple and complex) used in operations, as well as exceptions raised by operations, are mapped from the Contract Repository definition to the API used in Active Expert clients.
The following example contains the definition of an interface with a mapping to an OLE Automation class using the Visual Basic syntax.
Listing 4-10 Interface Definition
module Banking
{
interface Account
{
void Inquiry (in long AccountID, out string Balance) raises InquiryException;
void Withdraw (in long AccountID, in float Amount, out string Balance) raises
WithdrawException;
};
}
The following code listing shows the methods of the OLE Automation View in Visual Basic.
Listing 4-11 Methods of the OLE Automation View in Visual Basic for a Synchronous Call
Function Inquiry(ByVal AccountID As Long, ByRef Balance As string)
Function Withdraw (ByVal AccountID As Long, ByVal Amount As Float, ByRef Balance
As String
An instance of the OLE Automation View can be created by the CreateObject statement or by dragging its corresponding Application Builder-generated OCX onto the client form.
In addition to the synchronous invocation model, the Active Expert also supports the asynchronous service invocation style provided by the TUXEDO environment. The rationale for exposing this feature of TUXEDO via the Active Expert is that OLE Automation offers a natural way for ActiveX controls to trigger unsolicited events on their clients. The arrival of a reply to a previous asynchronous request can be defined as such an event. This style of request invocation is especially useful in a situation when the ActiveX control is running in an HTML page where the programming environment is inherently asynchronous. Mapping of the asynchronous service invocations extends the basic, synchronous mapping with new methods and provides an additional mapping to the event interface of the OLE Automation View. Note that this mapping applies only when the Automation View is an ActiveX control since plain OLE Automation servers do not support OLE events.
The Active Expert asynchronous API defines an extra method for asynchronous invocation per operation in the interface. The signature of this method contains only [in] parameters: one for each [in] and [inout] parameter of the operation.
The following code listing extends the example introduced in the previous section with the methods of the Automation View used for asynchronous invocations.
Listing 4-12 Methods of the OLE Automation View in Visual Basic for an Asynchronous Call
Function InquiryAsync(ByVal AccountID As Long) As DIBanking_AccountReply
Function WithdrawAsync (ByVal AccountID As Long, ByVal Amount As Float) As
DIBanking_Account_Reply
Methods of the Automation View used for asynchronous invocations return a reply object. The reply object is used to identify a specific asynchronous invocation and also serves as a container for the reply data. The type of the reply object (the reply interface) is specific to the interface to which the asynchronous operation belongs. In this example, InquiryAsync and WithdrawAsync both belong to the Account interface. There is one reply class for Contract Repository (or IDL) interface. The name of the reply interface is created by taking the name of the original interface and appending the word Reply. For example, the name of the reply interface for Account is AccountReply.
The reply interface contains methods to retrieve the reply data. There is a one-to-one correspondence between operations of the original interface and the reply interface. The names of the reply interface operations are obtained by prepending get_ and appending _Reply to the original operation names. The interface methods contain one [out] parameter for each [out] and [inout] parameter of the corresponding original operation.
The following example shows the operations of AccountReply in Visual Basic syntax.
Listing 4-13 Operations of AccountReply in Visual Basic
Public Sub get_INQUIRY_Reply(ByRef SBALANCE As String, Optional ByRef
exceptionInfo As VARIANT)
Public Sub get_WITHDRAWAL_Reply(ByRef SBALANCE As String, Optional ByRef
exceptionInfo As VARIANT)
Asynchronous invocation is targeted to Active Expert clients where the OLE Automation View of the interface is an ActiveX control. In this case, an OLE Automation Event Interface (referred to as event interface) is exposed by the Automation View (ActiveX control) to the client. The event interface is implemented by the client. The Automation View will automatically call the appropriate method of the event interface once the reply has arrived for an asynchronous request. This automatic delivery mechanism of replies integrates the TUXEDO system with the event/callback paradigm of GUI applications.
The Active Expert supports both the "push" and "pull" models of asynchronous communication programming. Normally, properties of the reply object are only read after the Active Expert has triggered the event signaling that the reply for the request has arrived ("push" model). If an attempt is made to read a property of the reply object before the reply has been arrived, a NoReplyYet user exception is returned. If the operation invoked on the reply object does not match the async operation that originally returned the reply object, a NoRequestInvoked user exception is raised.
In the context of the previous example, methods of the event interface exposed by the ActiveX control would be as follows.
Listing 4-14 Methods of the Event Interface Read by an ActiveX Control
Sub InquiryAsyncDone(ByValue Reply As DIBanking_AccountReply)
Sub WithdrawAsyncDone(ByValue Reply As DIBanking_AccountReply)
If the Automation View is a normal OLE Automation Server (not an ActiveX control), the client has to poll the reply object to retrieve the reply ("pull" model).