org.jboss.as.controller

Interface OperationContext

All Superinterfaces:

ExpressionResolver

public interface OperationContext
extends ExpressionResolver

The context for an operation step execution.

Author:

David M. Lloyd

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	OperationContext.AttachmentKey<T> An attachment key instance.
static class	OperationContext.ExecutionStatus The current activity of an operation.
static class	OperationContext.ResultAction The result action.
static interface	OperationContext.ResultHandler Handler for a callback to an OperationStepHandler indicating that the result of the overall operation is known and the handler can take any necessary actions to deal with that result.
static interface	OperationContext.RollbackHandler Handler for a callback to an OperationStepHandler indicating that the overall operation is being rolled back and the handler should revert any change it has made.
static class	OperationContext.Stage The stage at which a step should apply.

Field Summary

Fields inherited from interface org.jboss.as.controller.ExpressionResolver

EXPRESSION_PATTERN, REJECTING, SIMPLE, SIMPLE_LENIENT, TEST_RESOLVER

Method Summary

Modifier and Type	Method and Description
void	acquireControllerLock() Acquire the controlling ModelController's exclusive lock.
void	addModelStep(org.jboss.dmr.ModelNode response, org.jboss.dmr.ModelNode operation, OperationDefinition stepDefinition, OperationStepHandler stepHandler, boolean addFirst) Add a OperationContext.Stage.MODEL execution step to this operation process, including descriptive information for the operation.
void	addModelStep(OperationDefinition stepDefinition, OperationStepHandler stepHandler, boolean addFirst) Add a OperationContext.Stage.MODEL execution step to this operation process, including descriptive information for the operation.
void	addResource(PathAddress address, int index, Resource toAdd) Add a new resource, at to the executed operation address.
void	addResource(PathAddress address, Resource toAdd) Add a new resource, at the executed operation address.
void	addResponseWarning(Level level, org.jboss.dmr.ModelNode warning) See addResponseWarning(Level, String)
void	addResponseWarning(Level level, String warning) Add a warning to response.
void	addStep(org.jboss.dmr.ModelNode response, org.jboss.dmr.ModelNode operation, OperationStepHandler step, OperationContext.Stage stage) Add an execution step to this operation process.
void	addStep(org.jboss.dmr.ModelNode response, org.jboss.dmr.ModelNode operation, OperationStepHandler step, OperationContext.Stage stage, boolean addFirst) Add an execution step to this operation process.
void	addStep(org.jboss.dmr.ModelNode operation, OperationStepHandler step, OperationContext.Stage stage) Add an execution step to this operation process, writing any output to the response object associated with the current step.
void	addStep(org.jboss.dmr.ModelNode operation, OperationStepHandler step, OperationContext.Stage stage, boolean addFirst) Add an execution step to this operation process, writing any output to the response object associated with the current step.
void	addStep(OperationStepHandler step, OperationContext.Stage stage) Add an execution step to this operation process.
void	addStep(OperationStepHandler step, OperationContext.Stage stage, boolean addFirst) Add an execution step to this operation process.
<T> T	attach(OperationContext.AttachmentKey<T> key, T value) Attaches an arbitrary object to this context.
<T> T	attachIfAbsent(OperationContext.AttachmentKey<T> key, T value) Attaches an arbitrary object to this context only if the object was not already attached.
String	attachResultStream(String mimeType, InputStream stream) Attach a stream to be included as part of the response.
void	attachResultStream(String uuid, String mimeType, InputStream stream) Attach a stream to be included as part of the response, with a predetermined UUID.
AuthorizationResult	authorize(org.jboss.dmr.ModelNode operation) Check for authorization of the given operation.
AuthorizationResult	authorize(org.jboss.dmr.ModelNode operation, Set<Action.ActionEffect> effects) Check for authorization of the given effects for the given operation.
AuthorizationResult	authorize(org.jboss.dmr.ModelNode operation, String attribute, org.jboss.dmr.ModelNode currentValue) Check for authorization to read or modify an attribute, checking all effects of the given operation
AuthorizationResult	authorize(org.jboss.dmr.ModelNode operation, String attribute, org.jboss.dmr.ModelNode currentValue, Set<Action.ActionEffect> effects) Check for authorization to read or modify an attribute, limiting the check to the given effects of the operation
AuthorizationResult	authorizeOperation(org.jboss.dmr.ModelNode operation) Check for authorization to execute an operation.
ResourceAuthorization	authorizeResource(boolean attributes, boolean isDefaultResource) Check for authorization for the resource associated with the currently executing operation step and, optionally, its individual attributes
void	completeStep(OperationContext.ResultHandler resultHandler) Complete a step, while registering for a notification when the overall result of the operation is known.
void	completeStep(OperationContext.RollbackHandler rollbackHandler) Complete a step, while registering for a notification if the work done by the caller needs to be rolled back}.
Resource	createResource(PathAddress address) Create a new resource, relative to the executed operation address.
void	deregisterCapability(String capabilityName) Record that a previously registered capability will no longer be available.
void	deregisterCapabilityRequirement(String required, String dependent) Record that a previously registered requirement for a capability will no longer exist.
void	deregisterCapabilityRequirement(String required, String dependent, String attribute) Record that a previously registered requirement for a capability will no longer exist.
<T> T	detach(OperationContext.AttachmentKey<T> key) Detaches or removes the value from this context.
void	emit(Notification notification) Emit a Notification.
<T> T	getAttachment(OperationContext.AttachmentKey<T> key) Retrieves an object that has been attached to this context.
InputStream	getAttachmentStream(int index) Get a stream which is attached to the request.
int	getAttachmentStreamCount() Gets the number of streams attached to the request.
Environment	getCallEnvironment() Gets the caller environment for the current request.
Caller	getCaller() Deprecated. Use getSecurityIdentity() instead.
<T> T	getCapabilityRuntimeAPI(String capabilityName, Class<T> apiType) Gets the runtime API associated with a given capability, if there is one.
<T> T	getCapabilityRuntimeAPI(String capabilityBaseName, String dynamicPart, Class<T> apiType) Gets the runtime API associated with a given dynamically named capability, if there is one.
org.jboss.msc.service.ServiceName	getCapabilityServiceName(String capabilityName, Class<?> serviceType) Gets the name of a service associated with a given capability, if there is one.
org.jboss.msc.service.ServiceName	getCapabilityServiceName(String capabilityBaseName, Class<?> serviceType, String... dynamicParts) Gets the name of a service associated with a given dynamically named capability, if there is one.
org.jboss.msc.service.ServiceName	getCapabilityServiceName(String capabilityBaseName, String dynamicPart, Class<?> serviceType) Gets the name of a service associated with a given dynamically named capability, if there is one.
CapabilityServiceSupport	getCapabilityServiceSupport() Gets a support object that allows service implementations installed from this context to integrate with capabilities.
CapabilityServiceTarget	getCapabilityServiceTarget() Get the service target.
PathAddress	getCurrentAddress() Gets the address associated with the currently executing step.
String	getCurrentAddressValue() Gets the value of the current address' last element.
OperationContext.Stage	getCurrentStage() Get the current stage of execution.
org.jboss.dmr.ModelNode	getFailureDescription() Get the failure description response node, creating it if necessary.
Resource	getOriginalRootResource() Get a read-only reference of the entire management model BEFORE any changes were made by this context.
ProcessType	getProcessType() Get the type of process in which this operation is executing.
ImmutableManagementResourceRegistration	getResourceRegistration() Get a read only view of the managed resource registration.
ManagementResourceRegistration	getResourceRegistrationForUpdate() Get a mutable view of the managed resource registration.
org.jboss.dmr.ModelNode	getResponseHeaders() Get the response-headers response node, creating it if necessary.
org.jboss.dmr.ModelNode	getResult() Get the node into which the operation result should be written.
ImmutableManagementResourceRegistration	getRootResourceRegistration() Get a read only view of the root managed resource registration.
RunningMode	getRunningMode() Gets the running mode of the process.
org.wildfly.security.auth.server.SecurityIdentity	getSecurityIdentity() Obtain the SecurityIdentity for the current request.
org.jboss.dmr.ModelNode	getServerResults() Get the node into which the details of server results in a multi-server managed domain operation should be written.
org.jboss.msc.service.ServiceRegistry	getServiceRegistry(boolean modify) Get the service registry.
org.jboss.msc.service.ServiceTarget	getServiceTarget() Get the service target.
boolean	hasFailureDescription() Returns whether getFailureDescription() has been invoked.
boolean	hasOptionalCapability(String requested, String dependent, String attribute) Checks whether one of a capability's optional and runtime-only requirements is present.
boolean	hasResult() Returns whether getResult() has been invoked.
boolean	isBooting() Determine whether the controller is currently performing boot tasks.
boolean	isDefaultRequiresRuntime() Whether normally this operation would require a runtime step.
boolean	isModelAffected() Determine whether the model has thus far been affected by this operation.
boolean	isNormalServer() Convenience method to check if the process type is a server type and the running mode is RunningMode.NORMAL.
boolean	isResourceRegistryAffected() Determine whether the management resource registry has thus far been affected by this operation.
boolean	isResourceServiceRestartAllowed() Gets whether OperationContext.Stage.RUNTIME handlers can restart (or remove) runtime services in order to make the operation take effect.
boolean	isRollbackOnly() Determine whether the current operation is bound to be rolled back.
boolean	isRollbackOnRuntimeFailure() Gets whether any changes made by the operation should be rolled back if an error is introduced by a OperationContext.Stage.RUNTIME or OperationContext.Stage.VERIFY handler.
boolean	isRuntimeAffected() Determine whether the runtime container has thus far been affected by this operation.
boolean	markResourceRestarted(PathAddress resource, Object owner) Marks a resource to indicate that it's backing service(s) will be restarted.
Resource	readResource(PathAddress relativeAddress) Get the resource for read only operations, relative to the executed operation address.
Resource	readResource(PathAddress relativeAddress, boolean recursive) Get the resource for read only operations, relative to the executed operation address.
Resource	readResourceForUpdate(PathAddress relativeAddress) Get an addressable resource for update operations.
Resource	readResourceFromRoot(PathAddress address) Read an addressable resource from the root of the model.
Resource	readResourceFromRoot(PathAddress address, boolean recursive) Read an addressable resource from the root of the model.
void	registerAdditionalCapabilityRequirement(String required, String dependent, String attribute) Registers an additional hard requirement a capability has beyond what it was aware of when capability was passed to registerCapability(org.jboss.as.controller.capability.RuntimeCapability).
void	registerCapability(RuntimeCapability capability) Registers a capability with the system.
void	reloadRequired() Notify the context that the process requires a stop and re-start of its root service (but not a full process restart) in order to ensure stable operation and/or to bring its running state in line with its persistent configuration.
Resource	removeResource(PathAddress relativeAddress) Remove a resource relative to the executed operation address.
void	removeService(org.jboss.msc.service.ServiceController<?> controller) Initiate a service removal.
org.jboss.msc.service.ServiceController<?>	removeService(org.jboss.msc.service.ServiceName name) Initiate a service removal.
void	report(MessageSeverity severity, String message) Send a message to the client.
void	requireOptionalCapability(String required, String dependent, String attribute) Requests that one of a capability's optional requirements hereafter be treated as required, until the process is stopped or reloaded.
org.jboss.dmr.ModelNode	resolveExpressions(org.jboss.dmr.ModelNode node) Resolves any expressions in the passed in ModelNode.
void	restartRequired() Notify the context that the process must be terminated and replaced with a new process in order to ensure stable operation and/or to bring the running state in line with the persistent configuration.
void	revertReloadRequired() Notify the context that a previous call to reloadRequired() can be ignored (typically because the change that led to the need for reload has been rolled back.)
boolean	revertResourceRestarted(PathAddress resource, Object owner) Removes the restarted marking on the specified resource, provided the passed owner is the one originally used to obtain the mark.
void	revertRestartRequired() Notify the context that a previous call to restartRequired() can be ignored (typically because the change that led to the need for restart has been rolled back.)
void	runtimeUpdateSkipped() Notify the context that an update to the runtime that would normally have been made could not be made due to the current state of the process.
void	setRollbackOnly() Indicate that the operation should be rolled back, regardless of outcome.
void	stepCompleted() Deprecated. invoking this method is unnecessary since if an OperationStepHandler does not call one of the variants from its execute method, a no-op ResultHandler will automatically be registered

