EE4J Web API 10.0.0 · jakarta.security.auth.message.config.AuthConfigFactory

Modifier and Type	Class and Description
public static interface	AuthConfigFactory.RegistrationContext Represents the layer identifier, application context identifier, and description components of an AuthConfigProvider registration at the factory.

Modifier and Type	Field and Description
public static final String	DEFAULT_FACTORY_SECURITY_PROPERTY The name of the Security property used to define the default AuthConfigFactory implementation class.
private static AuthConfigFactory	factory
public static final String	GET_FACTORY_PERMISSION_NAME The name of the SecurityPermission required to call getFactory
public static final SecurityPermission	getFactorySecurityPermission The SecurityPermission, with name `GET_FACTORY_PERMISSION_NAME`, that is used to authorize access to the getFactory method.
public static final String	PROVIDER_REGISTRATION_PERMISSION_NAME The name of the SecurityPermission to be used to authorize access to the update methods of the factory implementation class.
private static final String	PROVIDER_SECURITY_PROPERTY The name of the Security property used to control operations within the factory.
public static final SecurityPermission	providerRegistrationSecurityPermission An instance of the SecurityPermission (with name `PROVIDER_REGISTRATION_PERMISSION_NAME`) for use in authorizing access to the update methods of the factory implementation class.
public static final String	SET_FACTORY_PERMISSION_NAME The name of the SecurityPermission required to call setFactory
public static final SecurityPermission	setFactorySecurityPermission The SecurityPermission, with name `SET_FACTORY_PERMISSION_NAME`, that is used to authorize access to the setFactory method.

Access	Constructor and Description
public	AuthConfigFactory()

Method Summary

