com.unboundid.directory.sdk.broker.api
Class StoreAdapter

java.lang.Object
  com.unboundid.directory.sdk.broker.api.StoreAdapter

All Implemented Interfaces:

Configurable, ExampleUsageProvider, UnboundIDExtension

@Extensible
@IdentityBrokerExtension
@ThreadSafety(level=INTERFACE_THREADSAFE)
public abstract class StoreAdapter
extends java.lang.Object
implements UnboundIDExtension, Configurable, ExampleUsageProvider

This class defines an API that must be implemented by extensions that need to store user data in some non-LDAP data store. This adapter API is generic and can support a wide range of repositories. When using multiple Identity Broker instances in a deployment, the data store should be accessible from all instances.

A Store Adapter can optionally support authentication by implementing the supportsAuthentication() and authenticate(StoreAuthenticationRequest) methods.

A Store Adapter can also opt to store the Identity Broker user metadata attributes, which contain the consents, OAuth tokens, and consent history, among other things. This metadata is separated into two categories: small and large. Both types are multi-valued and store raw binary values. The main difference is that the "small" metadata will typically contain small binary values and be accessed more frequently, whereas the "large" metadata will contain more sizable values (or a larger number of values) and be accessed less frequently. Implementers should take this into consideration when deciding where to store these metadata attributes.

After the StoreAdapter is initialized (via the initializeStoreAdapter() method), all methods will be guarded by a call to isAvailable() to make sure that the adapter is currently connected and ready to service requests. If this returns false, the DataView will return an appropriate 503 response code to clients until the adapter becomes available again.

Configuring Store Adapters

In order to configure a store adapter created using this API, use a command like:

      dsconfig create-store-adapter \
           ---adapter-name "{name}" \
           --type third-party \
           --set "extension-class:{class-name}" \
           --set "extension-argument:{name=value}"
 

where "{name}" is the name to use for the token store instance, "{class-name}" is the fully-qualified name of the Java class that extends com.unboundid.directory.sdk.broker.api.StoreAdapter, and "{name=value}" represents name-value pairs for any arguments to provide to the store adapter. If multiple arguments should be provided to extension, then the "--set extension-argument:{name=value}" option should be provided multiple times.

Constructor Summary

StoreAdapter()
Creates a new instance of this store adapter.

Method Summary

boolean	authenticate(java.lang.String scimId, AuthenticationRequest request) Authenticate the specified user against the backend data store.
abstract com.unboundid.scim.data.BaseResource	create(StoreCreateRequest request) Create the specified entry in the native data store.
void	defineConfigArguments(com.unboundid.util.args.ArgumentParser parser) Updates the provided argument parser to define any configuration arguments which may be used by this extension.
abstract void	delete(StoreDeleteRequest request) Delete the specified entry from the native data store.
void	finalizeStoreAdapter() This hook is called when the DataView is disabled or the Identity Broker shuts down.
java.util.Map<java.util.List<java.lang.String>,java.lang.String>	getExamplesArgumentSets() Retrieves a map containing examples of configurations that may be used for this extension.
abstract java.lang.String[]	getExtensionDescription() Retrieves a human-readable description for this extension.
abstract java.lang.String	getExtensionName() Retrieves a human-readable name for this extension.
abstract com.unboundid.scim.schema.ResourceDescriptor	getNativeSchema() Gets a ResourceDescriptor that describes the schema for the objects that will be returned by this StoreAdapter.
java.util.Collection<com.unboundid.util.ByteString>	getUserIndexedMetaData(java.lang.String scimId) Retrieve the user indexed metadata for the specified user.
java.util.Collection<com.unboundid.util.ByteString>	getUserLargeMetaData(java.lang.String scimId) Retrieve the user large metadata for the specified user.
java.util.Collection<com.unboundid.util.ByteString>	getUserMetaData(java.lang.String scimId) Retrieve the user metadata for the specified user.
void	initializeStoreAdapter(IdentityBrokerContext serverContext, StoreAdapterConfig config, com.unboundid.util.args.ArgumentParser parser) Initializes this store adapter.
abstract boolean	isAvailable() Determines whether this StoreAdapter is currently available and in-service.
abstract com.unboundid.scim.sdk.Resources<? extends com.unboundid.scim.data.BaseResource>	search(StoreSearchRequest request) Fetches the entries that match the specified criteria.
com.unboundid.scim.sdk.Resources<? extends com.unboundid.scim.data.BaseResource>	searchIndexedMetaData(com.unboundid.scim.sdk.SCIMFilterType filterType, com.unboundid.util.ByteString value, com.unboundid.scim.sdk.SCIMQueryAttributes requestAttrs) Retrieve resources that contain the specified user indexed metadata value.
boolean	supportsAuthentication(java.lang.Class<? extends AuthenticationRequest> request) Determines whether this StoreAdapter can handle the provided authentication request.
boolean	supportsUserMetaData() Determines whether this StoreAdapter supports reading and writing the user metadata attributes.
abstract com.unboundid.scim.data.BaseResource	update(StoreUpdateRequest request) Update the specified entry in the native data store.
void	updateUserMetaData(java.lang.String scimId, MetaDataMods metaDataMods, MetaDataMods indexedMetaDataMods, MetaDataMods largeMetaDataMods) Update the user metadata and/or user indexed metadata for the specified user with the specified modifications.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StoreAdapter