Method Detail

addStep

void addStep(OperationStepHandler step,
             OperationContext.Stage stage)
      throws IllegalArgumentException

Add an execution step to this operation process. Runtime operation steps are automatically added after configuration operation steps. Since only one operation may perform runtime work at a time, this method may block until other runtime operations have completed.

Parameters:

step - the step to add

stage - the stage at which the operation applies

Throws:

IllegalArgumentException - if the step handler is not valid for this controller type

addStep

void addStep(OperationStepHandler step,
             OperationContext.Stage stage,
             boolean addFirst)
      throws IllegalArgumentException

Add an execution step to this operation process. Runtime operation steps are automatically added after configuration operation steps. Since only one operation may perform runtime work at a time, this method may block until other runtime operations have completed.

Parameters:

step - the step to add

stage - the stage at which the operation applies

addFirst - add the handler before the others

Throws:

IllegalArgumentException - if the step handler is not valid for this controller type

addStep

void addStep(org.jboss.dmr.ModelNode operation,
             OperationStepHandler step,
             OperationContext.Stage stage)
      throws IllegalArgumentException

Add an execution step to this operation process, writing any output to the response object associated with the current step. Runtime operation steps are automatically added after configuration operation steps. Since only one operation may perform runtime work at a time, this method may block until other runtime operations have completed.

