jaguar.beans.enterprise.InstanceContext interface  jaguar.beans.enterprise.SharedObjectException class

Appendix A: Deprecated Java Classes and Interfaces

jaguar.beans.enterprise.ServerBean interface

Description

package com.sybase.jaguar.beans.enterprise;
public interface ServerBean

Interface for EAServer Java components, with methods that support transactional behavior and reuse of component instances.

Constructors

None required. If a component’s implementation class provides a default constructor, the EAServer runtime server calls the default constructor when creating a new component instance.

Methods

Usage

A component that implements ServerBean can participate in instance pooling. 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(InstanceContext, String) 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.

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


ServerBean lifecycle

Figure A-1 illustrates the states and state transitions in the lifecycle of a Java component that implements ServerBean.

Figure A-1: States in the ServerBean lifecycle

The state transitions are as follows:


Support for instance pooling

Instance pooling allows a single component instance to be activated and deactivated many times to serve different clients. Instance pooling can increase the performance of your application, since it eliminates unnecessary instance allocations. There are two ways to support pooling:

If the component’s Pooling option is enabled in EAServer Manager, EAServer never calls the canReuse() method since instances are always pooled.

If your component supports pooling, you must add code to the activate(InstanceContext, String) method that resets any class variables to their initial values. When activate returns, the component state must be the same 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.

See also

InstanceContext




ServerBean.activate(InstanceContext, String)

Description

Indicate that this component instance has been activated.

Syntax

Package

com.sybase.jaguar.beans.enterprise

Interface

ServerBean

public abstract void activate
            (InstanceContext ctx, String instanceKey)
            throws EnterpriseBeanException;

Parameters

ctx

An InstanceContext that is associated with the current component instance. activate should save a reference to the instance context for use in later method calls. This reference becomes invalid and must be discarded when deactivate() is called.

instanceKey

Not used.

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 canReuse() method to return false.

See “ServerBean lifecycle” for more information on when activate and deactivate are called.

If a component is declared to be transactional and its activate method throws an exception, the EAServer runtime server rolls back the transaction in which the component is about to participate.

See also

deactivate(), canReuse()




ServerBean.canReuse()

Description

Specify whether this component instance is eligible for reuse.

Syntax

Package

com.sybase.jaguar.beans.enterprise

Interface

ServerBean

public abstract boolean canReuse()

Returns

true or false to indicate whether the component instance is eligible to be recycled.

Usage

If the Pooling option is not set for your component in EAServer Manager, EAServer calls the component’s canReuse method after deactivating each instance to determine whether the instance can be reused. If canReuse returns false, EAServer destroys the instance. If the Pooling option is set, EAServer never calls the canReuse method. For more information on component properties, see the EAServer Manager online help.

Components that support instance pooling must be coded such that a recycled instance behaves the same as a newly allocated instance. Your implementation of the activate(InstanceContext, String) method must ensure that the instance state is reset to that of a newly allocated instance.

See also

activate(InstanceContext, String), deactivate(), destroy()




ServerBean.deactivate()

Description

Indicates that this component instance has been deactivated.

Syntax

Package

com.sybase.jaguar.beans.enterprise

Interface

ServerBean

public abstract void deactivate()
            throws EnterpriseBeanException;

Usage

The EAServer runtime calls deactivate() to indicate that the component instance is being deactivated. See “ServerBean 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 call InstanceContext.isRollbackOnly() to determine whether the current transaction is being committed or rolled back. If the transaction is being committed, deactivate() must send any cached database changes to the remote server(s).

If deactivate() throws an exception, the current transaction (if any) is rolled back; the caller of the component method that attempted to commit the transaction receives the exception as a JException with the message text included.

If your component is transactional and it maintains state (it calls InstanceContext.continueWork() from one or more methods), then deactivate() must verify that the current component state is ready for commit and throw an exception if it is not.

NoteNote deactivate should release references to the InstanceContext object that was received in the activate(InstanceContext, String) method. The InstanceContext is meaningless after deactivate has been called.

See also

activate(InstanceContext, String), canReuse(), destroy()




ServerBean.destroy()

Description

Indicates that this component instance is being released and will not be activated again.

Syntax

Package

com.sybase.jaguar.beans.enterprise

Interface

ServerBean

public abstract void destroy();

Usage

destroy should release any resources that were allocated by the component’s constructor.

See also

activate(InstanceContext, String), deactivate(), canReuse()





Copyright © 2005. Sybase Inc. All rights reserved. jaguar.beans.enterprise.SharedObjectException class