oracle.security.opss.service.config

Interface ConfigurationManagementService

All Superinterfaces:

JpsPersistable, OpssServiceInstance, ServiceInstance, ServiceLifecycle

public interface ConfigurationManagementService
extends ServiceLifecycle, OpssServiceInstance

The OPSS Configuration Management Service which manages the lifecycle of configuration(s) for one or more OPSS Runtime(s) (ServiceContexts). This service manages the Lifecycle of Configuration Profiles. Profiles are customized jps-config.xml files that relate to a specific usage of OPSS Services by an OPSS Consumer. For example one could register a FusionApps Profile or a JavaService Profile. A profile is identified by its unique identifier (profileId). The configuration service also manages the Lifecycle of Context Configurations. Context Configurations can be created either by supplying

• Explicit Configuration of the OPSS Services and BootStrap Services that should be created by the OPSS Runtime
• By providing a Customization of an Existing Configuration Profile.

A given implementation of this Service may chose to support only one of the above two methods or it may support both. Context Configurations can be identified by their unique Id (contextId) supplied during creation or they can have a unique name (contextName) in addition. Each Context Configuration can be in one of the following states at any given time

• CREATED
• COMPLETE
• ACTIVE
• INACTIVE
• TERMINATED

While the contextName for a Context Configuration is optional during creation, a Context Configuration cannot be COMPLETED unless it has a contextName set. The state of a Context Configuration defined in the OOTB jps-config.xml is considered to be implicitly ACTIVE and these Context Configurations do not undergo any state changes during the entire lifetime. Attempts to perform State Management of these contexts will be IGNORED. The Configuration Management Service itself can be in one of 2 Modes

