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.
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.
activate(InstanceContext, String) – Indicates that this component instance has been activated.
canReuse() – Specify whether this component instance is eligible for reuse.
deactivate() – Indicates that this component instance has been deactivated.
destroy() – Indicates that this component instance is being released and will not be activated again.
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.
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:
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(InstanceContext, String) 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 InstanceContext.rollbackWork() or InstanceContext.completeWork(), the instance is deactivated.
If the method has called InstanceContext.continueWork(), 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 InstanceContext.rollbackWork() or InstanceContext.completeWork()
The current transaction times out, or
The client’s instance reference has expired.
The EAServer runtime calls the component’s deactivate() method to indicate deactivation.
You can define your component so that instances are recycled after deactivation, as described in “Support for instance pooling”.
Destruction – The EAServer runtime calls destroy() to indicate that references to the class instance are being released. The instance is deallocated at a later time by the Java garbage collector thread.
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:
In EAServer Manager, you can configure your component so instances are always pooled by selecting the Pooling option on the Instances tab in the Component Properties window.
Alternatively, you can implement the ServerBean.canReuse() method
to specify at runtime whether an instance can be pooled. If canReuse() returns true,
the instance is pooled. Otherwise, the instance is destroyed.
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.
Indicate that this component instance has been activated.
Package |
|
Interface |
public abstract void activate (InstanceContext ctx, String instanceKey) throws EnterpriseBeanException;
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.
Not used.
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.
Specify whether this component instance is eligible for reuse.
Package |
|
Interface |
public abstract boolean canReuse()
true or false to
indicate whether the component instance is eligible to be recycled.
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.
activate(InstanceContext, String), deactivate(), destroy()
Indicates that this component instance has been deactivated.
Package |
|
Interface |
public abstract void deactivate() throws EnterpriseBeanException;
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.
Note
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.
activate(InstanceContext, String), canReuse(), destroy()
Indicates that this component instance is being released and will not be activated again.
Package |
|
Interface |
public abstract void destroy();
destroy should release any resources that were allocated by the component’s constructor.