Modifier and Type	Method and Description
private static void	checkPermission(Permission permission) Deprecated for removal. Following JEP 411 Utility method to check for permission to operate on the factory.
public abstract String[]	Returns: An array of String values where each value identifies a provider registration from which the listener was removed. This method never returns null; it returns an empty array if the listener was not removed from any registrations. detachListener(RegistrationListener The RegistrationListener to be detached. listener, String A String identifying the message layer or null. layer, String A String value identifying the application context or null. appContext) Disassociate the listener from all the provider registrations whose layer and appContext values are matched by the corresponding arguments to this method.
public abstract AuthConfigProvider	Returns: The implementation of the AuthConfigProvider interface registered at the factory for the layer and appContext, or null if no AuthConfigProvider is selected. An argument listener is attached even if the return value is null. getConfigProvider(String A String identifying the message layer for which the registered AuthConfigProvider is to be returned. The value of this argument may be null. layer, String A String that identifies the application messaging context for which the registered AuthConfigProvider is to be returned. The value of this argument may be null. appContext, RegistrationListener The RegistrationListener whose `notify` method is to be invoked if the corresponding registration is unregistered or replaced. The value of this argument may be null. listener) Get a registered AuthConfigProvider from the factory.
public static synchronized AuthConfigFactory	Returns: The non-null system-wide AuthConfigFactory instance set at the time of the call, or if that value was null, the value of the system-wide factory instance established by this method. This method returns null when the system-wide factory was not defined when this method was called and no default factory name was defined via the security property. getFactory() Get the system-wide AuthConfigFactory implementation.
public abstract AuthConfigFactory.RegistrationContext	Returns: A RegistrationContext or null. When a Non-null value is returned, it is a copy of the registration context corresponding to the registration. Null is returned when the registration identifier does not correspond to an active registration getRegistrationContext(String A String that identifies a provider registration at the factory registrationID) Get the registration context for the identified registration.
public abstract String[]	Returns: An array of String values where each value identifies a provider registration at the factory. This method never returns null; it returns an empty array when there are no registrations at the factory for the identified provider. getRegistrationIDs(AuthConfigProvider The AuthConfigurationProvider whose registration identifiers are to be returned. This argument may be null, in which case it indicates that the IDs of all active registrations within the factory are to be returned. provider) Get the registration identifiers for all registrations of the provider instance at the factory.
public abstract void	refresh() Cause the factory to reprocess its persistent declarative representation of provider registrations.
public abstract String	Returns: A String identifier assigned by the factory to the provider registration, and that may be used to remove the registration from the factory. registerConfigProvider(String The fully qualified name of an AuthConfigProvider implementation class (or null). Calling this method with a null value for this parameter shall cause `getConfigProvider` to return null when it is called with layer and appContext values for which the resulting registration is the best match. className, Map<String, String> A Map object containing the initialization properties to be passed to the properties argument of the provider constructor. This argument may be null. properties, String A String identifying the message layer for which the provider will be registered at the factory. A null value may be passed as an argument for this parameter, in which case the provider is registered at all layers. layer, String A String value that may be used by a runtime to request a configuration object from this provider. A null value may be passed as an argument for this parameter, in which case the provider is registered for all configuration ids (at the indicated layers). appContext, String A text String describing the provider. This value may be null. description) Registers within the factory and records within the factory's persistent declarative representation of provider registrations a provider of ServerAuthConfig and/or ClientAuthConfig objects for a message layer and application context identifier.
public abstract String	Returns: A String identifier assigned by the factory to the provider registration, and that may be used to remove the registration from the factory. registerConfigProvider(AuthConfigProvider The AuthConfigProvider to be registered at the factory (or null). Calling this method with a null value for this parameter shall cause `getConfigProvider` to return null when it is called with layer and appContext values for which the resulting registration is the best match. provider, String A String identifying the message layer for which the provider will be registered at the factory. A null value may be passed as an argument for this parameter, in which case the provider is registered at all layers. layer, String A String value that may be used by a runtime to request a configuration object from this provider. A null value may be passed as an argument for this parameter, in which case the provider is registered for all configuration ids (at the indicated layers). appContext, String A text String describing the provider. This value may be null. description) Registers within the (in-memory) factory, a provider of ServerAuthConfig and/or ClientAuthConfig objects for a message layer and application context identifier.
public abstract String	Returns: A String identifier assigned by the factory to the provider registration, and that may be used to remove the registration from the factory. registerServerAuthModule(ServerAuthModule the `ServerAuthModule` instance to be registered serverAuthModule, Object the profile specific context of the application for which the module is registered context) Registers within the (in-memory) factory, an instance of a `ServerAuthModule` for a message layer and application context identifier as identified by a profile specific context object.
public abstract boolean	Returns: True if there was a registration with the specified identifier and it was removed. Return false if the registrationID was invalid. removeRegistration(String A String that identifies a provider registration at the factory registrationID) Remove the identified provider registration from the factory (and from the persistent declarative representation of provider registrations, if appropriate) and invoke any listeners associated with the removed registration.
public abstract void	removeServerAuthModule(Object the profile specific context of the application for which the module is removed. context) Remove the `ServerAuthModule` (and potentially encompassing wrappers/factories) that was previously registered via a call to `registerServerAuthModule`.
public static synchronized void	setFactory(AuthConfigFactory The AuthConfigFactory instance, which may be null. factory) Set the system-wide AuthConfigFactory implementation.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

DEFAULT_FACTORY_SECURITY_PROPERTY	back to summary
public static final String DEFAULT_FACTORY_SECURITY_PROPERTY The name of the Security property used to define the default AuthConfigFactory implementation class.

factory	back to summary
private static AuthConfigFactory factory

GET_FACTORY_PERMISSION_NAME	back to summary
public static final String GET_FACTORY_PERMISSION_NAME The name of the SecurityPermission required to call getFactory

getFactorySecurityPermission	back to summary
public static final SecurityPermission getFactorySecurityPermission Deprecated for removal. Following JEP 411 The SecurityPermission, with name `GET_FACTORY_PERMISSION_NAME`, that is used to authorize access to the getFactory method. Annotations @Deprecated forRemoval:true

PROVIDER_REGISTRATION_PERMISSION_NAME	back to summary
public static final String PROVIDER_REGISTRATION_PERMISSION_NAME The name of the SecurityPermission to be used to authorize access to the update methods of the factory implementation class.

PROVIDER_SECURITY_PROPERTY	back to summary
private static final String PROVIDER_SECURITY_PROPERTY The name of the Security property used to control operations within the factory.

providerRegistrationSecurityPermission	back to summary
public static final SecurityPermission providerRegistrationSecurityPermission Deprecated for removal. Following JEP 411 An instance of the SecurityPermission (with name `PROVIDER_REGISTRATION_PERMISSION_NAME`) for use in authorizing access to the update methods of the factory implementation class. Annotations @Deprecated forRemoval:true

SET_FACTORY_PERMISSION_NAME	back to summary
public static final String SET_FACTORY_PERMISSION_NAME The name of the SecurityPermission required to call setFactory