• DEFAULT Mode : In this Mode the Configuration Service has consumed the OOTB/specified jps-config.xml and can service requests for obtaining the Default Configuration Context and other contexs defined in jps-config.xml. Requests for other services (such as querying the configurations of context's etc.) in this state will cause the ConfigurationService to transition to the REPOSITORY MODE for processing those requests.
• REPOSITORY Mode: In this Mode the Configuration Service is connected to its Configuration Repository and can handle all Service Requests.

The Configuration Management Service would transition from DEFAULT mode to REPOSITORY mode lazily the first time there is a request to service a Context Configuration or a Configuration Profile.

Author:

vjayanti

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	ConfigurationManagementService.CONFIG_STATE
static interface	ConfigurationManagementService.ConfigCustomization A Configuration Customization.
static class	ConfigurationManagementService.SERVICE_MODE

Nested classes/interfaces inherited from interface oracle.security.opss.service.OpssServiceInstance

OpssServiceInstance.State

Nested classes/interfaces inherited from interface oracle.security.jps.service.JpsPersistable

JpsPersistable.Mode

Method Summary

Methods

Modifier and Type	Method and Description
void	activateContextConfiguration(java.lang.String contextId) Activate a registered configuration.
void	addConfigListener(ConfigListener listener, ConfigEvent[] filter)
void	createConfigurationProfile(java.lang.String profileId, java.net.URI profileXml)
void	createContextConfiguration(java.lang.String contextId, java.util.List<ServiceInstanceDescriptor> serviceConfig, java.util.List<ServiceInstanceDescriptor> bootstrapConfig) Register a new configuration with the Configuration Service using explicit service definitions.
void	createContextConfiguration(java.lang.String contextId, java.lang.String profileId, javax.security.auth.callback.CallbackHandler customizationHandler) Create a new ContextConfiguration using a base Template/Profile.
void	createContextConfiguration(java.lang.String contextId, java.lang.String profileId, java.util.List<ConfigurationManagementService.ConfigCustomization> customization, java.util.List<ConfigurationManagementService.ConfigCustomization> bootCustomization) Create a new ContextConfiguration using a base Template/Profile.
void	deactivateContextConfiguration(java.lang.String contextId) Deactivate a registered Context Configuration
void	deleteConfigurationProfile(java.lang.String profileId)
void	deleteContextConfiguration(java.lang.String contextId) Unregister a Context Configuration.
void	exportConfiguration(java.lang.String contextId, java.io.OutputStream stream)
void	exportProfile(java.lang.String profileId, java.io.OutputStream stream) Export the configuration of a Profile to the outputstream.
ContextConfiguration	getContextBootstrapConfiguration(java.lang.String contextId)
ContextConfiguration	getContextConfiguration(java.lang.String contextId)
java.util.List<java.lang.String>	getContextConfigurationIds()
java.util.List<java.lang.String>	getContextConfigurationIds(ConfigurationManagementService.CONFIG_STATE state)
java.util.List<java.lang.String>	getContextConfigurationIds(ConfigurationManagementService.CONFIG_STATE state, java.lang.String profileId)
java.util.List<java.lang.String>	getContextConfigurationIds(java.lang.String profileId)
ConfigurationManagementService.CONFIG_STATE	getContextConfigurationState(java.lang.String contextId)
java.lang.String	getContextId(ContextNameEncoder contextNameEncoder)
java.lang.String	getContextName(java.lang.String contextId)
ContextConfiguration	getDefaultBootstrapConfiguration()
ContextConfiguration	getDefaultConfiguration()
JpsConfiguration	getJpsConfiguration()
ContextConfiguration	getJpsContextConfiguration(java.lang.String contextId)
ConfigurationManagementService.SERVICE_MODE	getMode()
java.util.List<java.lang.String>	getProfileIds()
java.util.List<ServiceProviderDescriptor>	getServiceProviders()
boolean	isRegistered(java.lang.String contextId)
void	removeConfigListener(ConfigListener listener)
void	setContextName(java.lang.String contextId, ContextNameEncoder contextNameEncoder) Sets a unique name for a Context identified by its contextId.
java.lang.String	unsetContextName(java.lang.String contextId) Unset the name of a named Context.
void	updateContextConfiguration(java.lang.String contextId, javax.security.auth.callback.CallbackHandler customizationHandler, boolean replace, boolean complete) Update a ContextConfiguration.
void	updateContextConfiguration(java.lang.String contextId, java.util.List<ConfigurationManagementService.ConfigCustomization> customization, java.util.List<ConfigurationManagementService.ConfigCustomization> bootCustomization, boolean replace, boolean complete) Update a ContextConfiguration.

Methods inherited from interface oracle.security.opss.service.ServiceLifecycle

postStart, preStart, restart, start, stop, terminate

Methods inherited from interface oracle.security.opss.service.OpssServiceInstance

getState

Methods inherited from interface oracle.security.jps.service.ServiceInstance

accept, getName, getServiceProvider

Methods inherited from interface oracle.security.jps.service.JpsPersistable

persist, refresh

Method Detail

getMode

ConfigurationManagementService.SERVICE_MODE getMode()

Returns:

the SERVICE_MODE of the Configuration Service

getServiceProviders

java.util.List<ServiceProviderDescriptor> getServiceProviders()

Returns:

the list of OPSS ServiceProvider Descriptors.

Throws:

ConfigurationRuntimeException - if there was an error in fetching the configuration

getDefaultBootstrapConfiguration

ContextConfiguration getDefaultBootstrapConfiguration()

Returns:

the default Bootstrap Configuration as defined in the jps-config.xml supplied to the provider.

Throws:

ConfigurationRuntimeException - if there was an error in fetching the configuration

getDefaultConfiguration

ContextConfiguration getDefaultConfiguration()

Returns:

the default Runtime Configuration as defined in the jps-config.xml supplied to the provider.

Throws:

ConfigurationRuntimeException - if there was an error in fetching the configuration

getJpsConfiguration

JpsConfiguration getJpsConfiguration()

Returns:

JpsConfiguration

Throws:

ConfigurationRuntimeException - if there was an error in fetching the configuration

getJpsContextConfiguration

ContextConfiguration getJpsContextConfiguration(java.lang.String contextId)
                                                throws ConfigurationException

Returns:

the Configuration of a jpsContext defined in OOTB jps-config.xml as a ContextConfiguration or null if so such jpsContext exists

Throws:

ConfigurationException - if there was an error in fetching the configuration

createConfigurationProfile

void createConfigurationProfile(java.lang.String profileId,
                              java.net.URI profileXml)
                                throws ConfigurationException

Parameters:

profileId - the unique identifier for the profile

profileXml - A template jps-config.xml that defines the Configuration Profile

Throws:

ConfigurationException - if there was an error in creating the configuration profile

deleteConfigurationProfile

void deleteConfigurationProfile(java.lang.String profileId)
                                throws ConfigurationException,
                                       RegistrationException

Parameters:

profileId - the unique identifier for the profile

Throws:

ConfigurationException - if there was an error in deleting the configuration profile

RegistrationException - if a profile with the profileId is not registered.

getContextConfiguration

ContextConfiguration getContextConfiguration(java.lang.String contextId)
                                             throws ConfigurationException,
                                                    RegistrationException

Parameters:

contextId - the unique identifier for the context whose Configuration is desired

Returns:

The configuration defined for a given context in OPSS configuration repository

Throws:

AccessControlException - if the code does not have permission to invoke this operation

ConfigurationException - if there was an error in fetching the configuration

RegistrationException - if a configuration with the contextId is not registered.

getContextBootstrapConfiguration

ContextConfiguration getContextBootstrapConfiguration(java.lang.String contextId)
                                                      throws ConfigurationException,
                                                             RegistrationException

Parameters:

contextId - the unique identifier for the bootstrap context whose Configuration is desired

Returns:

the bootstrap ContextConfiguration identified by the contextId.

Throws:

AccessControlException - if the code does not have permission to invoke this operation

ConfigurationException - if there was an error in fetching the configuration

RegistrationException - if a configuration with the contextId is not registered.

createContextConfiguration

void createContextConfiguration(java.lang.String contextId,
                              java.util.List<ServiceInstanceDescriptor> serviceConfig,
                              java.util.List<ServiceInstanceDescriptor> bootstrapConfig)
                                throws ConfigurationException,
                                       RegistrationException

Register a new configuration with the Configuration Service using explicit service definitions. The Configuration would be in CREATED state upon successful creation

Parameters:

contextId - the unique identifier for the ContextConfiguration

servicesConfig - the services configuration

bootstrapConfig - the bootstrap configuration.

Throws:

RegistrationException - if a Config with the contextId is already registered

AccessControlException - if the code does not have permission to invoke this operation

ConfigurationException - if there was an error in creating the configuration

createContextConfiguration

void createContextConfiguration(java.lang.String contextId,
                              java.lang.String profileId,
                              java.util.List<ConfigurationManagementService.ConfigCustomization> customization,
                              java.util.List<ConfigurationManagementService.ConfigCustomization> bootCustomization)
                                throws ConfigurationException,
                                       RegistrationException

Create a new ContextConfiguration using a base Template/Profile. The Configuration would be in CREATED state upon successful creation

Parameters:

contextId - the unique identifier for the ContextConfiguration

profileId - the base profile name from which to derive the Context Configuration

customization - the customization to be applied to the profile

bootCustomization - the customization to be applied to the bootstrap configuration implied by the profile, can be null.

Throws:

RegistrationException - if a Config with the contextId is already registered

AccessControlException - if the code does not have permission to invoke this operation

ConfigurationException - if there was an error in creating the configuration

createContextConfiguration

void createContextConfiguration(java.lang.String contextId,
                              java.lang.String profileId,
                              javax.security.auth.callback.CallbackHandler customizationHandler)
                                throws ConfigurationException

Create a new ContextConfiguration using a base Template/Profile. The Configuration would be in CREATED state upon successful creation. This method provides an Alternate programmatic form of customization where callers can supply code in the form of a CallbackHandler to perform Customizations

Parameters:

contextId - the unique identifier for the ContextConfiguration

profileId - the base profile name from which to derive the Context Configuration

customizationHandler - A CallBackHandler that can handle the CustomizationCallback to obtain the base Configuration as a DOM element on which it can perform the required Customizations.

Throws:

ConfigurationException

updateContextConfiguration

void updateContextConfiguration(java.lang.String contextId,
                              java.util.List<ConfigurationManagementService.ConfigCustomization> customization,
                              java.util.List<ConfigurationManagementService.ConfigCustomization> bootCustomization,
                              boolean replace,
                              boolean complete)
                                throws UnNamedContextException,
                                       RegistrationException,
                                       ConfigurationException

Update a ContextConfiguration. The Configuration must be in INACTIVE/CREATED state before a call to this method.

Parameters:

contextId - the unique identifier for the ContextConfiguration

customization - the customization to be applied to the configuration, can be null

bootCustomization - the customization to be applied to the bootstrap configuration implied by the profile, can be null.

replace - when set to true will completely replace the existing customizations with newly supplied customizations. When set to false the customizations supplied here are applied on top of the existing customizations (with matching targets overriding the old customization by newly supplied customization).

complete - when set to true will set the state of the configuration to COMPLETE.

Throws:

ConfigurationException - if there was an error in performing the operation or if the state of the context configuration is not INACTIVE/CREATED when the method was called. A ConfigurationException is also thrown if complete flag was set to true and the configuration was actually completed earlier.

UnNamedContextException - if a contextName was not set for the context

RegistrationException - if a Config with the contextId does not exist

AccessControlException - if the code does not have permission to invoke this operation

updateContextConfiguration

void updateContextConfiguration(java.lang.String contextId,
                              javax.security.auth.callback.CallbackHandler customizationHandler,
                              boolean replace,
                              boolean complete)
                                throws UnNamedContextException,
                                       RegistrationException,
                                       ConfigurationException

Update a ContextConfiguration. The Configuration must be in INACTIVE/CREATED state before a call to this method. This method provides an Alternate programmatic form of customization where callers can supply code in the form of a CallBackHandler to perform Customizations

Parameters:

contextId - the unique Identifier of the contextConfiguration

customizationHandler - A CallbackHandler that can handle the CustomizationCallback to obtain the base Configuration as a DOM element on which it can perform the required Customizations.

replace - when set to true will completely replace the existing customizations with newly supplied customizations. When set to false the customizations supplied here are applied on top of the existing customizations (with matching targets overriding the old customization by newly supplied customization).

complete - when set to true will set the state of the configuration to COMPLETE.

Throws:

ConfigurationException - if there was an error in performing the operation or if the state of the context configuration is not INACTIVE/CREATED when the method was called. A ConfigurationException is also thrown if complete flag was set to true and the configuration was actually completed earlier.

UnNamedContextException - if a contextName was not set for the context

RegistrationException - if a context with the contextId does not exist

AccessControlException - if the code does not have permission to invoke this operation

deleteContextConfiguration

void deleteContextConfiguration(java.lang.String contextId)
                                throws ConfigurationException,
                                       RegistrationException

Unregister a Context Configuration. The state of the configuration would be TERMINATED during execution of this method, till the time it gets removed from the Configuration Repository.

Parameters:

contextId - the context identifier

Throws:

RegistrationException - if a context with the contextId is not registered

AccessControlException - if the code does not have permission to invoke this operation

ConfigurationException - if there was an error in fetching the configuration

isRegistered

boolean isRegistered(java.lang.String contextId)
                     throws ConfigurationException

Parameters:

contextId - the context identifier

Returns:

true if a context with the contextId exists, false otherwise

Throws:

ConfigurationException - if there is an error in determining the registration status.

AccessControlException - if the code does not have permission to invoke this operation

activateContextConfiguration

void activateContextConfiguration(java.lang.String contextId)
                                  throws ConfigurationException,
                                         RegistrationException,
                                         ActivationException

Activate a registered configuration.

Parameters:

contextId - the context identifier

Throws:

AccessControlException - if the code does not have permission to invoke this operation

RegistrationException - if a config with the contextId is not registered.

ActivationException - if a config with the contextId is already active.

ConfigurationException - if there was an error in fetching the configuration

deactivateContextConfiguration

void deactivateContextConfiguration(java.lang.String contextId)
                                    throws ConfigurationException,
                                           RegistrationException,
                                           ActivationException

Deactivate a registered Context Configuration

Parameters:

contextId - the context identifier

Throws:

AccessControlException - if the code does not have permission to invoke this operation

RegistrationException - if a context with the contextId is not registered.

ActivationException - if a context with the contextId not active.

ConfigurationException - if there was an error in fetching the configuration

getContextConfigurationState

ConfigurationManagementService.CONFIG_STATE getContextConfigurationState(java.lang.String contextId)
                                                                         throws ConfigurationException,
                                                                                RegistrationException

Parameters:

contextId - the context identifier

Returns:

returns the State of the Configuration identified by contextId

Throws:

AccessControlException - if the code does not have permission to invoke this operation

RegistrationException - if a configuration with the contextId is not registered.

ConfigurationException - if there was an error in fetching the configuration state information

getContextConfigurationIds

java.util.List<java.lang.String> getContextConfigurationIds()
                                                            throws ConfigurationException

Returns:

returns a list of contextId's of all registered configurations. Configurations in the OOTB/specified jps-config.xml are also treated as implicitly registered.

Throws:

AccessControlException - if the code does not have permission to invoke this operation.

ConfigurationException - if there was an error in fetching the list of registered configurations.

getContextConfigurationIds

java.util.List<java.lang.String> getContextConfigurationIds(java.lang.String profileId)
                                                            throws ConfigurationException

Parameters:

profileId - the profile under which the configurations are to be fetched

Returns:

the ContextId's of the registered Context Configurations.

Throws:

ConfigurationPersistenceException

ConfigurationException

getContextConfigurationIds

java.util.List<java.lang.String> getContextConfigurationIds(ConfigurationManagementService.CONFIG_STATE state)
                                                            throws ConfigurationException

Parameters:

state - the state of the context configuration

Returns:

returns a list of contextId's for all registered configurations in the specified state

Throws:

AccessControlException - if the code does not have permission to invoke this operation.

ConfigurationRuntimeException - if there was an error in fetching the list of configurations.

ConfigurationException

getContextConfigurationIds

java.util.List<java.lang.String> getContextConfigurationIds(ConfigurationManagementService.CONFIG_STATE state,
                                                          java.lang.String profileId)
                                                            throws ConfigurationException

Parameters:

state - the state of the context configuration

profileId - the profile under which the configurations are to be fetched

Returns:

returns a list of contextId's of all registered configurations in the specified state

Throws:

AccessControlException - if the code does not have permission to invoke this operation.

ConfigurationRuntimeException - if there was an error in fetching the list of configurations.

ConfigurationException

getProfileIds

java.util.List<java.lang.String> getProfileIds()
                                               throws ConfigurationException

Returns:

the list of ProfileId's registered with the System

Throws:

ConfigurationException - if there was an error in registering the listener

addConfigListener

void addConfigListener(ConfigListener listener,
                     ConfigEvent[] filter)
                       throws ConfigurationException

Parameters:

listener - the listener to be notified for configuration registrations and un-registrations, as well as state changes

filter - the list of ConfigEvents that the listener is interested in. When specified as null, the listener would be notified for all Config Events.

Throws:

AccessControlException - if the code does not have permission to invoke this operation

ConfigurationException - if there was an error in registering the listener

removeConfigListener

void removeConfigListener(ConfigListener listener)
                          throws ConfigurationException

Parameters:

listener - the listener to be removed from the notification service

Throws:

ConfigurationException - if there was an error in un-registering the listener or if the listener was not registered.

exportProfile

void exportProfile(java.lang.String profileId,
                 java.io.OutputStream stream)
                   throws ConfigurationException,
                          java.io.IOException,
                          RegistrationException

Export the configuration of a Profile to the outputstream.

Parameters:

profileId - the id of the profile whose configuration has to be exported

stream - the

Throws:

AccessControlException - if the code does not have permission to invoke this operation.

RegistrationException - if a profile with the profileId is not registered.

ConfigurationException - if there was a problem in retrieving the configuration

java.io.IOException - if there was a problem in writing to the stream

exportConfiguration

void exportConfiguration(java.lang.String contextId,
                       java.io.OutputStream stream)
                         throws ConfigurationException,
                                java.io.IOException,
                                RegistrationException

Parameters:

contextId - the contextId whose complete configuration and bootstrap configuration is desired

stream - the outputstream to which the configuration needs to be written to

Throws:

AccessControlException - if the code does not have permission to invoke this operation.

RegistrationException - if a context with the contextId is not registered.

ConfigurationException - if there was a problem in retrieving the configuration

java.io.IOException - if there was a problem in writing to the stream

setContextName

void setContextName(java.lang.String contextId,
                  ContextNameEncoder contextNameEncoder)
                    throws ConfigurationException,
                           RegistrationException

Sets a unique name for a Context identified by its contextId. When the configuration of a Context is updated (via updateContextConfiguration API) the updates would happen in the context of the name in such a way that when the name is unset, the corresponding updates are reverted/purged.

Parameters:

contextId - the context for which the name has to be set

contextNameEncoder - Encoder instance that returns an encoded name to be set for the ContextConfiguration identified by the contexId

Throws:

ConfigurationException - if there was a problem in setting the name, or the context associated with contextId is in ACTIVE state, or the contextId is already associated with another contexName, or the contextName is already in use.

RegistrationException - if the contextId is not registered

unsetContextName

java.lang.String unsetContextName(java.lang.String contextId)
                                  throws ConfigurationException

Unset the name of a named Context. Any updates to the context configuration that happened in the context of the name would also be reverted at this point.

Parameters:

contextId - the context whose name (if any) has to be unset

Returns:

the current contextName if any was set prior to the call, or null

Throws:

ConfigurationException - if there was a problem in un-setting the name, or the context associated with contextId is in ACTIVE state

RegistrationException - if the contextId is not registered

getContextName

java.lang.String getContextName(java.lang.String contextId)
                                throws ConfigurationException

Parameters:

contextId - the context identifier

Returns:

the name (if any) associated with the contextId, null otherwise

Throws:

ConfigurationException - if there was a problem in getting the name

RegistrationException - if the contextId is not registered

getContextId

java.lang.String getContextId(ContextNameEncoder contextNameEncoder)
                              throws ConfigurationException

Parameters:

contextNameEncoder - Encoder instance that returns the encoded name of the context for which contextId is desired.

Returns:

the contextId (if any) associated with the name, null otherwise

Throws:

ConfigurationException - if there was a problem in getting the contextId