Parameters:

operation - the operation body to pass into the added step

step - the step to add

stage - the stage at which the operation applies

Throws:

IllegalArgumentException - if the step handler is not valid for this controller type

addStep

void addStep(org.jboss.dmr.ModelNode operation,
             OperationStepHandler step,
             OperationContext.Stage stage,
             boolean addFirst)
      throws IllegalArgumentException

Add an execution step to this operation process, writing any output to the response object associated with the current step. Runtime operation steps are automatically added after configuration operation steps. Since only one operation may perform runtime work at a time, this method may block until other runtime operations have completed.

Parameters:

operation - the operation body to pass into the added step

step - the step to add

stage - the stage at which the operation applies

addFirst - add the handler before the others

Throws:

IllegalArgumentException - if the step handler is not valid for this controller type

addStep

void addStep(org.jboss.dmr.ModelNode response,
             org.jboss.dmr.ModelNode operation,
             OperationStepHandler step,
             OperationContext.Stage stage)
      throws IllegalArgumentException

Add an execution step to this operation process. Runtime operation steps are automatically added after configuration operation steps. Since only one operation may perform runtime work at a time, this method may block until other runtime operations have completed.

Parameters:

response - the response which the nested step should populate

operation - the operation body to pass into the added step

step - the step to add

stage - the stage at which the operation applies

Throws:

IllegalArgumentException - if the step handler is not valid for this controller type

addStep

void addStep(org.jboss.dmr.ModelNode response,
             org.jboss.dmr.ModelNode operation,
             OperationStepHandler step,
             OperationContext.Stage stage,
             boolean addFirst)
      throws IllegalArgumentException

Add an execution step to this operation process. Runtime operation steps are automatically added after configuration operation steps. Since only one operation may perform runtime work at a time, this method may block until other runtime operations have completed.

Parameters:

response - the response which the nested step should populate

operation - the operation body to pass into the added step

step - the step to add

stage - the stage at which the operation applies

addFirst - add the handler before the others

Throws:

IllegalArgumentException - if the step handler is not valid for this controller type

addModelStep

void addModelStep(OperationDefinition stepDefinition,
                  OperationStepHandler stepHandler,
                  boolean addFirst)
           throws IllegalArgumentException

Add a OperationContext.Stage.MODEL execution step to this operation process, including descriptive information for the operation.

This method is primarily intended for internal use.

Parameters:

stepDefinition - the definition of the step to add

stepHandler - the handler for the step

addFirst - add the handler before the others @throws IllegalArgumentException if the step handler is not valid for this controller type

Throws:

IllegalStateException - if the current stage is not OperationContext.Stage.MODEL

IllegalArgumentException

addModelStep

void addModelStep(org.jboss.dmr.ModelNode response,
                  org.jboss.dmr.ModelNode operation,
                  OperationDefinition stepDefinition,
                  OperationStepHandler stepHandler,
                  boolean addFirst)
           throws IllegalArgumentException

Add a OperationContext.Stage.MODEL execution step to this operation process, including descriptive information for the operation.

This method is primarily intended for use by a handler for the composite operation.

Parameters:

response - the response which the nested step should populate

operation - the operation body to pass into the added step

stepDefinition - the definition of the step to add

stepHandler - the handler for the step

addFirst - add the handler before the others @throws IllegalArgumentException if the step handler is not valid for this controller type

Throws:

IllegalStateException - if the current stage is not OperationContext.Stage.MODEL

IllegalArgumentException

addResponseWarning

void addResponseWarning(Level level,
                        String warning)

Add a warning to response. This method appends warning message in response headers. Warning should be issued to inform managing end of non catastrophic occurrence, which require administrative action

Parameters:

level - - level of warning. Used to filter warning based on level value, just like

warning - - i18n formatter message, it should contain ID, just like jboss.Logger output does.

addResponseWarning

void addResponseWarning(Level level,
                        org.jboss.dmr.ModelNode warning)

See addResponseWarning(Level, String)

Parameters:

warning - - pre-formatted warning messsage.

getAttachmentStream

InputStream getAttachmentStream(int index)

Get a stream which is attached to the request.

Parameters:

index - the index

Returns:

the input stream

getAttachmentStreamCount

int getAttachmentStreamCount()

Gets the number of streams attached to the request.

Returns:

the number of streams

getResult

org.jboss.dmr.ModelNode getResult()

Get the node into which the operation result should be written.

Returns:

the result node

hasResult

boolean hasResult()

Returns whether getResult() has been invoked.

Returns:

true if getResult() has been invoked

attachResultStream

String attachResultStream(String mimeType,
                          InputStream stream)

