Mastering PowerBuilder

Instance Pooling

Jaguar components can optionally support instance pooling. Instance pooling allows component instances to be reused over and over by different clients. When a client asks Jaguar for an instance of a component, Jaguar first checks its instance pool to see if there is one available for reuse. If not, it creates a new instance. This begins the component’s lifecycle. Depending on how the component properties are configured, the component instance will be placed in the pool at:

The end of the method invocation.

The end of a transaction or

Not at all (the instance will be destroyed).

The wizard automatically defines two user-defined events (top and bottom) and maps them as follows.

Event Name	PowerBuilder Event ID
Activate	PBM_COMPONENT_ACTIVATE
CanBePooled	PBM_COMPONENT_CANBEPOOLED
Deactivate	PBM_COMPONENT_DEACTIVATE

The CanBePooled event is defined when you do not select Instance Pooling; Jaguar triggeres CanBePooled event after each client use to find whether that event decided to participate in Instance Pooling. You can write code in this event and specify whether that component instance should be pooled. When Instance Pooling is turned on, Jaguar does not fire CanBePooled event at all.

In your initial application migration to Jaguar, you don’t need to be concerned with making your components able to take full advantage of instance pooling because they can be deployed to be non-pooled and will behave similarly to Distributed PowerBuilder objects. However, at some point in your development, you should consider modifying components to support pooling for scalability. This can be accomplished on a component-by-component basis as warranted.

When you are ready to take advantage of instance pooling, a good first step would be to move most the logic found in your Constructor and Destructor events to the new Activate and Deactivate events. Pooled components will use the Activate and Activate events to reset the "state" of the component before its instance is used with another client.

Activate event is called when:

• The component is first created
• Each time it brought out of the instance pool for use.

Deactivate is called when:

• A transaction has been completed
• There is a timeout
• Auto Demarcation/Deactivation is turned on and a method completes execution.

The constructor event is still a good place for the code that needs to be run only once, such as the preparation of transaction objects or the creation of data stores used every time the component is used. A good rule of thumb is to place code in the Activate event that prepares the particular session, not the object. Also, when using pooled instances, keep in mind that the Destructor event may never be fired because Jaguar will always try to reuse the component instance.

It is also a good idea to place the database connectivity logic into the component’s Activate and Deactivate events. In these events you may want to check whether it is already in a transaction and act accordingly. The following seven steps explains the lifecycle of a component (PowerBuilder class object) in detail.

The component is typically instantiated on the first method invocation. When this occurs on a component developed in PowerBuilder, Jaguar creates a new PowerBuilder session for the component to run in.

The PowerBuilder session creates an instance of the requested PowerBuilder Class object that represents the Jaguar component—fires the Constructor event.

Jaguar triggers the Activate event on the non-visual object.

Jaguar then executes the method called by the client on the component.

If Automatic Demarcation/Deactivation setting for the component is enabled, the Deactivate event is triggered as soon as the method completes execution. Otherwise, Jaguar waits for the notification from the component.

CanBePooled event is fired if the component is not participating in Instance Pooling.

If that event returns 1, then the component is put in the pool. Otherwise, Jaguar triggers the Destructor event. Then it destroys the PowerBuilder object and terminates the runtime session.

Home	Previous Lesson: Service Component Next Lesson: Component TimeOut