Chapter 2 ActiveX C++ Interface Reference

IObjectControl interface

Description

Allows components to support Jaguar's instance pooling model. Jaguar calls the IObjectControl methods to indicate transitions in the lifecycle of an ActiveX component.

Methods

• Activate - Method called by the Jaguar runtime server to indicate that a component instance has been activated.
• CanBePooled - Method called by the Jaguar runtime server to determine whether a component instance is eligible for reuse.
• Deactivate - Method called by the Jaguar runtime server to indicate that a component instance has been deactivated.

Usage

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.

     Note If you want to pool instances every time they are deactivated and you do not need to reset the component's state, you only need to check the Pooling option on the component's Instances tab.
  

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 Jaguar transaction model. See "Understanding Transactions and Component Lifecycle Models" in the Jaguar CTS Programmer's Guide for a description of how components participate in transactions.

The next section discusses the ActiveX component lifecycle in detail.

ActiveX component lifecycle

The following figure illustrates the states and state transitions in the lifecycle of an ActiveX component.

The state transitions are as follows:

• New instance - The Jaguar 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 Jaguar 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 Jaguar 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 Jaguar runtime destroys the component reference. The component's destructor is called.

Support for instance pooling

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.

   Note CanBePooled will not be called if the Pooling option on the component's Instances Tab is checked.

Header file requirements

IObjectControl is defined in jagctx.h, which is provided in the Jaguar 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 Jaguar. 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.

See Also

IObjectContext interface

Chapter 8, "Creating ActiveX Components" in the Jaguar CTS Programmer's Guide

IObjectControl::Activate

Description

Method called by the Jaguar runtime server to indicate that a component instance has been activated.

Syntax

#include <jagctx.h>

HRESULT IObjectControl::Activate (void);

Return Values

Usage

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 Jaguar runtime server rolls back the transaction in which the component is about to participate.

See Also

CanBePooled, Deactivate

IObjectControl::CanBePooled

Description

Method called by the Jaguar runtime server to determine whether a component instance is eligible for reuse.

   Note CanBePooled will not be called if the Pooling option on the component's Instances Tab is checked.

Syntax

#include <jagctx.h>

BOOL IObjectControl::CanBePooled (void);

Return Values

Usage

If a component implements the IObjectControl interface, a single instance can be activated and deactivated many times to serve different clients. After deactivation, the Jaguar server runtime calls the component's CanBePooled method to determine whether the current instance can be reused. If CanBePooled returns FALSE , Jaguar 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.

See Also

Activate, Deactivate

IObjectControl::Deactivate

Description

Method called by the Jaguar runtime server to indicate that a component instance has been deactivated.

Syntax

#include <jagctx.h>

void IObjectControl::Deactivate (void);

Usage

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

See Also

Activate, CanBePooled

Copyright © 2000 Sybase, Inc. All rights reserved.