There are two types of startup beans: application startup
beans and Module startup beans.
About this task
Deprecated feature: The capabilities
provided with startup singleton session beans (EJB 3.1 specification)
causes the WebSphere Application Server proprietary startup beans
function to be deprecated.
depfeat
A module startup
bean is a session bean that is loaded when an EJB Jar file starts.
Module startup beans enable Java Platform
Enterprise Edition (Java EE) applications to run business logic automatically,
whenever an EJB module starts or stops normally. An application startup
bean is a session bean that is loaded when an application starts.
Application startup beans enable Java EE
applications to run business logic automatically, whenever an application
starts or stops normally.
Startup beans are especially useful
when used with asynchronous bean features. For example, a startup
bean might create an alarm object that uses the Java Message
Service (JMS) to periodically publish heartbeat messages on a well-known
topic. This enables clients or other server applications to determine
whether the application is available. Refer to the Enabling an application
to wait for a messaging engine to start article if you are using the
default JMS provider.
- For Application startup beans, use the home interface,
com.ibm.websphere.startupservice.AppStartUpHome, to designate a bean
as an Application startup bean. For Module startup beans, use the
home interface, com.ibm.websphere.startupservice.ModStartUpHome, to
designate a bean as a Module startup bean.
- For Application startup beans, use the remote interface,
com.ibm.websphere.startupservice.AppStartUp, to define start() and
stop() methods on the bean. For Module startup beans, use the remote
interface, com.ibm.websphere.startupservice.ModStartUp, to define
start() and stop() methods on the bean.
The startup
bean start() method is called when the module or application starts
and contains business logic to be run at module or application start
time.
The start() method returns a boolean value. True indicates
that the business logic within the start() method ran successfully.
Conversely, False indicates that the business logic within
the start() method failed to run completely. A return value of False
also indicates to the Application server that application startup
is aborted.
The startup bean stop() methods are called when
the module or application stops and contains business logic to be
run at module or application stop time. Any exception thrown by a
stop() method is logged only. No other action is taken.
The
start() and stop() methods must never use the TX_MANDATORY transaction
attribute. A global transaction does not exist on the thread when
the start() or stop() methods are invoked. Any other TX_* attribute
can be used. If TX_MANDATORY is used, an exception is logged, and
the application start is aborted.
The start() and stop() methods
on the remote interface use Run-As mode. Run-As mode
specifies the credential information to be used by the security service
to determine the permissions that a principal has on various resources.
If security is on, the Run-As mode needs to be defined on all
of the methods called. The identity of the bean without this setting
is undefined.
There are no restrictions on what code the start()
and stop() methods can run, since the full Application Server programming
model is available to these methods.
- Use an optional environment property integer, wasStartupPriority,
to specify the start order of multiple startup beans in the same Java Archive (JAR) file. If the
environment property is found and is the wrong type, application startup
is aborted. If no priority value is specified, a default priority
of 0 is used. It is recommended that you specify the priority
property. Beans that have specified a priority are sorted using this
property. Beans with numerically lower priorities are run first. Beans
that have the same priority are run in an undefined order. All priorities
must be positive integers. Beans are stopped in the opposite order
to their start priority. The priority values for module startup beans
and application startup beans are mutually exclusive. All modules
will be started prior to the application being declared as "started"
and therefore the start() methods for module startup beans within
an application will be invoked prior to the start() methods for any
application startup beans. Likewise, all application startup bean
stop() methods for a specific Java Archive
(JAR) file will be invoked prior to any module startup bean stop()
methods for that JAR.
Note: The
wasStartupPriority environment
property integer cannot be set through either a command or the administrative
console. This environment property integer is an EJB environment entry
that is to be set by an application developer not an administrator.
You set the integer value in the
ejb-jar.xml file
as shown in the example below:
<env-entry>
<env-entry-name>wasStartupPriority</env-entry-name>
<env-entry-type>java.lang.Integer</env-entry-type>
<env-entry-value>3</env-entry-value>
</env-entry>
As with any other EJB environment entry,
you set a separate
wasStartupPriority value for each EJB.
- For module startup beans, the order in which EJB modules
are started can be adjusted via the "Starting weight" value associated
with each module
- To control who can invoke startup bean methods via WebSphere® Security do the following:
- Define the method permissions for the Start() and Stop()
methods as you would for any EJB module. (See "Defining method permissions
for EJB modules".)
- Ensure that the user that is mapped to the Security
Role defined for the startup bean methods is the same user that is
defined as the Server user ID within the User Registry.