weblogic.application

Interface Module

All Known Subinterfaces:

AppEnvSharingModule, ConcurrentModule, DeployableObjectInfo, ModuleLocationInfo

All Known Implementing Classes:

ModuleWrapper, weblogic.servlet.internal.WebAppModule, WseeWebappModule.VirtualWebApp

public interface Module

This interface must be implemented by various module types (EJB, webapp...). It is used by the application container to drive deployment of applications.

Excluded in public API Reference.

Method Summary

Modifier and Type	Method and Description
void	activate() activate is called on Modules in the PREPARED state to transition the application to a fully running state.
void	adminToProduction() adminToProduction is called on Modules in the ACTIVE state to switch access control from admin-only to full production-mode.
void	deactivate() deactivate is called on modules in the ACTIVATED state and returns them to the PREPARED state.
void	destroy(UpdateListener.Registration reg) destroy is called on modules in the INITIALIZED state and returns them to the NEW state.
void	forceProductionToAdmin() forceProductionToAdmin makes an immediate transition to admin mode, destroying any in-flight work or sessions.
ComponentRuntimeMBean[]	getComponentRuntimeMBeans() Returns the ComponentRuntimeMBeans for this module.
DescriptorBean[]	getDescriptors() Returns a java object representing any descriptor information that was contained in the module uri.
java.lang.String	getId() Returns the Module's id.
java.lang.String	getType() Returns the module type.
void	gracefulProductionToAdmin(AdminModeCompletionBarrier barrier) gracefulProductionToAdmin is called on Modules in the ACTIVE state to switch access-control to admin-only.
weblogic.utils.classloaders.GenericClassLoader	init(ApplicationContext appCtx, weblogic.utils.classloaders.GenericClassLoader parent, UpdateListener.Registration reg) init is the first callback received by the Module during a deployment.
void	initUsingLoader(ApplicationContext appCtx, weblogic.utils.classloaders.GenericClassLoader gcl, UpdateListener.Registration reg) initUsingLoader is the first callback received by the Module during a deployment.
void	prepare() prepare is called on Modules in the INITIALIZED state to start the deployment.
void	remove() remove is called when the Module is removed from the server's configuration.
void	start() start is called on Modules in the ACTIVATED state to perform any post-deployment initialization.
void	unprepare() unprepare is called on modules in the PREPARED state and returns them to the INITIALIZED state.

Method Detail

getId

java.lang.String getId()

