org.jboss.as.controller

Interface ExtensionContext

public interface ExtensionContext

The context for registering a new extension.

Author:

David M. Lloyd, David Bosschaert, Brian Stansberry (c) 2011 Red Hat Inc.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	ExtensionContext.ContextType The various types of contexts in which an Extension can be asked to initialize.

Method Summary

Modifier and Type	Method and Description
PathManager	getPathManager() Gets the process' PathManager if the process is a server; throws an IllegalStateException if not.
ProcessType	getProcessType() Gets the type of the current process.
RunningMode	getRunningMode() Gets the current running mode of the process.
ExtensionContext.ContextType	getType() Gets the type of this context.
boolean	isRegisterTransformers() Deprecated. Use ExtensionTransformerRegistration
boolean	isRuntimeOnlyRegistrationValid() Gets whether it is valid for the extension to register resources, attributes or operations that do not involve the persistent configuration, but rather only involve runtime services.
default void	registerExpressionResolverExtension(Supplier<ExpressionResolverExtension> supplier, Pattern expressionPattern, boolean requiresRuntimeResolution) Registers that the extension may provide an ExpressionResolverExtension if one of its subsystems is appropriately configured.
SubsystemRegistration	registerSubsystem(String name, int majorVersion, int minorVersion) Deprecated. registerSubsystem(String, ModelVersion)
SubsystemRegistration	registerSubsystem(String name, int majorVersion, int minorVersion, int microVersion) Deprecated. registerSubsystem(String, ModelVersion)
SubsystemRegistration	registerSubsystem(String name, int majorVersion, int minorVersion, int microVersion, boolean deprecated) Deprecated. registerSubsystem(String, ModelVersion, boolean)
SubsystemRegistration	registerSubsystem(String name, ModelVersion version) Convenience variant of registerSubsystem(String, int, int, int) that uses 0 as the microVersion.
SubsystemRegistration	registerSubsystem(String name, ModelVersion version, boolean deprecated) Register a new subsystem type.

Method Detail

registerSubsystem

SubsystemRegistration registerSubsystem(String name,
                                        ModelVersion version)

Convenience variant of registerSubsystem(String, int, int, int) that uses 0 as the microVersion.

Parameters:

name - the name of the subsystem

version - the version of the subsystem's management interface.

Returns:

the SubsystemRegistration

Throws:

IllegalStateException - if the subsystem name has already been registered

registerSubsystem

SubsystemRegistration registerSubsystem(String name,
                                        ModelVersion version,
                                        boolean deprecated)

Register a new subsystem type. The returned registration object should be used to configure XML parsers, operation handlers, and other subsystem-specific constructs for the new subsystem. If the subsystem registration is deemed invalid by the time the extension registration is complete, the subsystem registration will be ignored, and an error message will be logged.

The new subsystem registration must register a handler and description for the add operation at its root address. The new subsystem registration must register a remove operation at its root address.

Parameters:

name - the name of the subsystem

version - the version of the subsystem's management interface.

deprecated - mark this extension as deprecated

Returns:

the SubsystemRegistration

Throws:

IllegalStateException - if the subsystem name has already been registered

registerSubsystem

@Deprecated
SubsystemRegistration registerSubsystem(String name,
                                                    int majorVersion,
                                                    int minorVersion)

Deprecated. registerSubsystem(String, ModelVersion)

Convenience variant of registerSubsystem(String, int, int, int) that uses 0 as the microVersion.

Parameters:

name - the name of the subsystem

majorVersion - the major version of the subsystem's management interface

minorVersion - the minor version of the subsystem's management interface

Returns:

the SubsystemRegistration

Throws:

IllegalStateException - if the subsystem name has already been registered

registerSubsystem

@Deprecated
SubsystemRegistration registerSubsystem(String name,
                                                    int majorVersion,
                                                    int minorVersion,
                                                    int microVersion)

Deprecated. registerSubsystem(String, ModelVersion)

Register a new subsystem type. The returned registration object should be used to configure XML parsers, operation handlers, and other subsystem-specific constructs for the new subsystem. If the subsystem registration is deemed invalid by the time the extension registration is complete, the subsystem registration will be ignored, and an error message will be logged.

The new subsystem registration must register a handler and description for the add operation at its root address. The new subsystem registration must register a remove operation at its root address.

Parameters:

name - the name of the subsystem

majorVersion - the major version of the subsystem's management interface

minorVersion - the minor version of the subsystem's management interface

microVersion - the micro version of the subsystem's management interface

Returns:

the SubsystemRegistration

Throws:

IllegalStateException - if the subsystem name has already been registered

registerSubsystem

@Deprecated
SubsystemRegistration registerSubsystem(String name,
                                                    int majorVersion,
                                                    int minorVersion,
                                                    int microVersion,
                                                    boolean deprecated)