Attach a stream to be included as part of the response. The return value of this method should be used as the value of the result for the step that invokes this method. Callers can then use that value to find the stream in the response to this operation.

Parameters:

mimeType - the mime type of the stream. Cannot be null

stream - the stream. Cannot be null

Returns:

a uuid for the stream. Will not be null

Throws:

IllegalStateException - if isBooting() returns true.

attachResultStream

void attachResultStream(String uuid,
                        String mimeType,
                        InputStream stream)

Attach a stream to be included as part of the response, with a predetermined UUID.

This method is intended for use by core handlers related to managed domain operation as they propagate a stream throughout a domain. Ordinary handlers should use attachResultStream(String, java.io.InputStream).

Parameters:

mimeType - the mime type of the stream. Cannot be null

stream - the stream. Cannot be null

Throws:

IllegalStateException - if isBooting() returns true.

getFailureDescription

org.jboss.dmr.ModelNode getFailureDescription()

Get the failure description response node, creating it if necessary.

Returns:

the failure description

hasFailureDescription

boolean hasFailureDescription()

Returns whether getFailureDescription() has been invoked.

Returns:

true if getFailureDescription() has been invoked

getServerResults

org.jboss.dmr.ModelNode getServerResults()

Get the node into which the details of server results in a multi-server managed domain operation should be written.

Returns:

the server results node

Throws:

IllegalStateException - if this process is not a ProcessType.HOST_CONTROLLER

getResponseHeaders

org.jboss.dmr.ModelNode getResponseHeaders()

Get the response-headers response node, creating it if necessary. Ordinary operation step handlers should not use this API for manipulating the operation-requires-restart or process-state headers. Use reloadRequired() and restartRequired() for that. (Some core operation step handlers used for coordinating execution of operations across different processes in a managed domain may use this method to manipulate the operation-requires-restart or process-state headers, but that is an exception.)

Returns:

the response-headers node

completeStep

void completeStep(OperationContext.RollbackHandler rollbackHandler)

Complete a step, while registering for a notification if the work done by the caller needs to be rolled back}.

Parameters:

rollbackHandler - the handler for any rollback notification. Cannot be null.

completeStep

void completeStep(OperationContext.ResultHandler resultHandler)

Complete a step, while registering for a notification when the overall result of the operation is known. Handlers that register for notifications will receive the notifications in the reverse of the order in which their steps execute.

Parameters:

resultHandler - the handler for the result notification. Cannot be null.

stepCompleted

@Deprecated
void stepCompleted()

Deprecated. invoking this method is unnecessary since if an OperationStepHandler does not call one of the variants from its execute method, a no-op ResultHandler will automatically be registered

Called by an OperationStepHandler to indicate it has completed its handling of a step and is uninterested in the result of subsequent steps. This is a convenience method that is equivalent to a call to completeStep(OperationContext.ResultHandler.NO_OP_RESULT_HANDLER).

A common user of this method would be a OperationContext.Stage.MODEL handler. Typically such a handler would not need to take any further action in the case of a successful result for the overall operation. If the operation result is a rollback, the OperationContext itself will ensure any changes made to the model are discarded, again requiring no action on the part of the handler. So a OperationContext.Stage.MODEL handler typically can be uninterested in the result of the overall operation and can use this method.

getProcessType

ProcessType getProcessType()

Get the type of process in which this operation is executing.

Returns:

the process type. Will not be null

getRunningMode

RunningMode getRunningMode()

Gets the running mode of the process.

Returns:

the running mode. Will not be null

isBooting

boolean isBooting()

Determine whether the controller is currently performing boot tasks.

Returns:

whether the controller is currently booting

isNormalServer

boolean isNormalServer()

Convenience method to check if the process type is a server type and the running mode is RunningMode.NORMAL. The typical usage would be for handlers that are only meant to execute on a normally running server, not on a host controller or on a RunningMode.ADMIN_ONLY server.

Returns:

true if the process type is a server type and the running mode is RunningMode.NORMAL.

isRollbackOnly

boolean isRollbackOnly()

Determine whether the current operation is bound to be rolled back.

Returns:

true if the operation will be rolled back

setRollbackOnly

void setRollbackOnly()

Indicate that the operation should be rolled back, regardless of outcome.

isRollbackOnRuntimeFailure

boolean isRollbackOnRuntimeFailure()

Gets whether any changes made by the operation should be rolled back if an error is introduced by a OperationContext.Stage.RUNTIME or OperationContext.Stage.VERIFY handler.

Returns:

true if the operation should rollback if there is a runtime stage failure

isResourceServiceRestartAllowed

boolean isResourceServiceRestartAllowed()

Gets whether OperationContext.Stage.RUNTIME handlers can restart (or remove) runtime services in order to make the operation take effect. If false and the operation cannot be effected without restarting or removing services, the handler should invoke reloadRequired() or restartRequired().

Returns:

true if a service restart or removal is allowed

reloadRequired

void reloadRequired()

Notify the context that the process requires a stop and re-start of its root service (but not a full process restart) in order to ensure stable operation and/or to bring its running state in line with its persistent configuration.

See Also:

ControlledProcessState.State.RELOAD_REQUIRED

restartRequired

void restartRequired()

Notify the context that the process must be terminated and replaced with a new process in order to ensure stable operation and/or to bring the running state in line with the persistent configuration.

See Also:

ControlledProcessState.State.RESTART_REQUIRED

revertReloadRequired

void revertReloadRequired()

Notify the context that a previous call to reloadRequired() can be ignored (typically because the change that led to the need for reload has been rolled back.)

revertRestartRequired

void revertRestartRequired()

Notify the context that a previous call to restartRequired() can be ignored (typically because the change that led to the need for restart has been rolled back.)

runtimeUpdateSkipped

void runtimeUpdateSkipped()

Notify the context that an update to the runtime that would normally have been made could not be made due to the current state of the process. As an example, a step handler that can only update the runtime when isBooting() is true must invoke this method if it is executed when isBooting() is false.

getCurrentAddress

PathAddress getCurrentAddress()

Gets the address associated with the currently executing step.

Returns:

the address. Will not be null

getCurrentAddressValue

String getCurrentAddressValue()

Gets the value of the current address' last element.

