Allows components to support EAServer’s instance pooling model. The component dispatcher calls the IObjectControl methods to indicate transitions in the lifecycle of an ActiveX component.
Activate – Indicates that a component instance has been activated.
CanBePooled – Determines whether a component instance is eligible for reuse.
Deactivate – Indicates that a component instance has been deactivated.
Implement the IObjectControl interface:
If you want to determine, at runtime, whether a specific instance should be pooled (do not check the Pooling option on the component’s Instances tab—otherwise, the CanBePooled method in the IObjectControl interface will not be called), or
If you need to reset the component’s state after deactivation.
The server can maintain a cache of idle component instances and bind them to individual clients only as needed. This strategy allows the server to service more clients without the performance drain caused by allocating a component instance for each request.
The Activate method indicates that an instance is being removed from the pool to service a client. The Deactivate method indicates that the instance is finished servicing the client. Instance reuse is optional (see “Support for instance pooling”). However, components that support it will achieve greater scalability.
If you are coding the component in C++, you can directly implement IObjectControl. However, some automation controllers such as PowerBuilder 7.0 provide built-in, implicit support. See your IDE’s documentation for more information.
The instance-pooling lifecycle is tightly coupled with the EAServer transaction model. See Chapter 2, “Understanding Transactions and Component Lifecycles,” in the EAServer Programmer’s Guide for a description of how components participate in transactions.
The next section discusses the ActiveX component lifecycle in detail.
The following figure illustrates the states and state transitions in the lifecycle of an ActiveX component.
Figure 2-1: States in the ActiveX component lifecycle
The state transitions are as follows:
New instance – The EAServer runtime allocates a new instance of the component class. The default constructor is called if one exists. The instance remains idle until the first method invocation.
Activation – Activation prepares a component instance for use by a client. Activate is called. Once an instance is activated, it is bound to one client and can service no other client until it has been deactivated.
In Method – In response to a method invocation request from the client, the EAServer runtime calls the corresponding class method in the component. The next state depends on the method’s execution, as follows:
If the method throws an uncaught exception, the instance is deactivated. If the method is participating in a transaction, the transaction is rolled back.
If the method has called IObjectContext::SetComplete or IObjectContext::SetAbort, the instance is deactivated.
If the method has called IObjectContext::EnableCommit or IObjectContext::DisableCommit, the instance is not deactivated. The client’s next method invocation is serviced by the same instance unless the client destroys its reference or disconnects.
Deactivation – Deactivation occurs when the instance has called either IObjectContext::SetComplete or IObjectContext::SetAbort, the client has destroyed its stub instance, or the client has disconnected. The EAServer runtime calls the component’s Deactivate method to indicate deactivation. After deactivation, the server calls the component’s CanBePooled method (unless the Pooling option in the component’s Instances tab is checked). If CanBePooled returns TRUE the instance is placed back in the idle pool for reuse. Otherwise, the instance is destroyed.
Destruction – The EAServer runtime destroys the component reference. The component’s destructor is called.
To support instance pooling using the IObjectControl interface, you must code your component as follows:
Code the class to implement the IObjectControl interface.
Code the CanBePooled method to return TRUE if
the instance state can be reset.
In the Activate method, add code to reset any class variables to their initial values, as if the component were freshly constructed. If the component keeps references to stateful objects across activation cycles, you must reset these objects to an initial state as well.
The decision whether to reuse a specific instance can be made at runtime.
IObjectControl is defined in jagctx.h, which is provided in the EAServer include subdirectory.
You must include initguid.h in only one source file that is linked into your component DLL. If you do not include initguid.h in one file or you include it several files, your project will not link.
initguid.h is not included with EAServer. It is part of the Win32 SDK. Both Microsoft Visual C++ and Powersoft Power++™ provide this file. Other ActiveX C++ builder tools may provide it as well.
Chapter 19, “Creating ActiveX Components,” in the EAServer Programmer’s Guide
Indicates that a component instance has been activated.
#include <jagctx.h> HRESULT IObjectControl::Activate (void);
Return value |
To indicate |
|---|---|
S_OK |
Success. |
Any other value. |
Interpreted as an error. If the component is transactional, the component dispatcher rolls back the transaction in which the component is about to participate. |
Activate and Deactivate allow
a component’s instances to be pooled. If a component supports
instance pooling, Activate must reset any class
variables to the initial values, as if the component instance were
being freshly constructed. To prohibit instance pooling, code the CanBePooled method
to return FALSE.
See “ActiveX component lifecycle” for more information on when Activate and Deactivate are called.
If a component is declared to be transactional and its Activate method returns an error (any value other than S_OK), the component dispatcher rolls back the transaction in which the component is about to participate.
Determines whether a component instance is eligible for reuse.
#include <jagctx.h> BOOL IObjectControl::CanBePooled (void);
Return value |
To indicate |
|---|---|
TRUE |
The instance can be reused. |
FALSE |
The instance cannot be reused and should be deallocated. |
If a component implements the IObjectControl interface, a single instance can be activated and deactivated many times to serve different clients. After deactivation, the component dispatcher calls the component’s CanBePooled method to determine whether the current instance can be reused. If CanBePooled returns FALSE, the dispatcher destroys the instance.
Components that support instance pooling must be coded such that a recycled instance behaves the same as a newly allocated instance. See “Support for instance pooling” for more information.
Indicates that a component instance has been deactivated.
#include <jagctx.h> void IObjectControl::Deactivate (void);
The EAServer runtime calls Deactivate to indicate that the component instance is being deactivated. See “ActiveX component lifecycle” for more information on when Activate and Deactivate are called.
If your component caches data changes, you can code the Deactivate method to send cached changes to the remote database server.
Deactivate can be used to deallocate or reset the state of objects that are initialized in the Activate method.
