weblogic.server
Interface ServerService

All Superinterfaces:

ServerStates

@Contract
public interface ServerService
extends ServerStates

Server services that need to hook into the servers lifecycle implement this interface. The implementation classname is then added to the ServerServices. Please refer to the javadoc of ServerServices for more information on when start, stop and halt are called.

getName

String getName()

Get the name of the server service. This name is displayed externally in utilities like weblogic.version and also during server startup.

getVersion

String getVersion()

Get a comma separated list of specification versions that this server service implements. The version information is displayed to customers through weblogic.version and other utilities.

start

void start()
           throws ServiceFailureException

This method starts the service. The service is fully functioning and available to other services after this method returns. This is a blocking operation. The service should return only after it has started. It should throw ServiceFailureException if it is unable to complete the start operation.

This method can be called more than once but not concurrently. Here are the conditions under which start() can be called:

During server startup

After stop completes without exception

After halt completes without exception

After halt completes without exception even when a preceding stop threw an exception

Throws:

ServiceFailureException - service is unable to start due to an internal error condition. The service is not available if this exception is thrown. The service should cleanup its state before throwing this exception. No further callbacks will be issued after this exception is thrown.

stop

void stop()
          throws ServiceFailureException

This method gracefully shuts down the service completing inflight work and releasing resources. The method should block till the operation is complete. The service should fully stop before returning without relying on a subsequent halt() call. Here is a broad definition of inflight work:

"work associated with state that will be lost if this service becomes unavailable. Remote and/or local users are relying on this state to complete their work. The user can be another ServerService, a remote EJB client, browser request etc. If the state is replicated to another cluster node or is persistent and available to other nodes then work accessing such state is not treated as inflight work. Note that work would be treated as inflight till replication or persistence is complete."

There is always a danger that completing inflight work can take forever. The caller of this method is expected to handle that condition. For e.g. graceful shutdown provides a timeout after which force shutdown begins.

Services should handle a halt() call even when stop() is executing.

This method can be called more than once but not concurrently. Here are the conditions under which stop() can be called:

After start completes without exception and the service is running

.

While halt is in progress. stop should quit by throwing a ServiceFailureException

.

stop and halt called simultaneouly. Should allow halt to proceed. stop should quit by throwing a ServiceFailureException

.

After service is already shutdown due to a previous stop or halt. Should just return without exception

.

Throws:

ServiceFailureException - This exception is thrown to indicate that stop quit without completing inflight work. This could happen due to an internal error or if halt is already in progress. If stop fails due to internal error, the service should guarantee that a subsequent halt call will succeed.

halt

void halt()
          throws ServiceFailureException

This method shuts down the service by cancelling or rolling back inflight work. Inflight work is dropped if it cannot be cancelled. Resources held by the service are released. The method should block till the operation is complete. The service should guarantee a quick shutdown independent of the nature and the amount of inflight work it is handling. It is understood that there might be a small part of the shutdown time that is proportional to the amount of inflight work due to the increased cancellation time. Here are the guidelines for cancellation:

"Inflight work should be cancelled if possible and if the cancellation time is not dependent on user intervention or user configured timeout e.g. rollback of pending transactions. If cancellation cannot be done without user intervention or configuration (e.g. invalidation of servlet session in a non-clustered server) then it should be dropped. If the state is replicated to another cluster node or is persistent and available to other nodes then cancellation just means relinquishing control over that state and letting another cluster member takeover."

Services should handle a halt() call even when stop() is executing.

This method can be called more than once but not concurrently. Here are the conditions under which halt() can be called:

After start completes without exception

After stop throws ServiceFailureException

After stop completes successfully. This is a trivial case and halt should just return

While stop is still executing. stop should quit by throwing a ServiceFailureException and allow halt to proceed

While start is still executing. start should quit by throwing a ServiceFailureException and allow halt to proceed

stop and halt called simultaneouly. Should allow halt to proceed. stop should quit by throwing a ServiceFailureException

After service is already shutdown due to a previous stop or halt. Should just return without exception

.

Throws:

ServiceFailureException - service is unable to halt due to an internal error condition. The service becomes unavailable if this exception is thrown. halt() should throw this exception with an appropriate message only when it cannot complete shutdown and the next invocation of start() might fail because of this failure. Note that the next invocation of start() can happen after server restart. In all other cases, halt() should log a message and continue to completion.