public StoreAdapter()

Creates a new instance of this store adapter. All implementations must include a default constructor, but any initialization should generally be done in the initializeStoreAdapter(com.unboundid.directory.sdk.broker.types.IdentityBrokerContext, com.unboundid.directory.sdk.broker.config.StoreAdapterConfig, com.unboundid.util.args.ArgumentParser) method.

Method Detail

getExtensionName

public abstract java.lang.String getExtensionName()

Retrieves a human-readable name for this extension.

Specified by:

getExtensionName in interface UnboundIDExtension

Returns:

A human-readable name for this extension.

getExtensionDescription

public abstract java.lang.String[] getExtensionDescription()

Retrieves a human-readable description for this extension. Each element of the array that is returned will be considered a separate paragraph in generated documentation.

Specified by:

getExtensionDescription in interface UnboundIDExtension

Returns:

A human-readable description for this extension, or null or an empty array if no description should be available.

getExamplesArgumentSets

public java.util.Map<java.util.List<java.lang.String>,java.lang.String> getExamplesArgumentSets()

Retrieves a map containing examples of configurations that may be used for this extension. The map key should be a list of sample arguments, and the corresponding value should be a description of the behavior that will be exhibited by the extension when used with that configuration.

Specified by:

getExamplesArgumentSets in interface ExampleUsageProvider

Returns:

A map containing examples of configurations that may be used for this extension. It may be null or empty if there should not be any example argument sets.

defineConfigArguments

public void defineConfigArguments(com.unboundid.util.args.ArgumentParser parser)
                           throws com.unboundid.util.args.ArgumentException

Updates the provided argument parser to define any configuration arguments which may be used by this extension. The argument parser may also be updated to define relationships between arguments (e.g., to specify required, exclusive, or dependent argument sets).

Specified by:

defineConfigArguments in interface Configurable

Parameters:

parser - The argument parser to be updated with the configuration arguments which may be used by this extension.

Throws:

com.unboundid.util.args.ArgumentException - If a problem is encountered while updating the provided argument parser.

initializeStoreAdapter

public void initializeStoreAdapter(IdentityBrokerContext serverContext,
                                   StoreAdapterConfig config,
                                   com.unboundid.util.args.ArgumentParser parser)
                            throws java.lang.Exception

Initializes this store adapter. Any initialization should be performed here. This method should generally store the IdentityBrokerContext in a class member so that it can be used elsewhere in the implementation.

The default implementation is empty.

Parameters:

serverContext - A handle to the server context for the server in which this extension is running. Extensions should typically store this in a class member.

config - The general configuration for this object.

parser - The argument parser which has been initialized from the configuration for this store adapter.

Throws:

java.lang.Exception - If a problem occurs while initializing this store adapter.

finalizeStoreAdapter

public void finalizeStoreAdapter()

This hook is called when the DataView is disabled or the Identity Broker shuts down. Any clean-up of this store adapter should be performed here.

The default implementation is empty.

supportsAuthentication

public boolean supportsAuthentication(java.lang.Class<? extends AuthenticationRequest> request)

Determines whether this StoreAdapter can handle the provided authentication request. The default implementation returns false, but subclasses may override this if they do support authentication.

Parameters:

request - the class of the authentication request.

Returns:

true if the StoreAdapter supports the provided authentication request, false otherwise.

supportsUserMetaData

public boolean supportsUserMetaData()

Determines whether this StoreAdapter supports reading and writing the user metadata attributes. The default implementation returns false, but subclasses may override this if they do support storing the metadata attributes.

Returns:

true if the StoreAdapter supports the Broker metadata, false otherwise.

authenticate

public boolean authenticate(java.lang.String scimId,
                            AuthenticationRequest request)
                     throws com.unboundid.scim.sdk.SCIMException,
                            AuthenticationException

Authenticate the specified user against the backend data store. The default implementation throws UnsupportedOperationException; subclasses that support authentication should override this.

Parameters:

scimId - the id of the user to authenticate.

request - the authentication request.

Returns:

true if authentication succeeds or false if this StoreAdaptor is unable to support the authentication request. In this case, other StoreAdaptors that supports the authentication request will be tried.

Throws:

com.unboundid.scim.sdk.SCIMException - if there is a problem authenticating the user

AuthenticationException - if authentication fails

isAvailable

public abstract boolean isAvailable()

Determines whether this StoreAdapter is currently available and in-service. This may return false in the case that all backend servers are down, for example; during this time the DataView will return an appropriate 503 response code to clients.

Returns:

true if the StoreAdapter initialized and connected; false otherwise.

getNativeSchema

public abstract com.unboundid.scim.schema.ResourceDescriptor getNativeSchema()

Gets a ResourceDescriptor that describes the schema for the objects that will be returned by this StoreAdapter. The StoreAdapter will always be initialized before this method is called, and the isAvailable() method will be checked as well.