setFactorySecurityPermission	back to summary
public static final SecurityPermission setFactorySecurityPermission Deprecated for removal. Following JEP 411 The SecurityPermission, with name `SET_FACTORY_PERMISSION_NAME`, that is used to authorize access to the setFactory method. Annotations @Deprecated forRemoval:true

AuthConfigFactory	back to summary
public AuthConfigFactory()

Method Detail

checkPermission	back to summary
private static void checkPermission(Permission permission) throws SecurityException Deprecated for removal. Following JEP 411 Utility method to check for permission to operate on the factory. Annotations @Deprecated forRemoval:true Exceptions SecurityException: if the SecurityManager is enabled and the calling access control context has not been granted the argument permission.

checkPermission

back to summary

private static void checkPermission(Permission permission) throws SecurityException

Deprecated

for removal.

Following JEP 411

Utility method to check for permission to operate on the factory.

Annotations

@Deprecated
forRemoval:true

Exceptions

SecurityException:: if the SecurityManager is enabled and the calling access control context has not been granted the argument permission.

detachListener back to summary

detachListener	back to summary
public abstract String[] detachListener(RegistrationListener listener, String layer, String appContext) Disassociate the listener from all the provider registrations whose layer and appContext values are matched by the corresponding arguments to this method. Factories should periodically notify Listeners to effectively detach listeners that are no longer in use. When a SecurityManager is enabled, and before making any changes to the factory, this method must confirm that the calling access control context has been granted the `providerRegistrationSecurityPermission` Parameters listener:RegistrationListener The RegistrationListener to be detached. layer:String A String identifying the message layer or null. appContext:String A String value identifying the application context or null. Returns:String[] An array of String values where each value identifies a provider registration from which the listener was removed. This method never returns null; it returns an empty array if the listener was not removed from any registrations. Exceptions SecurityException: If the caller does not have permission to detach the listener from the factory.

public abstract String[] detachListener(RegistrationListener listener, String layer, String appContext)

Disassociate the listener from all the provider registrations whose layer and appContext values are matched by the corresponding arguments to this method.

Factories should periodically notify Listeners to effectively detach listeners that are no longer in use.

When a SecurityManager is enabled, and before making any changes to the factory, this method must confirm that the calling access control context has been granted the providerRegistrationSecurityPermission

Parameters

listener:RegistrationListener: The RegistrationListener to be detached.
layer:String: A String identifying the message layer or null.
appContext:String: A String value identifying the application context or null.

Returns:String[]

An array of String values where each value identifies a provider registration from which the listener was removed. This method never returns null; it returns an empty array if the listener was not removed from any registrations.

Exceptions

SecurityException:: If the caller does not have permission to detach the listener from the factory.

getConfigProvider back to summary

getConfigProvider	back to summary
public abstract AuthConfigProvider getConfigProvider(String layer, String appContext, RegistrationListener listener) Get a registered AuthConfigProvider from the factory. Get the provider of ServerAuthConfig and ClientAuthConfig objects registered for the identified message layer and application context. All factories shall employ the following precedence rules to select the registered AuthConfigProvider that matches the layer and appContext arguments: The provider specifically registered for the values passed as the layer and appContext arguments shall be selected. If no provider is selected according to the preceding rule, the provider specifically registered for the value passed as the appContext argument and for all (that is, null) layers shall be selected. If no provider is selected according to the preceding rules, the provider specifically registered for the value passed as the layer argument and for all (that is, null) appContexts shall be selected. If no provider is selected according to the preceding rules, the provider registered for all (that is, null) layers and for all (that is, null) appContexts shall be selected. If no provider is selected according to the preceding rules, the factory shall terminate its search for a registered provider. The above precedence rules apply equivalently to registrations created with a null or non-null `className` argument. Parameters layer:String A String identifying the message layer for which the registered AuthConfigProvider is to be returned. The value of this argument may be null. appContext:String A String that identifies the application messaging context for which the registered AuthConfigProvider is to be returned. The value of this argument may be null. listener:RegistrationListener The RegistrationListener whose `notify` method is to be invoked if the corresponding registration is unregistered or replaced. The value of this argument may be null. Returns:AuthConfigProvider The implementation of the AuthConfigProvider interface registered at the factory for the layer and appContext, or null if no AuthConfigProvider is selected. An argument listener is attached even if the return value is null.

