IObjectContext interface  ISharedProperty interface

Chapter 2: ActiveX C++ Interface Reference

IObjectControl interface

Description

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.

Methods

Usage

Implement the IObjectControl interface:

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.


ActiveX component lifecycle

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:


Support for instance pooling

To support instance pooling using the IObjectControl interface, you must code your component as follows:

The decision whether to reuse a specific instance can be made at runtime.

NoteNote CanBePooled is not 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 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.

See also

IObjectContext interface

Chapter 19, “Creating ActiveX Components,” in the EAServer Programmer’s Guide




IObjectControl::Activate

Description

Indicates that a component instance has been activated.

Syntax

#include <jagctx.h>

HRESULT IObjectControl::Activate (void);

Returns

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.

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

See also

CanBePooled, Deactivate




IObjectControl::CanBePooled

Description

Determines whether a component instance is eligible for reuse.

NoteNote CanBePooled is not called if the Pooling option on the component’s Instances Tab is checked.

Syntax

#include <jagctx.h>

BOOL IObjectControl::CanBePooled (void);

Returns

Return value

To indicate

TRUE

The instance can be reused.

FALSE

The instance cannot be reused and should be deallocated.

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

See also

Activate, Deactivate




IObjectControl::Deactivate

Description

Indicates that a component instance has been deactivated.

Syntax

#include <jagctx.h>

void IObjectControl::Deactivate (void);

Usage

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.

See also

Activate, CanBePooled





Copyright © 2005. Sybase Inc. All rights reserved. ISharedProperty interface