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
 @BrokerExtension
 @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 Data Governance Server instances in a deployment, the data store should be accessible from all instances.

After the Store Adapter 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 SCIMResourceType 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 store adapter 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 the extension, then the "--set extension-argument:{name=value}" option should be provided multiple times.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
abstract java.lang.String	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 SCIMResourceType is disabled or the Data Governance Server 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.
java.util.Collection<StoreAttributeDefinition>	getNativeSchema() Retrieves a collection of attribute definitions describing the schema for objects supported by this Store Adapter.
void	initializeStoreAdapter(BrokerContext serverContext, StoreAdapterConfig config, com.unboundid.util.args.ArgumentParser parser) Initializes this store adapter.
abstract boolean	isAvailable() Determines whether this Store Adapter is currently available and in-service.
abstract java.lang.String	retrieve(StoreRetrieveRequest request) Fetches the specified entry.
abstract void	search(StoreSearchRequest request) Search for entries in the native store which could match the specified criteria.
abstract java.lang.String	update(StoreUpdateRequest request) Update the specified entry in the native data store.

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.BrokerContext, 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(BrokerContext 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 BrokerContext 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 SCIMResourceType is disabled or the Data Governance Server shuts down. Any clean-up of this store adapter should be performed here.

The default implementation is empty.

getNativeSchema

public java.util.Collection<StoreAttributeDefinition> getNativeSchema()

Retrieves a collection of attribute definitions describing the schema for objects supported by this Store Adapter. The default implementation returns an empty collection indicating that the schema is not defined. Use StoreAttributeDefinition.Builder to create instances of StoreAttributeDefinition.

Returns:

The attribute definitions describing the schema, or an empty collection if the schema is not defined.

isAvailable

public abstract boolean isAvailable()

Determines whether this Store Adapter 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 SCIMResourceType will return an appropriate 503 response code to clients.

Returns:

true if the Store Adapter initialized and connected; false otherwise.

retrieve

public abstract java.lang.String retrieve(StoreRetrieveRequest request)
                                   throws com.unboundid.scim2.common.exceptions.ScimException

Fetches the specified entry.

Parameters:

request - The retrieve request.

Returns:

The retrieved entry as a JSON object. This string can be created by any JSON library. For example, the Jackson library's ObjectNode.toString() or the UnboundID LDAP SDK's JSONObject.toString().

Throws:

com.unboundid.scim2.common.exceptions.ScimException - If there is a problem fulfilling the request.

search

public abstract void search(StoreSearchRequest request)
                     throws com.unboundid.scim2.common.exceptions.ScimException

Search for entries in the native store which could match the specified criteria. The contract is for the store adapter to return a superset of matching entries, i.e. The store adapter must return all entries which match the specified filter but may also return entries which do not match. The results from the store adapter are subsequently filtered by the Data Governance Server.

Parameters:

request - The search request.

Throws:

com.unboundid.scim2.common.exceptions.ScimException - If there is a problem fulfilling the search request.

create

public abstract java.lang.String create(StoreCreateRequest request)
                                 throws com.unboundid.scim2.common.exceptions.ScimException

Create the specified entry in the native data store.

Parameters:

request - The create request.

Returns:

The entry that was just created as a JSON object. This string can be created by any JSON library. For example, the Jackson library's ObjectNode.toString() or the UnboundID LDAP SDK's JSONObject.toString().

Throws:

com.unboundid.scim2.common.exceptions.ScimException - If there is a problem creating the entry.

update

public abstract java.lang.String update(StoreUpdateRequest request)
                                 throws com.unboundid.scim2.common.exceptions.ScimException

Update the specified entry in the native data store.

Parameters:

request - The update request.

Returns:

The updated resource as a JSON object. This string can be created by any JSON library. For example, the Jackson library's ObjectNode.toString() or the UnboundID LDAP SDK's JSONObject.toString().

Throws:

com.unboundid.scim2.common.exceptions.ScimException - If there is a problem modifying the entry.

delete

public abstract void delete(StoreDeleteRequest request)
                     throws com.unboundid.scim2.common.exceptions.ScimException

Delete the specified entry from the native data store.

Parameters:

request - The delete request.

Throws:

com.unboundid.scim2.common.exceptions.ScimException - If there is a problem deleting the entry.