public abstract AuthConfigProvider getConfigProvider(String layer, String appContext, RegistrationListener listener)

Get a registered AuthConfigProvider from the factory. Get the provider of ServerAuthConfig and ClientAuthConfig objects registered for the identified message layer and application context.

All factories shall employ the following precedence rules to select the registered AuthConfigProvider that matches the layer and appContext arguments:

The provider specifically registered for the values passed as the layer and appContext arguments shall be selected.
If no provider is selected according to the preceding rule, the provider specifically registered for the value passed as the appContext argument and for all (that is, null) layers shall be selected.
If no provider is selected according to the preceding rules, the provider specifically registered for the value passed as the layer argument and for all (that is, null) appContexts shall be selected.
If no provider is selected according to the preceding rules, the provider registered for all (that is, null) layers and for all (that is, null) appContexts shall be selected.
If no provider is selected according to the preceding rules, the factory shall terminate its search for a registered provider.

The above precedence rules apply equivalently to registrations created with a null or non-null className argument.

Parameters

layer:String: A String identifying the message layer for which the registered AuthConfigProvider is to be returned. The value of this argument may be null.
appContext:String: A String that identifies the application messaging context for which the registered AuthConfigProvider is to be returned. The value of this argument may be null.
listener:RegistrationListener: The RegistrationListener whose notify method is to be invoked if the corresponding registration is unregistered or replaced. The value of this argument may be null.

Returns:AuthConfigProvider

The implementation of the AuthConfigProvider interface registered at the factory for the layer and appContext, or null if no AuthConfigProvider is selected. An argument listener is attached even if the return value is null.

getFactory back to summary

getFactory	back to summary
public static synchronized AuthConfigFactory getFactory() Get the system-wide AuthConfigFactory implementation. If a non-null system-wide factory instance is defined at the time of the call, for example, with `setFactory`, it will be returned. Otherwise, an attempt will be made to construct an instance of the default AuthConfigFactory implementation class. The fully qualified class name of the default factory implementation class is obtained from the value of the `DEFAULT_FACTORY_SECURITY_PROPERTY` security property. When an instance of the default factory implementation class is successfully constructed by this method, this method will set it as the system-wide factory instance. The absolute pathname of the Java security properties file is JAVA_HOME/lib/security/java.security, where JAVA_HOME refers to the directory where the JDK was installed. When a SecurityManager is enabled, the `getFactorySecurityPermission` will be required to call this method. If at the time of the call, a system-wide factory instance has not already been defined, then the `setFactorySecurityPermission` will also be required. Returns:AuthConfigFactory The non-null system-wide AuthConfigFactory instance set at the time of the call, or if that value was null, the value of the system-wide factory instance established by this method. This method returns null when the system-wide factory was not defined when this method was called and no default factory name was defined via the security property. Exceptions SecurityException: If the caller does not have permission to retrieve the factory, or set it as the system-wide instance. Also thrown if an exception was thrown during the class loading, or construction of the default AuthConfigFactory implementation class; in which case the SecurityException will contain the root Exception as its cause.

public static synchronized AuthConfigFactory getFactory()

Get the system-wide AuthConfigFactory implementation.

If a non-null system-wide factory instance is defined at the time of the call, for example, with setFactory, it will be returned. Otherwise, an attempt will be made to construct an instance of the default AuthConfigFactory implementation class. The fully qualified class name of the default factory implementation class is obtained from the value of the DEFAULT_FACTORY_SECURITY_PROPERTY security property. When an instance of the default factory implementation class is successfully constructed by this method, this method will set it as the system-wide factory instance.

The absolute pathname of the Java security properties file is JAVA_HOME/lib/security/java.security, where JAVA_HOME refers to the directory where the JDK was installed.

When a SecurityManager is enabled, the getFactorySecurityPermission will be required to call this method. If at the time of the call, a system-wide factory instance has not already been defined, then the setFactorySecurityPermission will also be required.

Returns:AuthConfigFactory

The non-null system-wide AuthConfigFactory instance set at the time of the call, or if that value was null, the value of the system-wide factory instance established by this method. This method returns null when the system-wide factory was not defined when this method was called and no default factory name was defined via the security property.

Exceptions

SecurityException:: If the caller does not have permission to retrieve the factory, or set it as the system-wide instance. Also thrown if an exception was thrown during the class loading, or construction of the default AuthConfigFactory implementation class; in which case the SecurityException will contain the root Exception as its cause.