Returns:

the last element value

Throws:

IllegalStateException - if getCurrentAddress() is the empty address

getResourceRegistration

ImmutableManagementResourceRegistration getResourceRegistration()

Get a read only view of the managed resource registration. The registration is relative to the operation address.

Returns:

the model node registration

getResourceRegistrationForUpdate

ManagementResourceRegistration getResourceRegistrationForUpdate()

Get a mutable view of the managed resource registration. The registration is relative to the operation address.

Returns:

the model node registration

getRootResourceRegistration

ImmutableManagementResourceRegistration getRootResourceRegistration()

Get a read only view of the root managed resource registration.

Returns:

the root resource registration

getServiceRegistry

org.jboss.msc.service.ServiceRegistry getServiceRegistry(boolean modify)
                                                  throws UnsupportedOperationException

Get the service registry. If the step is not a runtime operation handler step, an exception will be thrown. The returned registry must not be used to remove services, if an attempt is made to call ServiceController.setMode(REMOVE) on a ServiceController returned from this registry an IllegalStateException will be thrown. To remove a service call removeService(org.jboss.msc.service.ServiceName).

Note: It is very important that the modify parameter accurately reflect whether the caller intends to make any modifications to any object reachable, directly or indirectly, from the returned ServiceRegistry. This includes modifying any ServiceController, Service, Value or any object reachable from a value.

Parameters:

modify - true if the operation may be modifying any object reachable directly or indirectly from the returned ServiceRegistry, false otherwise

Returns:

the service registry

Throws:

UnsupportedOperationException - if the calling step is not a runtime operation step

removeService

org.jboss.msc.service.ServiceController<?> removeService(org.jboss.msc.service.ServiceName name)
                                                  throws UnsupportedOperationException

Initiate a service removal. If the step is not a runtime operation handler step, an exception will be thrown. Any subsequent step which attempts to add a service with the same name will block until the service removal completes. The returned controller may be used to attempt to cancel a removal in progress.

Parameters:

name - the service to remove

Returns:

the controller of the service to be removed if service of given name exists; null otherwise

Throws:

UnsupportedOperationException - if the calling step is not a runtime operation step

removeService

void removeService(org.jboss.msc.service.ServiceController<?> controller)
            throws UnsupportedOperationException

Initiate a service removal. If the step is not a runtime operation handler step, an exception will be thrown. Any subsequent step which attempts to add a service with the same name will block until the service removal completes.

Parameters:

controller - the service controller to remove

Throws:

UnsupportedOperationException - if the calling step is not a runtime operation step

getServiceTarget

org.jboss.msc.service.ServiceTarget getServiceTarget()
                                              throws UnsupportedOperationException

Get the service target. If the step is not a runtime operation handler step, an exception will be thrown. The returned service target is limited such that only the service add methods are supported. If a service added to this target was removed by a prior operation step, the install will wait until the removal completes.

Returns:

the service target

Throws:

UnsupportedOperationException - if the calling step is not a runtime operation step

getCapabilityServiceTarget

CapabilityServiceTarget getCapabilityServiceTarget()
                                            throws UnsupportedOperationException

Get the service target. If the step is not a runtime operation handler step, an exception will be thrown. The returned service target is limited such that only the service add methods are supported. If a service added to this target was removed by a prior operation step, the install will wait until the removal completes.

Returns:

the service target

Throws:

UnsupportedOperationException - if the calling step is not a runtime operation step

acquireControllerLock

void acquireControllerLock()

Acquire the controlling ModelController's exclusive lock. Holding this lock prevent other operations from mutating the model, the management resource registry or the runtime service registry until the lock is released. The lock is automatically released when the execute method of the handler that invoked this method returns.

This method should be little used. The model controller's exclusive lock is acquired automatically when any of the operations in this interface that imply mutating the model, management resource registry or service registry are invoked. The only use for this method are special situations where an exclusive lock is needed but none of those methods will be invoked.

createResource

Resource createResource(PathAddress address)
                 throws UnsupportedOperationException

Create a new resource, relative to the executed operation address. Since only one operation may write at a time, this operation may block until other writing operations have completed.

Parameters:

address - the (possibly empty) address where the resource should be created. Address is relative to the address of the operation being executed

Returns:

the created resource

Throws:

IllegalStateException - if a resource already exists at the given address

UnsupportedOperationException - if the calling operation is not a model operation

addResource

void addResource(PathAddress address,
                 Resource toAdd)

Add a new resource, at the executed operation address. Since only one operation may write at a time, this operation may block until other writing operations have completed.

Parameters:

address - the (possibly empty) address where the resource should be added. Address is relative to the address of the operation being executed

toAdd - the new resource

Throws:

IllegalStateException - if a resource already exists at the given address, or if the resource does not support ordered childred

UnsupportedOperationException - if the calling operation is not a model operation

addResource

void addResource(PathAddress address,
                 int index,
                 Resource toAdd)

Add a new resource, at to the executed operation address. Since only one operation may write at a time, this operation may block until other writing operations have completed.

Parameters:

address - the (possibly empty) address where the resource should be added. Address is relative to the address of the operation being executed

index - the index of the resource to be created in the parent resources children of this type

toAdd - the new resource

Throws:

IllegalStateException - if a resource already exists at the given address

UnsupportedOperationException - if the calling operation is not a model operation

readResource

Resource readResource(PathAddress relativeAddress)

Get the resource for read only operations, relative to the executed operation address. Reads never block. If a write action was previously performed, the value read will be from an uncommitted copy of the the management model.
Note: By default the returned resource is read-only copy of the entire sub-model. In case this is not required use readResource(PathAddress, boolean) instead.

Parameters:

relativeAddress - the (possibly empty) address where the resource should be added. The address is relative to the address of the operation being executed

Returns:

the resource

readResource

Resource readResource(PathAddress relativeAddress,
                      boolean recursive)

Get the resource for read only operations, relative to the executed operation address. Reads never block. If a write action was previously performed, the value read will be from an uncommitted copy of the the management model.

Parameters:

relativeAddress - the (possibly empty) address where the resource should be added. The address is relative to the address of the operation being executed

recursive - whether the model should be read recursively or not

Returns:

