Port References and Dynamic Ports
A port reference is a handle that can be passed into or out of an XLANG schedule instance. This handle represents a real port instance (not just a name), and its type depends on the technology used to implement the port. Whenever you add a port to an XLANG schedule drawing, a new port reference field is added to the Port References message on the Data page. This port reference can be passed around as a field inside a message.
If the port can be completely specified at design time, then at runtime the XLANG Scheduler Engine can connect to the actual object specified based entirely on the information provided at design time. The port instance is constructed a priori, or in some cases, by the engine. Such a port is called a static port. You can use the port reference field from the Port References message to pass out a reference to this static port for use by other schedule instances or applications. This port reference is, generally, an opaque handle to the other schedule instances or applications that receive it. However, on the originating system, where the reference was generated, it can be resolved back to the real port. This is related to the notion of the dynamic port described next.
If the port cannot be specified at design time—that is, the precise instance of the port is known only when the schedule runs—then the XLANG Scheduler Engine must acquire a reference to the port at runtime. Such a port is called a dynamic port. For dynamic ports to be successfully resolved at runtime, in the XLANG schedule design, you must populate the port reference field in the Port References message with a reference passed into the schedule. The passed reference is provided in a message by another schedule or application that has access to the underlying real port implementation. For the reference to be useful, it must arrive before the dynamic port is needed by the schedule at runtime.
Figures 10.4 and 10.5 are from another example provided with the product. This example is nominally at Program FilesMicrosoft BizTalk ServerSDKXLANG SamplesDynamic BindingQueueQueueBindAppQueueBind.skv, or a similar place depending on your installation. Figure 10.4 is the business process page, and Figure 10.5 is the data page of QueueBind.skv. The schedule demonstrates the use of a dynamic port.
Figure 10.4. Example of dynamic port using MSMQ—Business Process.
Figure 10.5. Example of dynamic port using MSMQ—Data.
As with all examples supplied with the product, you can read more about such examples in a readme file supplied with the sample.
Figure 10.4 shows that the QueueBind XLANG schedule receives a message ItemOrder, via the GetOrder port connected to the GetOrder action, from an MSMQ queue called .private$purchase_dept. The received message contains a port reference to another MSMQ queue that must be used by this schedule to send a response. The next action, ProcessOrder, extracts this port reference and constructs the response document. The action DisplayAck is used to show the result of this operation, as part of the sample. The final step, SendAck, sends the constructed response to the port specified in the incoming document. Note that the SendAck port is a dynamic port using the MSMQ implementation technology. The port implementation box is shown with a light shadow under it. In Figure 10.5, note how the dynamic port reference is used on the Data page.
Figure 10.5 shows the Data page corresponding to the schedule shown in Figure 10.4. The ItemOrder is the incoming message. The Document field of this message is passed to the ProcessOrder method of the COM port QueueBindUtil using ProcessOrder_in message. The method returns the response document in the message ProcessOrder_out, in the sOrderAck field, and the MSMQ port reference in the sQueuePath field. Note that these fields are of the string type. The part that tells the XLANG Scheduler Engine how to resolve the dynamic port reference is the connection from the sQueuePath field of the ProcessOrder_out message to the SendAck field of the Port References message.
A port reference must contain enough information for the application (in this example, the schedule) holding the reference to locate and access the real port instance (in this example, the MSMQ queue). This information varies based on the implementation technology. We look at each technology in turn to see what the port reference looks like.
A Port Using COM Components
For a port based on a COM component, the port reference is either an interface (for example, IDispatch) or a COM moniker that can be resolved to an interface. The interface is acquired by binding to the port object using an associated moniker class implementation. COM components bound to static ports are instantiated by the XLANG Scheduler Engine, which also creates the running schedule instance. The monikers for these static ports are available through the Port References message from within the running schedule instance. Therefore, on the Data page, you can use this moniker string to fill an outgoing message field. This outgoing message can be used later to retrieve the moniker and resolve it back to an interface of the COM component, which is, the port.
Alternatively, such monikers can be acquired through the engine's object model (described in Chapter 11). No matter how such a moniker is acquired, it can be subsequently resolved back to the ports either by using the moniker class sked or directly in the schedule drawing by binding to the Port References message to resolve a dynamic port. Note that the sked moniker class is also implemented by the XLANG Orchestration Engine.
An example of a port moniker for a static port bound to a COM component looks as follows:
sked://MyMachine!XLANG Scheduler/ {D1BD91F0-B480-410c-96ED-476E2BA12D91}/MyCOMPort
The XLANG Scheduler Engine instantiates the COM component as part of the running schedule instance and provides a COM proxy for the port in that instance. The moniker that is generated by the engine is for this port proxy. This moniker is accessible through the port-specific field in the Port References message on the Data page and is used to populate outgoing message fields, if so desired.
COM Primer on Monikers, Interfaces, and ProxiesComponent Object Model (or COM) is an architecture that defines how objects interact. This interaction occurs over well-defined interfaces exposed by the objects and can occur within a single process or across processes or even across different machines. The remote interactions are covered by Distributed COM, or DCOM architecture. COM is a language-independent, binary specification for object interaction. It is the core of Microsoft's object framework. A COM interface is a set of functions exposed by an object. The interface defines a “contract” between the object and its users. The interface is the only COM-supported mechanism for interacting with the object, and it is rigorously defined by COM. The interface consists of an array of methods (functions). The interface is identified by a globally unique interface ID (GUID). COM provides many basic services as part of the framework. For example, you can create COM objects and inquire about the interfaces implemented by the objects. COM provides built-in support for managing object lifetimes, marshalling arguments between the caller and callee when an interface method is called, taking care of process and thread boundaries, enforcing access and rights control, and so on. COM uses a proxy and stub mechanism to manage the marshalling of arguments when a method call is made. If the caller of an interface method is in a different context from the object that implements the interface, then COM must determine how to make the call. The different contexts may be due to threading, process, machine, or even security boundaries. COM constructs an interface proxy for the caller and a corresponding stub for the callee. These two objects make the interface method call appear to be a local function call. Of course, the method call will fail if arguments cannot be correctly marshalled across the differing contexts. A moniker is a name that uniquely identifies a COM object, usually a specific instance of a COM class. COM defines an IMoniker interface. This interface must be implemented by a moniker class, which is a class that knows how to resolve a name into a running COM object instance. The XLANG Scheduler Engine implements such a moniker class that knows how to translate names based on the sked prefix. |
For a dynamic port using the COM technology, you must resolve this dynamic port by selecting a field in a message that contains a valid COM interface or a moniker for the real port that the dynamic port stands for. This message must be received before the dynamic port is accessed within the running schedule. The engine will acquire the COM interface to the real port (by resolving the moniker to an object instance, if necessary) before messages are sent in or out of the dynamic port.
Yet another kind of port is supported with COM components. This is called No Instantiation. This kind of port uses the method signature to construct a properly formed message, just like any other port connected to a COM component. However, what is different is the fact that the method and the COM component are never instantiated and called. See the section “Case 1: Application Calls a Method” for more information about this option.
A Port Using Message Queuing
For a static port connected to an MSMQ queue, the port-specific field in the Port References message contains the fully qualified path for the queue, as follows:
MyMachineprivate$QueuePrefix{373FEF8C-131B-4e39-97A2-ABABCFC14CB7}
The preceding example shows the path for a per-instance queue, as opposed to a fixed queue for all schedule instances. A per-instance queue contains a queue name prefix and a GUID to distinguish it from any other queue. If you need to, it is a good way of generating a unique endpoint for message delivery or receipt.
You can use a queue port reference to resolve a dynamic port connected to an MSMQ queue. You must connect a port reference that you get in a message to the field in the Port References message. The XLANG Scheduler Engine will locate the queue before sending or receiving messages through the dynamic port. See Figures 10.4 and 10.5 for examples.
A Port Using BizTalk Messaging
For a static port using the BizTalk Messaging Services, the port-specific field of the Port References message does contain a path for the BizTalk Messaging channel; however, the usage of this port reference is a bit different from other types of port implementations. For all other types of port implementations, the port reference is agnostic about the direction of message flow. For BizTalk Messaging-based ports, this is not so: You may only use the port reference of a receiving static port to resolve a sending dynamic port. Stated differently, dynamic ports that receive messages via BizTalk Messaging are not supported. Consequently, the port reference of a static port that sends messages cannot be used. See the section “BizTalk Messaging Binding Wizard” and Figure 10.19 for more information on how such a port is configured.
Figure 10.19. BizTalk Messaging wizard pages.
A port used to receive messages from BizTalk Messaging is always a static port. Such a port can optionally be used to activate the XLANG schedule. If used in this manner, the port cannot be used with multiple actions or with a single action in a loop. There can be at most one such port in a schedule. The port reference from this port cannot be used with any message.
A static port for receiving messages but not to activate the XLANG schedule does not have the previous restrictions—that is, you can use it in a loop and pass around its port reference so that others may send messages to it. However, the only protocol supported by BizTalk Messaging to post messages to an XLANG schedule port is HTTP. Figure 10.6 summarizes these statements.
Figure 10.6. Use of dynamic ports with BizTalk Messaging.
Figure 10.6 shows a schedule on the left using a dynamic channel to send messages. The dynamic channel is resolved (shown using the dotted arrow) by using a reference to a static channel defined in a schedule as shown on the right. There could be any number of such schedules. The dynamic channel will direct the outgoing message to the referenced port using the provided HTTP URL. The schedule on the left must receive the port reference in some message before it must resolve the dynamic channel. Comparing Figure 10.6 to Figure 10.3, the schedule on the left is like schedule C that generates responses, whereas the schedule on the right is like A or B that makes the request.
We reviewed characteristics of a BizTalk Messaging-based static port. Figure 10.6 showed how a reference to the static port is used to resolve a dynamic port. Now we review other characteristics of BizTalk Messaging-based ports in an XLANG schedule.
A port used to send messages can be static or dynamic. As stated earlier, the port reference for a port that sends messages is not used. A static port directs the messages to a known preexisting channel.
For a dynamic port, the channel to send the message to is selected at runtime. To resolve the channel to use, you must have previously received a message containing the destination address (as shown in Figure 10.6). You must connect this to the port reference field in the Port References message on the Data page. How a dynamic channel is resolved is described later in the section “BizTalk Messaging Binding Wizard.” This is an advanced topic and will be further dealt with in Chapter 16.
Note
Note that a dynamic channel is not the same as an open channel, which is a channel not associated with a specific source organization.
This concludes the conceptual material for ports and their binding to specific implementation technologies.