getRegistrationContext	back to summary
public abstract AuthConfigFactory.RegistrationContext getRegistrationContext(String registrationID) Get the registration context for the identified registration. Parameters registrationID:String A String that identifies a provider registration at the factory Returns:AuthConfigFactory.RegistrationContext A RegistrationContext or null. When a Non-null value is returned, it is a copy of the registration context corresponding to the registration. Null is returned when the registration identifier does not correspond to an active registration

getRegistrationContext

back to summary

public abstract AuthConfigFactory.RegistrationContext getRegistrationContext(String registrationID)

Get the registration context for the identified registration.

Parameters

registrationID:String: A String that identifies a provider registration at the factory

Returns:AuthConfigFactory.RegistrationContext

A RegistrationContext or null. When a Non-null value is returned, it is a copy of the registration context corresponding to the registration. Null is returned when the registration identifier does not correspond to an active registration

getRegistrationIDs	back to summary
public abstract String[] getRegistrationIDs(AuthConfigProvider provider) Get the registration identifiers for all registrations of the provider instance at the factory. Parameters provider:AuthConfigProvider The AuthConfigurationProvider whose registration identifiers are to be returned. This argument may be null, in which case it indicates that the IDs of all active registrations within the factory are to be returned. Returns:String[] An array of String values where each value identifies a provider registration at the factory. This method never returns null; it returns an empty array when there are no registrations at the factory for the identified provider.

getRegistrationIDs

back to summary

public abstract String[] getRegistrationIDs(AuthConfigProvider provider)

Get the registration identifiers for all registrations of the provider instance at the factory.

Parameters

provider:AuthConfigProvider: The AuthConfigurationProvider whose registration identifiers are to be returned. This argument may be null, in which case it indicates that the IDs of all active registrations within the factory are to be returned.

Returns:String[]

An array of String values where each value identifies a provider registration at the factory. This method never returns null; it returns an empty array when there are no registrations at the factory for the identified provider.

refresh back to summary

refresh	back to summary
public abstract void refresh() Cause the factory to reprocess its persistent declarative representation of provider registrations. A factory should only replace an existing registration when a change of provider implementation class or initialization properties has occurred. When a SecurityManager is enabled, and before the point where this method could have caused any changes to the factory, this method must confirm that the calling access control context has been granted the `providerRegistrationSecurityPermission` Exceptions SecurityException: If the caller does not have permission to refresh the factory, or if an error occurred during the reinitialization.

public abstract void refresh()

Cause the factory to reprocess its persistent declarative representation of provider registrations.

A factory should only replace an existing registration when a change of provider implementation class or initialization properties has occurred.

When a SecurityManager is enabled, and before the point where this method could have caused any changes to the factory, this method must confirm that the calling access control context has been granted the providerRegistrationSecurityPermission

Exceptions

SecurityException:: If the caller does not have permission to refresh the factory, or if an error occurred during the reinitialization.

registerConfigProvider back to summary

registerConfigProvider	back to summary
public abstract String registerConfigProvider(String className, Map<String, String> properties, String layer, String appContext, String description) Registers within the factory and records within the factory's persistent declarative representation of provider registrations a provider of ServerAuthConfig and/or ClientAuthConfig objects for a message layer and application context identifier. This method typically constructs an instance of the provider before registering it with the factory. Factories may extend or modify the persisted registrations of existing provider instances, if those instances were registered with ClassName and properties arguments equivalent to those passed in the current call. This method employs the two argument constructor required to be supported by every implementation of the AuthConfigProvider interface, and this method must pass a null value for the factory argument of the constructor. `AuthConfigProviderImpl AuthConfigProviderImpl(Map properties, AuthConfigFactory factory)`. At most one registration may exist within the factory for a given combination of message layer and appContext. Any pre-existing registration with identical values for layer and appContext is replaced by a subsequent registration. When replacement occurs, the registration identifier, layer, and appContext identifier remain unchanged, and the AuthConfigProvider (with initialization properties) and description are replaced. Within the lifetime of its Java process, a factory must assign unique registration identifiers to registrations, and must never assign a previously used registration identifier to a registration whose message layer and or appContext identifier differ from the previous use. Programmatic registrations performed by using this method must update (according to the replacement rules described above) the persistent declarative representation of provider registrations employed by the factory constructor. When a SecurityManager is enabled, before loading the argument provider, and before making any changes to the factory, this method must confirm that the calling access control context has been granted the `providerRegistrationSecurityPermission` Parameters className:String The fully qualified name of an AuthConfigProvider implementation class (or null). Calling this method with a null value for this parameter shall cause `getConfigProvider` to return null when it is called with layer and appContext values for which the resulting registration is the best match. properties:Map<String, String> A Map object containing the initialization properties to be passed to the properties argument of the provider constructor. This argument may be null. layer:String A String identifying the message layer for which the provider will be registered at the factory. A null value may be passed as an argument for this parameter, in which case the provider is registered at all layers. appContext:String A String value that may be used by a runtime to request a configuration object from this provider. A null value may be passed as an argument for this parameter, in which case the provider is registered for all configuration ids (at the indicated layers). description:String A text String describing the provider. This value may be null. Returns:String A String identifier assigned by the factory to the provider registration, and that may be used to remove the registration from the factory. Exceptions SecurityException: If the caller does not have permission to register a provider at the factory, or if the the provider construction (given a non-null `className`) or registration fails.

