com.ibm.websphere.startupservice (IBM WebSphere Application Server, Release 8.5)

Interface Summary
Interface	Description
AppStartUp	Startup beans must use this interface for their remote interfaces.
AppStartUpHome	Any startup beans must use this interface in their J2EE descriptors.
ModStartUp	Startup beans who's start() methods are to be invoked at module start time must use this interface for their remote interfaces.
ModStartUpHome	Any startup beans who's start() methods are to be invoked at module start time must use this interface in their J2EE descriptors.

Package com.ibm.websphere.startupservice Description

Provides applications a means to invoke business logic when an application or module is started or stopped.

Required jars

Applications that use these APIs must have was_public.jar on their compilation classpath. This is located in the dev directory of a WebSphere Application Server installation.

Startup beans

There are two types of Startup beans, Application Startup beans and Module Startup beans. Both types of startup beans can be either a stateless or stateful session bean.

Application Startup beans enable the invocation of business logic during the starting and stopping of applications (EAR files). These beans must use com.ibm.websphere.startupservice.AppStartUpHome as their home interface and com.ibm.websphere.startupservice.AppStartUp as their remote interface. The user may not extend these interfaces.

Module Startup beans enable the invocation of business logic during the starting and stopping of modules (JAR files). These beans must use com.ibm.websphere.startupservice.ModStartUpHome as their home interface and com.ibm.websphere.startupservice.ModStartUp as their remote interface. The user may not extend these interfaces.

The remote interfaces for both types of startup beans have two methods, start() and stop(). Both methods can utilize any TX_ attribute except for TX_MANDATORY. It is also acceptable if the bean uses bean managed transactions.

An ejb jar in an EAR may contain zero or more of these startup beans of either type. When an application is started, WebSphere will find any session beans that specify the startup bean home and remote interfaces. As each module(JAR) within the application is started, the start() methods on the Module Startup beans associated with this module will be invoked. When the entire application(EAR) has started, the start() methods for each Application Startup bean will be invoked. Each start() method returns a boolean. If the method returns true then the application will continue startup processing normally. If it returns false then the application startup will be aborted. If the start() method throws any exception, then the application start process fails also.

When the application is stopped the stop() methods on all the Module and Application Startup beans will be invoked. This happens the reverse order from the order in which the start() methods were invoked. If the JVM stops suddenly then the stop methods will not be invoked. Any exceptions thrown by a stop method are ignored.

Influencing the execution order of startup beans within an ejb-jar

EJBs can have one or more properties associated with them. These properties are normally accessing using JNDI from the java:comp/env/xxx space. The integer property named "wasStartupPriority" can be used to specify a priority. If a bean does not have this property then it defaults to 0 for that bean.

The beans are started in numerically ascending order and are stopped in numerically descending order. This order is applies only within the scope of a single module (JAR). Also, Module and Application Startup beans are handled separately so the order or each type is independant of the other. Modules start prior to Applications and therefore all Module Startup beans will be executed prior to the Application Startup beans. Consider the following example:

Application TestApp has 2 EJB JAR files (Ajar, Bjar).
Ajar has one Application Startup bean (appStartA(with wasStartupPriority= 1))
Ajar also has 2 Module Startup beans (modStartA1(with wasStartupPriority= 1) and modStartA2(with wasStartupPriority=2))
Bjar has one Application Startup bean (appStartB(with wasStartupPriority = 1)
Bjar also has 2 Module Startup Beans (modStartB1(with wasStartupPriority = 1) and modStartB2(with wasStartupPriority = 2))
Module Ajar has been weighted such that it will start first.
When TestApp is started the start() methods will be invoked in the following order: modStartA1, modStartA2, modStartB1, appStartA, appStartB.
When TestApp is stopped the stop() methods will be invoked n the following order: appStartB, appStartA, modStartB1, modStartA2, modStartA1.

Using startup beans in a clustered application in a distributed environment.

If a startup bean is present in a clustered application, the start and stop methods are called whenever a cluster member starts or stops. For example, if App A has a startup bean and is deployed to a cluster of four machines numbered 1 through 4. The following events may occur:

Event	What happens
Cluster member on machine #1 starts	The startup bean start() methods are executed on machine #1.
Cluster member on machine #2 starts	The startup bean start() methods are executed on machine #2.
Cluster member on machine #3 starts	The startup bean start() methods are executed on machine #3.
Cluster member on machine #1 stops	The startup bean stop() methods are executed on machine #1.
Cluster member on machine #1 restarts	The startup bean start() methods are executed on machine #1.
Cluster member on machine #4 starts	The startup bean start() methods are executed on machine #4.

Therefore, 'start' and 'stop' are actions that occur for each cluster member. Start and stop methods can be called while a clustered application is already running.

If a clustered application needs to execute startup code ONE time before the first cluster member starts then it is best to execute a script that invokes a session bean that contains the start/stop logic. Execute this script prior to starting the clustered application. Likewise, before you stop the clustered application then run another script to execute the application stop code and then shutdown the application. It may be necessary to factor the application into two pieces;

a non-clustered 'start/stop' application and
a clustered 'running code' application.

This would allow the 'running code' application to be stopped and then the script can invoke code in the 'start/stop' application. Likewise, at startup then start the 'start/stop' application first, run the script then start the 'running code' application.

Security

If security is on then the start and stop methods must run as a role.

Best practices

The start method should execute quickly. These methods must complete in order for the application to start successfully. This means that if a start method takes a long time to execute then the application won't start quickly. It will delay the application becoming available. A start method that needs to do expensive processing should use a WorkManager and a Work to spin off the work to another thread so that the application can start in parallel with the expensive operation.

Version:: 1.1.0