the resource

readResourceFromRoot

Resource readResourceFromRoot(PathAddress address)

Read an addressable resource from the root of the model. Reads never block. If a write action was previously performed, the value read will be from an uncommitted copy of the the management model.

Note: By default the returned resource is read-only copy of the entire sub-model. In case the entire sub-model is not required use readResourceFromRoot(PathAddress, boolean) instead.

Parameters:

address - the (possibly empty) address

Returns:

a read-only reference from the model

readResourceFromRoot

Resource readResourceFromRoot(PathAddress address,
                              boolean recursive)

Read an addressable resource from the root of the model. Reads never block. If a write action was previously performed, the value read will be from an uncommitted copy of the the management model.

Use the recursive parameter to avoid the expense of making read-only copies of large portions of the resource tree. If recursive is false, the returned resource will only have placeholder resources for immediate children. Those placeholder resources will return an empty model and will not themselves have any children. Their presence, however, allows the caller to see what immediate children exist under the target resource.

Parameters:

address - the (possibly empty) address

recursive - whether the model should be read recursively or not

Returns:

a read-only reference from the model

readResourceForUpdate

Resource readResourceForUpdate(PathAddress relativeAddress)

Get an addressable resource for update operations. Since only one operation may write at a time, this operation may block until other writing operations have completed.

Parameters:

relativeAddress - the (possibly empty) address where the resource should be added. The address is relative to the address of the operation being executed

Returns:

the resource

removeResource

Resource removeResource(PathAddress relativeAddress)
                 throws UnsupportedOperationException

Remove a resource relative to the executed operation address. Since only one operation may write at a time, this operation may block until other writing operations have completed.

Parameters:

relativeAddress - the (possibly empty) address where the resource should be removed. The address is relative to the address of the operation being executed

Returns:

the old value of the node

Throws:

UnsupportedOperationException - if the calling operation is not a model operation

getOriginalRootResource

Resource getOriginalRootResource()

Get a read-only reference of the entire management model BEFORE any changes were made by this context. The structure of the returned model may depend on the context type (domain vs. server).

Returns:

the read-only original resource

isModelAffected

boolean isModelAffected()

Determine whether the model has thus far been affected by this operation.

Returns:

true if the model was affected, false otherwise

isResourceRegistryAffected

boolean isResourceRegistryAffected()

Determine whether the management resource registry has thus far been affected by this operation.

Returns:

true if the management resource registry was affected, false otherwise

isRuntimeAffected

boolean isRuntimeAffected()

Determine whether the runtime container has thus far been affected by this operation.

Returns:

true if the container was affected, false otherwise

getCurrentStage

OperationContext.Stage getCurrentStage()

Get the current stage of execution.

Returns:

the current stage

report

void report(MessageSeverity severity,
            String message)

Send a message to the client. Valid only during this operation.

Parameters:

severity - the message severity

message - the message

markResourceRestarted

boolean markResourceRestarted(PathAddress resource,
                              Object owner)

Marks a resource to indicate that it's backing service(s) will be restarted. This is to ensure that a restart only occurs once, even if there are multiple updates. When true is returned the caller has "acquired" the mark and should proceed with the restart, when false, the caller should take no additional action. The passed owner is compared by instance when a call to revertReloadRequired(). This is to ensure that only the "owner" will be successful in reverting the mark.

Parameters:

resource - the resource that will be restarted

owner - the instance representing ownership of the mark

Returns:

true if the mark was required and the service should be restarted, false if no action should be taken.

revertResourceRestarted

boolean revertResourceRestarted(PathAddress resource,
                                Object owner)

Removes the restarted marking on the specified resource, provided the passed owner is the one originally used to obtain the mark. The purpose of this method is to facilitate rollback processing. Only the "owner" of the mark should be the one to revert the service to a previous state (once again restarting it).When true is returned, the caller must take the required corrective action by restarting the resource, when false is returned the caller should take no additional action. The passed owner is compared by instance to the one provided in markResourceRestarted(PathAddress, Object)

Parameters:

resource - the resource being reverted

owner - the owner of the mark for the resource

Returns:

true if the caller owns the mark and the service should be restored by restarting false if no action should be taken.

resolveExpressions

org.jboss.dmr.ModelNode resolveExpressions(org.jboss.dmr.ModelNode node)
                                    throws OperationFailedException

Resolves any expressions in the passed in ModelNode. Expressions may either represent system properties or vaulted date. For vaulted data the format is ${VAULT::vault_block::attribute_name::sharedKey}

Specified by:

resolveExpressions in interface ExpressionResolver

Parameters:

node - the ModelNode containing expressions.

Returns:

a copy of the node with expressions resolved

Throws:

OperationFailedException - if there is a value of type ModelType.EXPRESSION in the node tree and there is no system property or environment variable that matches the expression, or if a security manager exists and its checkPermission method doesn't allow access to the relevant system property or environment variable

getAttachment

<T> T getAttachment(OperationContext.AttachmentKey<T> key)

Retrieves an object that has been attached to this context.

Type Parameters:

T - the value type of the attachment.

Parameters:

key - the key to the attachment.

Returns:

the attachment if found otherwise null.

attach

<T> T attach(OperationContext.AttachmentKey<T> key,
             T value)

Attaches an arbitrary object to this context.

Type Parameters:

T - the value type of the attachment.

Parameters:

key - they attachment key used to ensure uniqueness and used for retrieval of the value.

value - the value to store.

Returns:

the previous value associated with the key or null if there was no previous value.

attachIfAbsent

<T> T attachIfAbsent(OperationContext.AttachmentKey<T> key,
                     T value)

Attaches an arbitrary object to this context only if the object was not already attached. If a value has already been attached with the key provided, the current value associated with the key is returned.

Type Parameters:

T - the value type of the attachment.

Parameters:

key - they attachment key used to ensure uniqueness and used for retrieval of the value.

value - the value to store.

Returns:

the previous value associated with the key or null if there was no previous value.

detach

<T> T detach(OperationContext.AttachmentKey<T> key)

Detaches or removes the value from this context.

Type Parameters:

T - the value type of the attachment.

Parameters:

key - the key to the attachment.

Returns:

the attachment if found otherwise null.

authorize

AuthorizationResult authorize(org.jboss.dmr.ModelNode operation)

Check for authorization of the given operation.

Parameters:

operation - the operation. Cannot be null

Returns:

the authorization result

authorize

AuthorizationResult authorize(org.jboss.dmr.ModelNode operation,
                              Set<Action.ActionEffect> effects)

Check for authorization of the given effects for the given operation.

Parameters:

operation - the operation. Cannot be null

effects - the relevant effects. If empty, all effects associated with the operation are tested.

Returns:

the authorization result

authorizeResource

ResourceAuthorization authorizeResource(boolean attributes,
                                        boolean isDefaultResource)

Check for authorization for the resource associated with the currently executing operation step and, optionally, its individual attributes

Parameters:

attributes - true if the result should include attribute authorizations

isDefaultResource - true if

Returns:

the resource authorization

authorize

AuthorizationResult authorize(org.jboss.dmr.ModelNode operation,
                              String attribute,
                              org.jboss.dmr.ModelNode currentValue)

Check for authorization to read or modify an attribute, checking all effects of the given operation

Parameters:

operation - the operation that will read or modify

attribute - the attribute name

currentValue - the current value of the attribute

Returns:

the authorization result

authorize

AuthorizationResult authorize(org.jboss.dmr.ModelNode operation,
                              String attribute,
                              org.jboss.dmr.ModelNode currentValue,
                              Set<Action.ActionEffect> effects)

Check for authorization to read or modify an attribute, limiting the check to the given effects of the operation

Parameters:

operation - the operation that will read or modify

attribute - the attribute name

currentValue - the current value of the attribute

effects - the effects to check, or, if empty, all effects

Returns:

the authorization result

authorizeOperation

AuthorizationResult authorizeOperation(org.jboss.dmr.ModelNode operation)

Check for authorization to execute an operation.

Parameters:

operation - the operation. Cannot be null

Returns:

the authorization result

getCaller

@Deprecated
Caller getCaller()

Deprecated. Use getSecurityIdentity() instead.

Obtain the Caller for the current request.

Returns:

The current caller.

getSecurityIdentity

org.wildfly.security.auth.server.SecurityIdentity getSecurityIdentity()

Obtain the SecurityIdentity for the current request.

Returns:

The current SecurityIdentity.

emit

void emit(Notification notification)

Emit a Notification.

Parameters:

notification - the notification to emit

getCallEnvironment

Environment getCallEnvironment()

Gets the caller environment for the current request.

Returns:

the call environment

registerCapability

void registerCapability(RuntimeCapability capability)

Registers a capability with the system. Any requirements associated with the capability will be recorded as requirements.

Parameters:

capability - the capability. Cannot be null

Throws:

IllegalStateException - if the current stage is not OperationContext.Stage.MODEL

registerAdditionalCapabilityRequirement

void registerAdditionalCapabilityRequirement(String required,
                                             String dependent,
                                             String attribute)

Registers an additional hard requirement a capability has beyond what it was aware of when capability was passed to registerCapability(org.jboss.as.controller.capability.RuntimeCapability). Used for cases where a capability optionally depends on another capability, and whether or not that requirement is needed is not known when the capability is first registered.

This method should be used in preference to requireOptionalCapability(String, String, String) when, based on its own configuration, the caller knows in OperationContext.Stage.MODEL that the optional capability is actually required in the current process.

Parameters:

required - the name of the required capability. Cannot be null

dependent - the name of the capability that requires the other capability. Cannot be null

attribute - the name of the attribute that triggered this requirement, or null if no single attribute was responsible

Throws:

IllegalStateException - if the current stage is not OperationContext.Stage.MODEL or if capability is not registered

hasOptionalCapability

boolean hasOptionalCapability(String requested,
                              String dependent,
                              String attribute)

Checks whether one of a capability's optional and runtime-only requirements is present. Only for use in cases where the dependent capability's persistent configuration does not mandate the presence of the requested capability, but the capability will use it at runtime if it is present.

This method should be used in preference to registerAdditionalCapabilityRequirement(String, String, String) when the caller's own configuration doesn't impose a hard requirement for the requested capability, but, if it is present it will be used. Once the caller declares an intent to use the capability by invoking this method and getting a true response, thereafter the system is aware that dependent is actually using requested, but will not prevent configuration changes that make requested unavailable.

Parameters:

requested - the name of the requested capability. Cannot be null

dependent - the name of the capability that requires the other capability. Cannot be null

attribute - the name of the attribute that triggered this requirement, or null if no single attribute was responsible

Returns:

true if the requested capability is present; false if not. If true, hereafter dependent's requirement for requested will not be treated as optional.

Throws:

IllegalStateException - if the current stage is OperationContext.Stage.MODEL. The complete set of capabilities is not known until the end of the model stage.

requireOptionalCapability

void requireOptionalCapability(String required,
                               String dependent,
                               String attribute)
                        throws OperationFailedException

Requests that one of a capability's optional requirements hereafter be treated as required, until the process is stopped or reloaded. This request will only be granted if the required capability is already present; otherwise an OperationFailedException will be thrown.

This method should be used in preference to registerAdditionalCapabilityRequirement(String, String, String) only if the caller is not sure whether the capability is required until OperationContext.Stage.RUNTIME. Not knowing whether a capability is required until stage RUNTIME is an anti-pattern, so use of this method is strongly discouraged. It only exists to avoid the need to break backward compatibility by removing support for expressions from certain attributes.

Parameters:

required - the name of the required capability. Cannot be null

dependent - the name of the capability that requires the other capability. Cannot be null

attribute - the name of the attribute that triggered this requirement, or null if no single attribute was responsible

Throws:

IllegalStateException - if the current stage is OperationContext.Stage.MODEL. The complete set of capabilities is not known until the end of the model stage.

OperationFailedException - if the requested capability is not available

deregisterCapabilityRequirement

void deregisterCapabilityRequirement(String required,
                                     String dependent)

Record that a previously registered requirement for a capability will no longer exist.