public abstract String registerConfigProvider(String className, Map<String, String> properties, String layer, String appContext, String description)

Registers within the factory and records within the factory's persistent declarative representation of provider registrations a provider of ServerAuthConfig and/or ClientAuthConfig objects for a message layer and application context identifier. This method typically constructs an instance of the provider before registering it with the factory. Factories may extend or modify the persisted registrations of existing provider instances, if those instances were registered with ClassName and properties arguments equivalent to those passed in the current call.

This method employs the two argument constructor required to be supported by every implementation of the AuthConfigProvider interface, and this method must pass a null value for the factory argument of the constructor. AuthConfigProviderImpl AuthConfigProviderImpl(Map properties, AuthConfigFactory factory).

At most one registration may exist within the factory for a given combination of message layer and appContext. Any pre-existing registration with identical values for layer and appContext is replaced by a subsequent registration. When replacement occurs, the registration identifier, layer, and appContext identifier remain unchanged, and the AuthConfigProvider (with initialization properties) and description are replaced.

Within the lifetime of its Java process, a factory must assign unique registration identifiers to registrations, and must never assign a previously used registration identifier to a registration whose message layer and or appContext identifier differ from the previous use.

Programmatic registrations performed by using this method must update (according to the replacement rules described above) the persistent declarative representation of provider registrations employed by the factory constructor.

When a SecurityManager is enabled, before loading the argument provider, and before making any changes to the factory, this method must confirm that the calling access control context has been granted the providerRegistrationSecurityPermission

Parameters

className:String: The fully qualified name of an AuthConfigProvider implementation class (or null). Calling this method with a null value for this parameter shall cause getConfigProvider to return null when it is called with layer and appContext values for which the resulting registration is the best match.
properties:Map<String, String>: A Map object containing the initialization properties to be passed to the properties argument of the provider constructor. This argument may be null.
layer:String: A String identifying the message layer for which the provider will be registered at the factory. A null value may be passed as an argument for this parameter, in which case the provider is registered at all layers.
appContext:String: A String value that may be used by a runtime to request a configuration object from this provider. A null value may be passed as an argument for this parameter, in which case the provider is registered for all configuration ids (at the indicated layers).
description:String: A text String describing the provider. This value may be null.

Returns:String

A String identifier assigned by the factory to the provider registration, and that may be used to remove the registration from the factory.

Exceptions

SecurityException:: If the caller does not have permission to register a provider at the factory, or if the the provider construction (given a non-null className) or registration fails.

registerConfigProvider back to summary