Returns the Module's id. In EARs, the module's id is defined as the uri in the application.xml (for standard Java EE Modules), or the weblogic-application.xml/weblogic-extension.xml (for WL-specific modules.

The id returned by getId must be unique within the application. For WAR files, the file uri is not unique, so the context-root is returned instead.

getType

java.lang.String getType()

Returns the module type. The types are defined in WebLogicModuleType.

Returns:

getComponentRuntimeMBeans

ComponentRuntimeMBean[] getComponentRuntimeMBeans()

Returns the ComponentRuntimeMBeans for this module. A Module may have >= 0 ComponentRuntimeMBeans. If a Module has 0 ComponentRuntimeMBeans, it should return ComponentRuntimeMBean[0] rather than null

This method is used by the ApplicationRuntimeMBean to find all the ComponentRuntimeMBeans in an application

getDescriptors

DescriptorBean[] getDescriptors()

Returns a java object representing any descriptor information that was contained in the module uri. A zero length array is returned if no descriptors were found, a standard and or weblogic descriptor is returned otherwise.

init

weblogic.utils.classloaders.GenericClassLoader init(ApplicationContext appCtx,
                                                    weblogic.utils.classloaders.GenericClassLoader parent,
                                                    UpdateListener.Registration reg)
                                             throws ModuleException

init is the first callback received by the Module during a deployment. It is an opportunity for the Module to initialize any module-specific resources prior to the prepare request

init is responsible for establishing the application classloader hierarchy and dependencies. The Module is passed its parent classloader. Typically this will be the "application" classloader, but if custom classloader declarations were used, it could be an arbitrary classloader.

Module implementations which don't require additional classloaders or classfinders should just return the parent classloader unchanged.

Module implemenations which want to load in the default classloader (eg EJB) should just add classfinders to the parent and return it.

Module implemenations which want a subloader should create a new classloader with the supplied parent and then return the new classloader.

If the init callback fails (by throwing a ModuleException or unchecked exception), the module MUST perform any cleanup before exiting init. It DOES NOT receive any further callbacks.

After init completes successfully, the module is in the INITIALIZED state.

Parameters:

ApplicationContext - the Application Context

GenericClassLoader - the parent classloader

UpdateListener.Registration - opportunity for the module to register an UpdateListener using passed handle.

Returns:

Returns the ClassLoader used for this Module

Throws:

ModuleException - when init fails. The Deployment engine is responsible for logging this exception.

initUsingLoader

void initUsingLoader(ApplicationContext appCtx,
                     weblogic.utils.classloaders.GenericClassLoader gcl,
                     UpdateListener.Registration reg)
              throws ModuleException

initUsingLoader is the first callback received by the Module during a deployment. It is an opportunity for the Module to initialize any module-specific resources prior to the prepare request .

initUsingLoader (rather than init) is used when this module's classloader is declared in the classloader-structure in weblogic-application.xml. initUsingLoader indicates the Module must load its classes in the GenericClassLoader and cannot create a subloader.

If the initUsingLoader callback fails (by throwing a ModuleException or unchecked exception), the module MUST perform any cleanup before exiting initUsingLoader. It DOES NOT receive any further callbacks.

After initUsingLoader completes successfully, the module is in the INITIALIZED state.

Parameters:

ApplicationContext - the Application Context

GenericClassLoader - the classloader

UpdateListener.Registration - opportunity for the module to register an UpdateListener.

Throws:

ModuleException - when initUsingLoader fails. The Deployment engine is responsible for logging this exception.

prepare

void prepare()
      throws ModuleException

prepare is called on Modules in the INITIALIZED state to start the deployment. The Module should perform as much deployment as possible during prepare. Ideally only user-visible changes (such as binding into JNDI) should be delayed until activate.

If the prepare callback fails (by throwing a ModuleException or unchecked exception), the module MUST perform any cleanup before exiting prepare. It DOES NOT receive an unprepare callback.

After prepare completes successfully, the module is in the PREPARED state.

Throws:

ModuleException - when prepare fails. The Deployment engine is responsible for logging this exception.

activate

void activate()
       throws ModuleException

activate is called on Modules in the PREPARED state to transition the application to a fully running state. It is called after a successful prepare. Ideally activate should always succeed.

If the activate callback fails (by throwing a ModuleException or unchecked exception), the module returns to the PREPARED state and will then receive a unprepare callback

After activate completes successfully, the module is in the ACTIVATED state.

Throws:

ModuleException - when activate fails. The Deployment engine is responsible for logging this exception.

start

void start()
    throws ModuleException

start is called on Modules in the ACTIVATED state to perform any post-deployment initialization. It is equivalent to using a postStart ApplicationLifecycleListener.

If the start callback fails (by throwing a ModuleException or unchecked exception), the module remains in the ACTIVATED state and will then receive a deactivate callback

After start completes successfully, the module remains in the ACTIVATED state.

start callbacks should be used sparingly. If possible, deployments should fail during the prepare callback rather than detecting errors in activate or start.

Throws:

ModuleException - when start fails. The Deployment engine is responsible for logging this exception.

deactivate

void deactivate()
         throws ModuleException

deactivate is called on modules in the ACTIVATED state and returns them to the PREPARED state. It removes any user-visible portions of the application deployment.

If the deactivate callback fails (by throwing a ModuleException or unchecked exception), the module is FORCED to the PREPARED state and will then receive a unprepare callback.

After deactivate completes successfully, the module is in the PREPARED state.

Throws:

ModuleException - when deactivate fails. The Deployment engine is responsible for logging this exception.

unprepare

void unprepare()
        throws ModuleException

unprepare is called on modules in the PREPARED state and returns them to the INITIALIZED state. It removes the Module from the application.

If the unprepare callback fails (by throwing a ModuleException or unchecked exception), the module is FORCED to the INITIALIZED state and will then receive a destroy callback.

Throws:

ModuleException - when unprepare fails. The Deployment engine is responsible for logging this exception.

destroy

void destroy(UpdateListener.Registration reg)
      throws ModuleException

destroy is called on modules in the INITIALIZED state and returns them to the NEW state. destroy is a chance for the module to undo any side-effects of its init method.

If the destroy callback fails (by throwing a ModuleException or unchecked exception), the module is FORCED to the NEW state.

Parameters:

UpdateListener.Registration - If this Module registered an UpdateListener in init, it has to remove it here using this registration handle.

Throws:

ModuleException - when destroy fails. The Deployment engine is responsible for logging this exception.

remove

void remove()
     throws ModuleException

remove is called when the Module is removed from the server's configuration. The Module implementation generally uses this to remove any working directories or other persistent state associated with the Module.

If the remove callback fails (by throwing a ModuleException or unchecked exception), the module MUST perform any cleanup before exiting remove. It DOES NOT receive any further callbacks.

Throws:

ModuleException - when remove fails. The Deployment engine is responsible for logging this exception.

adminToProduction

void adminToProduction()

adminToProduction is called on Modules in the ACTIVE state to switch access control from admin-only to full production-mode. If modules are not distinguishing between admin and production modes, they can simply return without doing anything.

adminToProduction should NEVER fail. If an unchecked exception is thrown, the user should shutdown the application as it may be in an inconsistent state.

gracefulProductionToAdmin

void gracefulProductionToAdmin(AdminModeCompletionBarrier barrier)
                        throws ModuleException

gracefulProductionToAdmin is called on Modules in the ACTIVE state to switch access-control to admin-only. This call is asynchronous and the AdminModeCompletionBarrier is notified when the application has completed its transformation. If modules are not distinguishing between admin and production modes, they can simply return without doing anything.

Note, this callback might take a long time to complete. The default servlet session timeout is approximately 1 hour. The forceProductionToAdmin method can be used instead.

Throws:

ModuleException

forceProductionToAdmin

void forceProductionToAdmin()
                     throws ModuleException

forceProductionToAdmin makes an immediate transition to admin mode, destroying any in-flight work or sessions. If modules are not distinguishing between admin and production modes, they can simply return without doing anything.

Throws:

ModuleException