Returns:

a SCIM ResourceDescriptor object. This may not be null.

search

public abstract com.unboundid.scim.sdk.Resources<? extends com.unboundid.scim.data.BaseResource> search(StoreSearchRequest request)
                                                                                                 throws com.unboundid.scim.sdk.SCIMException

Fetches the entries that match the specified criteria.

Parameters:

request - the search request

Returns:

a collection of SCIM resources that are in the native schema. This may be empty, but it may not be null.

Throws:

com.unboundid.scim.sdk.SCIMException - if there is a problem fulfilling the search request

create

public abstract com.unboundid.scim.data.BaseResource create(StoreCreateRequest request)
                                                     throws com.unboundid.scim.sdk.SCIMException

Create the specified entry in the native data store.

Parameters:

request - the create request

Returns:

the resource that was just created, scoped according to the SCIMQueryAttributes contained in the request

Throws:

com.unboundid.scim.sdk.SCIMException - if there is a problem creating the entry

update

public abstract com.unboundid.scim.data.BaseResource update(StoreUpdateRequest request)
                                                     throws com.unboundid.scim.sdk.SCIMException

Update the specified entry in the native data store.

Parameters:

request - the update request

Returns:

the updated resource, scoped according to the SCIMQueryAttributes contained in the request

Throws:

com.unboundid.scim.sdk.SCIMException - if there is a problem modifying the entry

delete

public abstract void delete(StoreDeleteRequest request)
                     throws com.unboundid.scim.sdk.SCIMException

Delete the specified entry from the native data store.

Parameters:

request - the delete request

Throws:

com.unboundid.scim.sdk.SCIMException - if there is a problem deleting the entry

updateUserMetaData

public void updateUserMetaData(java.lang.String scimId,
                               MetaDataMods metaDataMods,
                               MetaDataMods indexedMetaDataMods,
                               MetaDataMods largeMetaDataMods)
                        throws com.unboundid.scim.sdk.SCIMException

Update the user metadata and/or user indexed metadata for the specified user with the specified modifications. At least one of the MetaDataMods parameters will be non-null. The default implementation throws UnsupportedOperationException; subclasses should override this if they support the user metadata attributes.

Parameters:

scimId - the id of the user whose metadata is to be updated

metaDataMods - the set of modifications to the user metadata (may be null)

indexedMetaDataMods - the set of modifications to the indexed metadata (may be null)

largeMetaDataMods - the set of modifications to the large metadata (may be null)

Throws:

com.unboundid.scim.sdk.SCIMException - if there is a problem updating the metadata

getUserMetaData

public java.util.Collection<com.unboundid.util.ByteString> getUserMetaData(java.lang.String scimId)
                                                                    throws com.unboundid.scim.sdk.SCIMException

Retrieve the user metadata for the specified user. The default implementation throws UnsupportedOperationException; subclasses should override this if they support the user metadata attributes.

Parameters:

scimId - the id of the user

Returns:

the set of values for the metadata attribute

Throws:

com.unboundid.scim.sdk.SCIMException - if there is a problem retrieving the metadata

getUserIndexedMetaData

public java.util.Collection<com.unboundid.util.ByteString> getUserIndexedMetaData(java.lang.String scimId)
                                                                           throws com.unboundid.scim.sdk.SCIMException

Retrieve the user indexed metadata for the specified user. The default implementation throws UnsupportedOperationException; subclasses should override this if they support the user metadata attributes.

Parameters:

scimId - the id of the user

Returns:

the set of values for the indexed metadata attribute

Throws:

com.unboundid.scim.sdk.SCIMException - if there is a problem retrieving the large metadata

getUserLargeMetaData

public java.util.Collection<com.unboundid.util.ByteString> getUserLargeMetaData(java.lang.String scimId)
                                                                         throws com.unboundid.scim.sdk.SCIMException

Retrieve the user large metadata for the specified user. The default implementation throws UnsupportedOperationException; subclasses should override this if they support the user metadata attributes.

Parameters:

scimId - the id of the user

Returns:

the set of values for the large metadata attribute

Throws:

com.unboundid.scim.sdk.SCIMException - if there is a problem retrieving the large metadata

searchIndexedMetaData

public com.unboundid.scim.sdk.Resources<? extends com.unboundid.scim.data.BaseResource> searchIndexedMetaData(com.unboundid.scim.sdk.SCIMFilterType filterType,
                                                                                                              com.unboundid.util.ByteString value,
                                                                                                              com.unboundid.scim.sdk.SCIMQueryAttributes requestAttrs)
                                                                                                       throws com.unboundid.scim.sdk.SCIMException

Retrieve resources that contain the specified user indexed metadata value.

Parameters:

filterType - The filter type to use.

value - The user indexed metadata value to search on.

requestAttrs - The attributes to return.

Returns:

The resources that contain the specified user indexed metadata value. Guaranteed not to be null, but could be empty.

Throws:

com.unboundid.scim.sdk.SCIMException - if there is a problem fulfilling the search request