registerConfigProvider	back to summary
public abstract String registerConfigProvider(AuthConfigProvider provider, String layer, String appContext, String description) Registers within the (in-memory) factory, a provider of ServerAuthConfig and/or ClientAuthConfig objects for a message layer and application context identifier. This method does NOT effect the factory's persistent declarative representation of provider registrations, and is intended to be used by providers to perform self-Registration. At most one registration may exist within the factory for a given combination of message layer and appContext. Any pre-existing registration with identical values for layer and appContext is replaced by a subsequent registration. When replacement occurs, the registration identifier, layer, and appContext identifier remain unchanged, and the AuthConfigProvider (with initialization properties) and description are replaced. Within the lifetime of its Java process, a factory must assign unique registration identifiers to registrations, and must never assign a previously used registration identifier to a registration whose message layer and or appContext identifier differ from the previous use. When a SecurityManager is enabled, and before making any changes to the factory, this method must confirm that the calling access control context has been granted the `providerRegistrationSecurityPermission` Parameters provider:AuthConfigProvider The AuthConfigProvider to be registered at the factory (or null). Calling this method with a null value for this parameter shall cause `getConfigProvider` to return null when it is called with layer and appContext values for which the resulting registration is the best match. layer:String A String identifying the message layer for which the provider will be registered at the factory. A null value may be passed as an argument for this parameter, in which case the provider is registered at all layers. appContext:String A String value that may be used by a runtime to request a configuration object from this provider. A null value may be passed as an argument for this parameter, in which case the provider is registered for all configuration ids (at the indicated layers). description:String A text String describing the provider. This value may be null. Returns:String A String identifier assigned by the factory to the provider registration, and that may be used to remove the registration from the factory. Exceptions SecurityException: If the caller does not have permission to register a provider at the factory, or if the provider registration fails.

public abstract String registerConfigProvider(AuthConfigProvider provider, String layer, String appContext, String description)

Registers within the (in-memory) factory, a provider of ServerAuthConfig and/or ClientAuthConfig objects for a message layer and application context identifier. This method does NOT effect the factory's persistent declarative representation of provider registrations, and is intended to be used by providers to perform self-Registration.

Parameters

provider:AuthConfigProvider: The AuthConfigProvider to be registered at the factory (or null). Calling this method with a null value for this parameter shall cause getConfigProvider to return null when it is called with layer and appContext values for which the resulting registration is the best match.
layer:String: A String identifying the message layer for which the provider will be registered at the factory. A null value may be passed as an argument for this parameter, in which case the provider is registered at all layers.
appContext:String: A String value that may be used by a runtime to request a configuration object from this provider. A null value may be passed as an argument for this parameter, in which case the provider is registered for all configuration ids (at the indicated layers).
description:String: A text String describing the provider. This value may be null.

Returns:String

A String identifier assigned by the factory to the provider registration, and that may be used to remove the registration from the factory.

Exceptions

SecurityException:: If the caller does not have permission to register a provider at the factory, or if the provider registration fails.

registerServerAuthModule back to summary

registerServerAuthModule	back to summary
public abstract String registerServerAuthModule(ServerAuthModule serverAuthModule, Object context) Registers within the (in-memory) factory, an instance of a `ServerAuthModule` for a message layer and application context identifier as identified by a profile specific context object. This will override any other modules that have already been registered, either via proprietary means or using the standard API. The `ServerAuthModule` is removed, via a call to `removeServerAuthModule` when the context associated with the profile specific context object ends. Note that this method is a convenience method that can be used instead of `registerConfigProvider`, but should ultimately have the same effect. That is, the `layer` and `appContext` parameters are generated from the context object, and the `ServerAuthModule` is wrapped by an implementation specific `AuthConfigProvider`, which are then used to call `registerConfigProvider` or an internal method with the same effect. The returned registration ID is then associated with the profile specific context object, and also returned from this method. A "profile specific context object" is for example the `ServletContext` in the Servlet Container Profile. The context associated with this `ServletContext` ends when for example the application corresponding to it is undeployed. Association of the registration ID with the `ServletContext` simply means calling the `setAttribute` method on the `ServletContext`, with the registration ID as value. (The name attribute has not been standardised in this version of the specification) Parameters serverAuthModule:ServerAuthModule the `ServerAuthModule` instance to be registered context:Object the profile specific context of the application for which the module is registered Returns:String A String identifier assigned by the factory to the provider registration, and that may be used to remove the registration from the factory.

public abstract String registerServerAuthModule(ServerAuthModule serverAuthModule, Object context)

Registers within the (in-memory) factory, an instance of a ServerAuthModule for a message layer and application context identifier as identified by a profile specific context object.

This will override any other modules that have already been registered, either via proprietary means or using the standard API. The ServerAuthModule is removed, via a call to removeServerAuthModule when the context associated with the profile specific context object ends.

Note that this method is a convenience method that can be used instead of registerConfigProvider, but should ultimately have the same effect. That is, the layer and appContext parameters are generated from the context object, and the ServerAuthModule is wrapped by an implementation specific AuthConfigProvider, which are then used to call registerConfigProvider or an internal method with the same effect. The returned registration ID is then associated with the profile specific context object, and also returned from this method.