Deprecated. registerSubsystem(String, ModelVersion, boolean)

Register a new subsystem type. The returned registration object should be used to configure XML parsers, operation handlers, and other subsystem-specific constructs for the new subsystem. If the subsystem registration is deemed invalid by the time the extension registration is complete, the subsystem registration will be ignored, and an error message will be logged.

The new subsystem registration must register a handler and description for the add operation at its root address. The new subsystem registration must register a remove operation at its root address.

Parameters:

name - the name of the subsystem

majorVersion - the major version of the subsystem's management interface

minorVersion - the minor version of the subsystem's management interface

microVersion - the micro version of the subsystem's management interface

deprecated - mark this extension as deprecated

Returns:

the SubsystemRegistration

Throws:

IllegalStateException - if the subsystem name has already been registered

registerExpressionResolverExtension

default void registerExpressionResolverExtension(Supplier<ExpressionResolverExtension> supplier,
                                                 Pattern expressionPattern,
                                                 boolean requiresRuntimeResolution)

Registers that the extension may provide an ExpressionResolverExtension if one of its subsystems is appropriately configured. Calling this informs the management kernel that the resolver extension may be installed at some point and provides a supplier via which the resolver extension can be obtained. It also instructs the management kernel as to how to handle expression strings that might be of interest to the resolver extension if it were configured.

Once this is invoked, the kernel expression resolver will begin calling the given supplier whenever it needs to resolve an expression string. If it returns a non-null value, the returned ExpressionResolverExtension will be invoked to ensure it is initialized and to try and resolve the expression string.

If the given supplier returns [@code null}, that indicates the resolver extension has not yet been configured (and perhaps never will be.) The management kernel resolver will however continue to account for the resolver extension in the following ways:

1. It will check if any unresolved expression string matches the provided expressionPatterns. If not no further action is taken with respect to this resolver extension.
2. If it does match, and the expression resolution is occurring in OperationContext.Stage.MODEL, an exception will be thrown. The effect of this is calling this method disables Stage.MODEL resolution of expressions that match the pattern. Resolving in Stage.MODEL is generally an anti-pattern though, although there are cases where it is attempted, particular with system-property resources.
3. If it does match and the expression resolution is occurring after OperationContext.Stage.MODEL, the behavior depends on the provided requiresRuntimeResolution parameter. If true, an exception will be thrown, as the required resolution could not be performed. If false, no resolution will be attempted and the overall resolution will continue on. Setting this to false allows expressions that match the pattern but which aren't definitely meant for handling by the resolver extension to still be processed.

Note that if multiple callers register resolver extensions, the management kernel will apply the above logic to each in turn until one provides a resolved string or all have been given an opportunity to try. Only when all have been given an opportunity to try will any exception resulting from one of the attempts be propagated. If none provide a resolved string, but none throw an exception, the expression resolution will move on to trying the core management kernel expression resolution mechanism.

Parameters:

supplier - function to be checked during expression resolution to determine if the resolver extension is available. Supplier should return null if the resolver extension isn't actually configured by a subsystem. The supplier itself cannot be null.

expressionPattern - if the supplier returns null, the pattern the kernel expression resolver should use to determine if a given expression string would be of interest to the resolver extension if it was available.

requiresRuntimeResolution - true if the kernel resolver should throw an expression resolution exception if the supplier returns null, the expression string to resolves matches the given expressionPattern, and the resolution is occuring outside of OperationContext.Stage.MODEL.

getType

ExtensionContext.ContextType getType()

Gets the type of this context.

Returns:

the context type. Will not be null

getProcessType

ProcessType getProcessType()

Gets the type of the current process.

Returns:

the current process type. Will not be null

getRunningMode

RunningMode getRunningMode()

Gets the current running mode of the process.

Returns:

the current running mode. Will not be null

isRuntimeOnlyRegistrationValid

boolean isRuntimeOnlyRegistrationValid()

Gets whether it is valid for the extension to register resources, attributes or operations that do not involve the persistent configuration, but rather only involve runtime services. Extensions should use this method before registering such "runtime only" resources, attributes or operations. This method is intended to avoid registering resources, attributes or operations on process types that can not install runtime services.

Returns:

whether it is valid to register runtime resources, attributes, or operations.

getPathManager

PathManager getPathManager()

Gets the process' PathManager if the process is a server; throws an IllegalStateException if not.

Returns:

the path manager. Will not return null

Throws:

IllegalStateException - if the process is not a server

isRegisterTransformers

@Deprecated
boolean isRegisterTransformers()

Deprecated. Use ExtensionTransformerRegistration

Returns true if subsystems should register transformers. This is true if #getProcessType().isHostController() is true and the process controller is the master domain controller.

Returns:

true if transformers should be registered