Appendix A Jaguar 1.1 Java Classes and Interfaces
package com.sybase.jaguar.beans.enterprise;
public interface ServerBean
Interface for Java components in Jaguar, with methods that support transactional behavior and reuse of component instances.
None required. If a component's implementation class provides a default constructor, the Jaguar runtime server calls the default constructor when creating a new component instance.
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 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 figure below illustrates the states and state transitions in the lifecycle of a Java component that implements ServerBean.
The state transitions are as follows:
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:
true
,
the instance is pooled. Otherwise, the instance is destroyed.
If the component's Pooling option is enabled in Jaguar Manager, Jaguar 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.
ndicate that this component instance has been activated.
Package |
|
Interface |
public abstract void activate
(InstanceContext ctx, String instanceKey)
throws EnterpriseBeanException;
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.
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 Jaguar 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 Jaguar
Manager, Jaguar calls the component's canReuse method
after deactivating each instance to determine whether the instance
can be reused. If canReuse returns false
, Jaguar
destroys the instance. If the Pooling option is set, Jaguar never
calls the canReuse method. For more information
on component properties, see "Defining Packages and Components" in
the Jaguar CTS Programmer's Guide.
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 Jaguar 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 Jaguar 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.
activate(InstanceContext, String), deactivate(), canReuse()
| Copyright © 2000 Sybase, Inc. All rights reserved. |
| |