Semantics with "reload-required" and "restart-required": Deregistering a capability requirement does not obligate the caller to cease using a previously obtained reference to that capability's runtime API. But, if the caller will not cease using the capability, it must put the process in reload-required or restart-required state. This will reflect the fact that the model says the capability is not required, but in the runtime it still is.

Parameters:

required - the name of the no longer required capability

dependent - the name of the capability that no longer has the requirement

Throws:

IllegalStateException - if the current stage is not OperationContext.Stage.MODEL

deregisterCapabilityRequirement

void deregisterCapabilityRequirement(String required,
                                     String dependent,
                                     String attribute)

Record that a previously registered requirement for a capability will no longer exist.

Semantics with "reload-required" and "restart-required": Deregistering a capability requirement does not obligate the caller to cease using a previously obtained reference to that capability's runtime API. But, if the caller will not cease using the capability, it must put the process in reload-required or restart-required state. This will reflect the fact that the model says the capability is not required, but in the runtime it still is.

Parameters:

required - the name of the no longer required capability

dependent - the name of the capability that no longer has the requirement

attribute - the name of the attribute that references to the no longer required capability, or null if there is if no single attribute referring to the required capability.

Throws:

IllegalStateException - if the current stage is not OperationContext.Stage.MODEL

deregisterCapability

void deregisterCapability(String capabilityName)

Record that a previously registered capability will no longer be available. Invoking this operation will also automatically deregister any requirements that are associated with this capability, including optional ones.

Semantics with "reload-required" and "restart-required": Deregistering a capability does not eliminate the obligation to other capabilities that have previously depended upon it to support them by providing expected runtime services. It does require that those other capabilities also deregister their requirements as part of the same operation. Requiring that they do so ensures that the management model is consistent. However, those other capabilities may simply put the process in reload-required or restart-required state and then continue to use the existing services. So, an operation that invokes this method should also always put the process into reload-required or restart-required state. This will reflect the fact that the model says the capability is not present, but in the runtime it still is.

Parameters:

capabilityName - the name of the capability

Throws:

IllegalStateException - if the current stage is not OperationContext.Stage.MODEL

getCapabilityRuntimeAPI

<T> T getCapabilityRuntimeAPI(String capabilityName,
                              Class<T> apiType)

Gets the runtime API associated with a given capability, if there is one.

Type Parameters:

T - the java type that exposes the API

Parameters:

capabilityName - the name of the capability. Cannot be null

apiType - class of the java type that exposes the API. Cannot be null

Returns:

the runtime API. Will not return null

Throws:

IllegalStateException - if the current stage is OperationContext.Stage.MODEL. The complete set of capabilities is not known until the end of the model stage.

IllegalArgumentException - if the capability does not provide a runtime API

ClassCastException - if the runtime API exposed by the capability cannot be cast to type {code T}

getCapabilityRuntimeAPI

<T> T getCapabilityRuntimeAPI(String capabilityBaseName,
                              String dynamicPart,
                              Class<T> apiType)

Gets the runtime API associated with a given dynamically named capability, if there is one.

Type Parameters:

T - the java type that exposes the API

Parameters:

capabilityBaseName - the base name of the capability. Cannot be null

dynamicPart - the dynamic part of the capability name. Cannot be null

apiType - class of the java type that exposes the API. Cannot be null

Returns:

the runtime API. Will not return null

Throws:

IllegalStateException - if the current stage is OperationContext.Stage.MODEL. The complete set of capabilities is not known until the end of the model stage.

IllegalArgumentException - if the capability does not provide a runtime API

ClassCastException - if the runtime API exposed by the capability cannot be cast to type {code T}

getCapabilityServiceName

org.jboss.msc.service.ServiceName getCapabilityServiceName(String capabilityName,
                                                           Class<?> serviceType)

Gets the name of a service associated with a given capability, if there is one.

Parameters:

capabilityName - the name of the capability. Cannot be null

serviceType - class of the java type that exposes by the service. Cannot be null

Returns:

the name of the service. Will not return null

Throws:

IllegalStateException - if the current stage is OperationContext.Stage.MODEL. The complete set of capabilities is not known until the end of the model stage.

IllegalArgumentException - if serviceType is null or the capability does not provide a service of type serviceType

getCapabilityServiceName

org.jboss.msc.service.ServiceName getCapabilityServiceName(String capabilityBaseName,
                                                           String dynamicPart,
                                                           Class<?> serviceType)

Gets the name of a service associated with a given dynamically named capability, if there is one.

Parameters:

capabilityBaseName - the base name of the capability. Cannot be null

dynamicPart - the dynamic part of the capability name. Cannot be null

serviceType - class of the java type that exposes by the service. Cannot be null

Returns:

the name of the service. Will not return null

Throws:

IllegalStateException - if the current stage is OperationContext.Stage.MODEL. The complete set of capabilities is not known until the end of the model stage.

IllegalArgumentException - if serviceType is null or the capability does not provide a service of type serviceType

getCapabilityServiceName

org.jboss.msc.service.ServiceName getCapabilityServiceName(String capabilityBaseName,
                                                           Class<?> serviceType,
                                                           String... dynamicParts)

Gets the name of a service associated with a given dynamically named capability, if there is one.

Parameters:

capabilityBaseName - the base name of the capability. Cannot be null

serviceType - class of the java type that exposes by the service. Cannot be null

dynamicParts - the dynamic parts of the capability name. Cannot be null

Returns:

the name of the service. Will not return null

Throws:

IllegalStateException - if the current stage is OperationContext.Stage.MODEL. The complete set of capabilities is not known until the end of the model stage.

IllegalArgumentException - if serviceType is null or the capability does not provide a service of type serviceType

getCapabilityServiceSupport

CapabilityServiceSupport getCapabilityServiceSupport()

Gets a support object that allows service implementations installed from this context to integrate with capabilities.

Returns:

the support object. Will not return null * @throws java.lang.IllegalStateException if the current stage is OperationContext.Stage.MODEL. Service integration is not supported in the model stage.

isDefaultRequiresRuntime

boolean isDefaultRequiresRuntime()

Whether normally this operation would require a runtime step. It returns true in the following cases

• The process is a server, and it is running in NORMAL (i.e. not admin-only) mode.
• The process is a HC, and the address of the operation is a subsystem in the host model or a child thereof