A "profile specific context object" is for example the ServletContext in the Servlet Container Profile. The context associated with this ServletContext ends when for example the application corresponding to it is undeployed. Association of the registration ID with the ServletContext simply means calling the setAttribute method on the ServletContext, with the registration ID as value. (The name attribute has not been standardised in this version of the specification)

Parameters

serverAuthModule:ServerAuthModule: the ServerAuthModule instance to be registered
context:Object: the profile specific context of the application for which the module is registered

Returns:String

A String identifier assigned by the factory to the provider registration, and that may be used to remove the registration from the factory.

removeRegistration back to summary

removeRegistration	back to summary
public abstract boolean removeRegistration(String registrationID) Remove the identified provider registration from the factory (and from the persistent declarative representation of provider registrations, if appropriate) and invoke any listeners associated with the removed registration. When a SecurityManager is enabled, and before making any changes to the factory, this method must confirm that the calling access control context has been granted the `providerRegistrationSecurityPermission` Parameters registrationID:String A String that identifies a provider registration at the factory Returns:boolean True if there was a registration with the specified identifier and it was removed. Return false if the registrationID was invalid. Exceptions SecurityException: If the caller does not have permission to unregister the provider at the factory.

public abstract boolean removeRegistration(String registrationID)

Remove the identified provider registration from the factory (and from the persistent declarative representation of provider registrations, if appropriate) and invoke any listeners associated with the removed registration.

Parameters

registrationID:String: A String that identifies a provider registration at the factory

Returns:boolean

True if there was a registration with the specified identifier and it was removed. Return false if the registrationID was invalid.

Exceptions

SecurityException:: If the caller does not have permission to unregister the provider at the factory.

removeServerAuthModule back to summary

removeServerAuthModule	back to summary
public abstract void removeServerAuthModule(Object context) Remove the `ServerAuthModule` (and potentially encompassing wrappers/factories) that was previously registered via a call to `registerServerAuthModule`. Note that this method is a convenience method that can be used instead of `removeRegistration`, but should ultimately have the same effect. That is calling `removeRegistration` with the return value from `registerServerAuthModule` must have the same effect in that the `ServerAuthModule` is removed. Parameters context:Object the profile specific context of the application for which the module is removed.

public abstract void removeServerAuthModule(Object context)

Remove the ServerAuthModule (and potentially encompassing wrappers/factories) that was previously registered via a call to registerServerAuthModule.

Note that this method is a convenience method that can be used instead of removeRegistration, but should ultimately have the same effect. That is calling removeRegistration with the return value from registerServerAuthModule must have the same effect in that the ServerAuthModule is removed.

Parameters

context:Object: the profile specific context of the application for which the module is removed.

setFactory	back to summary
public static synchronized void setFactory(AuthConfigFactory factory) Set the system-wide AuthConfigFactory implementation. If an implementation was set previously, it will be replaced. Listeners are not notified of a change to the registered factory. Parameters factory:AuthConfigFactory The AuthConfigFactory instance, which may be null. Exceptions SecurityException: If the caller does not have permission to set the factory.

setFactory

back to summary

public static synchronized void setFactory(AuthConfigFactory factory)

Set the system-wide AuthConfigFactory implementation.

If an implementation was set previously, it will be replaced.

Listeners are not notified of a change to the registered factory.

Parameters

factory:AuthConfigFactory: The AuthConfigFactory instance, which may be null.

Exceptions

SecurityException:: If the caller does not have permission to set the factory.

Modifier and Type	Method and Description
public String	Returns: A String identifying the application context for which the AuthConfigProvider was registered. The returned value may be null. getAppContext() Get the application context identifier from the registration context
public String	Returns: The description String from the registration, or null if no description string was included in the registration. getDescription() Get the description from the registration context
public String	Returns: A String identifying the message layer for which the AuthConfigProvider was registered. The returned value may be null. getMessageLayer() Get the layer name from the registration context
public boolean	Returns: A boolean indicating whether the registration is the result of a className based registration, or an instance-based (for example, self-) registration. Only registrations performed using the five argument `registerConfigProvider` method are persistent. isPersistent() Get the persisted status from the registration context.

public abstract Class AuthConfigFactory

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public Interface AuthConfigFactory.RegistrationContext

Method Summary

Method Detail