Package org.forgerock.am.cts

Interface CTSPersistentStore

public interface CTSPersistentStore

Persistent storage interface for the CTS (Core Token Service) provides callers with a generic way of storing and retrieving objects.

The CTS is configured and provisioned by a backing implementation. Callers of this interface need will need to convert their native objects into a Token. This conversion is provided by a TokenAdapter implementation.

Once in Token format, the caller can perform CRUDPQ based operations on the store which will make the request to the backing implementation. In addition to the request, callers can specify a series of Options which will enable specific behaviours of the CTS.

Subsequent layers of the CTS will manage the specific detail of converting Token instances into the final storage representation which is defined by a CTS token schema. Mappings for this schema are defined in CoreTokenField and related classes.

Implementations of this interface must be thread safe as this service will often be on a direct call path from the front end of the Server hosting OpenAM, and so multiple calls to the service can occur at the same time from different calling threads.

See Also:

CTSOptions, TokenAdapter, Token

Method Summary

Modifier and Type	Method	Description
void	addContinuousQueryListener(ContinuousQueryListener listener, TokenFilter filter)	Performs a continuous query against the persistent store using the provided TokenFilter.
default Collection<PartialToken>	attributeQuery(TokenFilter tokenFilter)	Performs a partial Token query against the store synchronously.
Collection<PartialToken>	attributeQuery(TokenFilter tokenFilter, Options options)	Performs a partial Token query against the store synchronously.
default Promise<Collection<PartialToken>,CoreTokenException>	attributeQueryAsync(TokenFilter tokenFilter)	Performs a partial Token query against the store synchronously.
Promise<Collection<PartialToken>,CoreTokenException>	attributeQueryAsync(TokenFilter tokenFilter, Options options)	Performs a partial Token query against the store synchronously.
default Token	create(Token token)	Creates a Token in the persistent store synchronously.
Token	create(Token token, Options options)	Creates a Token in the persistent store synchronously.
default Promise<Token,CoreTokenException>	createAsync(Token token)	Creates a Token in the persistent store asynchronously.
Promise<Token,CoreTokenException>	createAsync(Token token, Options options)	Creates a Token in the persistent store asynchronously.
default PartialToken	delete(String tokenId)	Delete the Token from the store synchronously based on its id.
PartialToken	delete(String tokenId, Options options)	Delete the Token from the store synchronously based on its id.
default PartialToken	delete(Token token)	Delete the Token from the store synchronously.
default Promise<PartialToken,CoreTokenException>	deleteAsync(String tokenId)	Delete the Token from the store asynchronously based on its id.
Promise<PartialToken,CoreTokenException>	deleteAsync(String tokenId, Options options)	Delete the Token from the store asynchronously based on its id.
default Promise<PartialToken,CoreTokenException>	deleteAsync(Token token)	Deletes the Token from the store asynchronously.
default void	deleteOnQueryAsync(TokenFilter tokenFilter)	Performs an asynchronous query against the persistent store using the provided TokenFilter and then deletes the matching tokens from the store.
Promise<Collection<PartialToken>,CoreTokenException>	deleteOnQueryAsync(TokenFilter tokenFilter, Options options)	Performs an asynchronous query against the persistent store using the provided TokenFilter and then deletes the matching tokens from the store.
default PartialToken	patch(String tokenId, TokenType tokenType, TokenModifications modifications)	Patches a token which already exists in the persistent store with modifications.
PartialToken	patch(String tokenId, TokenType tokenType, TokenModifications modifications, Options options)	Patches a token which already exists in the persistent store with modifications.
default Promise<PartialToken,CoreTokenException>	patchAsync(String tokenId, TokenType tokenType, TokenModifications modifications)	Asynchronously patches a token which already exists in the persistent store with modifications.
Promise<PartialToken,CoreTokenException>	patchAsync(String tokenId, TokenType tokenType, TokenModifications modifications, Options options)	Asynchronously patches a token which already exists in the persistent store with modifications.
default Collection<Token>	query(TokenFilter filter)	Performs a synchronous query against the persistent store using the provided TokenFilter.
Collection<Token>	query(TokenFilter filter, Options options)	Performs a synchronous query against the persistent store using the provided TokenFilter.
default Token	read(String tokenId)	Read a Token from the persistent store synchronously.
Token	read(String tokenId, Options options)	Read a Token from the persistent store synchronously.
void	removeContinuousQueryListener(ContinuousQueryListener listener, TokenFilter filter)	Removes a ContinuousQueryListener from a specified TokenFilter.
void	stopContinuousQuery(TokenFilter filter)	Removes all ContinuousQueryListeners and stops a ContinuousQuery generated for a specified TokenFilter.
default Token	update(Token readState, Token updatedState)	Updates an existing Token in the store synchronously.
Token	update(Token readState, Token updatedState, Options options)	Updates an existing Token in the store synchronously.
default Promise<Token,CoreTokenException>	updateAsync(Token readState, Token updatedState)	Updates an existing Token in the store asynchronously.
Promise<Token,CoreTokenException>	updateAsync(Token readState, Token updatedState, Options options)	Updates an existing Token in the store asynchronously.
default Token	upsert(Token token)	Updates an existing Token in the store synchronously.
Token	upsert(Token token, Options options)	Updates an existing Token in the store synchronously.
default Promise<Token,CoreTokenException>	upsertAsync(Token token)	Updates an existing Token in the store asynchronously.
Promise<Token,CoreTokenException>	upsertAsync(Token token, Options options)	Updates an existing Token in the store asynchronously.

Method Detail

create

default Token create(Token token)
              throws CoreTokenException

Creates a Token in the persistent store synchronously.

Parameters:

token - Non null Token to create.

Returns:

The token that was created

Throws:

CoreTokenException - If there was an error while performing the different TokenBlobStrategys on the provided Token, or if the operation itself has failed.

create

Token create(Token token,
             Options options)
      throws CoreTokenException

Creates a Token in the persistent store synchronously.

Parameters:

token - Non null Token to create.

options - Non null set of Options to provide to backing CTS implementation.

Returns:

The token that was created

Throws:

CoreTokenException - If there was an error while performing the different TokenBlobStrategys on the provided Token, or if the operation itself has failed.

createAsync

default Promise<Token,CoreTokenException> createAsync(Token token)
                                                     throws CoreTokenException

Creates a Token in the persistent store asynchronously. The result of the operation (success/failure) is ignored.

Parameters:

token - Non null Token to create.

Returns:

A callable that will return the token that was created

Throws:

CoreTokenException - If there was an error while performing the different TokenBlobStrategys on the provided Token.

createAsync

Promise<Token,CoreTokenException> createAsync(Token token,
                                                    Options options)
                                             throws CoreTokenException

Creates a Token in the persistent store asynchronously. The result of the operation (success/failure) is ignored.

Parameters:

token - Non null Token to create.

options - Non null set of Options to provide to backing CTS implementation.

Returns:

A callable that will return the token that was created

Throws:

CoreTokenException - If there was an error while performing the different TokenBlobStrategys on the provided Token.

read

default Token read(String tokenId)
            throws CoreTokenException

Read a Token from the persistent store synchronously.

Parameters:

tokenId - The non null Token Id that the Token was created with.

Returns:

Null if there was no matching Token. Otherwise a fully populated Token will be returned.

Throws:

CoreTokenException - If there was an error while performing the different TokenBlobStrategys on the returned Token, or if the operation itself has failed.

read

Token read(String tokenId,
           Options options)
    throws CoreTokenException

Read a Token from the persistent store synchronously.

Parameters:

tokenId - The non null Token Id that the Token was created with.

options - Non null set of Options to provide to backing CTS implementation.

Returns:

Null if there was no matching Token. Otherwise a fully populated Token will be returned.

Throws:

CoreTokenException - If there was an error while performing the different TokenBlobStrategys on the returned Token, or if the operation itself has failed.

upsert

default Token upsert(Token token)
              throws CoreTokenException

Updates an existing Token in the store synchronously. If the Token does not exist in the store then a Token is created. If the Token did exist in the store then it is updated. Not all fields of the Token can be updated, see the Token class for more details.

Parameters:

token - Non null Token to update.

Returns:

The token that was updated

Throws:

CoreTokenException - If there was an error while performing the different TokenBlobStrategys on the provided Token, or if the operation itself has failed.

See Also:

Token.isFieldReadOnly(org.forgerock.am.cts.api.tokens.CoreTokenField)

upsert

Token upsert(Token token,
             Options options)
      throws CoreTokenException

Updates an existing Token in the store synchronously. If the Token does not exist in the store then a Token is created. If the Token did exist in the store then it is updated. Not all fields of the Token can be updated, see the Token class for more details.

Parameters:

token - Non null Token to update.

options - Non null set of Options to provide to backing CTS implementation.

Returns:

The token that was updated

Throws:

CoreTokenException - If there was an error while performing the different TokenBlobStrategys on the provided Token, or if the operation itself has failed.

See Also:

Token.isFieldReadOnly(org.forgerock.am.cts.api.tokens.CoreTokenField)

upsertAsync

default Promise<Token,CoreTokenException> upsertAsync(Token token)
                                                     throws CoreTokenException

Updates an existing Token in the store asynchronously. If the Token does not exist in the store then a Token is created. If the Token did exist in the store then it is updated. Not all fields of the Token can be updated, see the Token class for more details.

Parameters:

token - Non null Token to update.

Returns:

A callable that will return the token that was updated

Throws:

CoreTokenException - If there was an error while performing the different TokenBlobStrategys on the provided Token.

See Also:

Token.isFieldReadOnly(org.forgerock.am.cts.api.tokens.CoreTokenField)

upsertAsync

Promise<Token,CoreTokenException> upsertAsync(Token token,
                                                    Options options)
                                             throws CoreTokenException

Updates an existing Token in the store asynchronously. If the Token does not exist in the store then a Token is created. If the Token did exist in the store then it is updated. Not all fields of the Token can be updated, see the Token class for more details.

Parameters:

token - Non null Token to update.

options - Non null set of Options to provide to backing CTS implementation.

Returns:

A callable that will return the token that was updated

Throws:

CoreTokenException - If there was an error while performing the different TokenBlobStrategys on the provided Token.

See Also:

Token.isFieldReadOnly(org.forgerock.am.cts.api.tokens.CoreTokenField)

update

default Token update(Token readState,
                     Token updatedState)
              throws CoreTokenException

Updates an existing Token in the store synchronously. If the Token does not exist in the store then an error is thrown. Not all fields of the Token can be updated, see the Token class for more details.

Parameters:

readState - Non null Token state previously read.

updatedState - Non null Token state to save.

Returns:

The token that was updated

Throws:

CoreTokenException - If there was an error while performing the different TokenBlobStrategys on the provided Token, or if the operation itself has failed.

See Also:

Token.isFieldReadOnly(org.forgerock.am.cts.api.tokens.CoreTokenField)

update

Token update(Token readState,
             Token updatedState,
             Options options)
      throws CoreTokenException

Updates an existing Token in the store synchronously. If the Token does not exist in the store then an error is thrown. Not all fields of the Token can be updated, see the Token class for more details.

Parameters:

readState - Non null Token state previously read.

updatedState - Non null Token state to save.

options - Non null set of Options to provide to backing CTS implementation.

Returns:

The token that was updated

Throws:

CoreTokenException - If there was an error while performing the different TokenBlobStrategys on the provided Token, or if the operation itself has failed.

See Also:

Token.isFieldReadOnly(org.forgerock.am.cts.api.tokens.CoreTokenField)

updateAsync

default Promise<Token,CoreTokenException> updateAsync(Token readState,
                                                            Token updatedState)
                                                     throws CoreTokenException

Updates an existing Token in the store asynchronously. If the Token does not exist in the store then an error will be logged. Not all fields of the Token can be updated, see the Token class for more details.

Parameters:

readState - Non null Token state previously read.

updatedState - Non null Token state to save.

Returns:

A callable that will return the token that was updated

Throws:

CoreTokenException - If there was an error while performing the different TokenBlobStrategys on the provided Token, or if the operation itself has failed.

See Also:

Token.isFieldReadOnly(org.forgerock.am.cts.api.tokens.CoreTokenField)

updateAsync

Promise<Token,CoreTokenException> updateAsync(Token readState,
                                                    Token updatedState,
                                                    Options options)
                                             throws CoreTokenException

Updates an existing Token in the store asynchronously. If the Token does not exist in the store then an error will be logged. Not all fields of the Token can be updated, see the Token class for more details.

Parameters:

readState - Non null Token state previously read.

updatedState - Non null Token state to save.

options - Non null set of Options to provide to backing CTS implementation.

Returns:

A callable that will return the token that was updated

Throws:

CoreTokenException - If there was an error while performing the different TokenBlobStrategys on the provided Token, or if the operation itself has failed.

See Also:

Token.isFieldReadOnly(org.forgerock.am.cts.api.tokens.CoreTokenField)

delete

default PartialToken delete(Token token)
                     throws CoreTokenException

Delete the Token from the store synchronously.

Parameters:

token - Non null Token to be deleted from the store.

Returns:

The token that was deleted

Throws:

CoreTokenException - If the delete operation has failed.

deleteAsync

default Promise<PartialToken,CoreTokenException> deleteAsync(Token token)
                                                            throws CoreTokenException

Deletes the Token from the store asynchronously.

Parameters:

token - Non null Token to be deleted from the store.

Returns:

A callable that will return the token that was delete

Throws:

CoreTokenException

delete

default PartialToken delete(String tokenId)
                     throws CoreTokenException

Delete the Token from the store synchronously based on its id. Note: It is often more efficient to delete the token based on the Id if you already have this information, rather than reading the Token first before removing it.

Parameters:

tokenId - The non null Token Id of the token to remove.

Returns:

The token that was deleted

Throws:

CoreTokenException - If the delete operation has failed.

delete

PartialToken delete(String tokenId,
                    Options options)
             throws CoreTokenException

Delete the Token from the store synchronously based on its id. Note: It is often more efficient to delete the token based on the Id if you already have this information, rather than reading the Token first before removing it.

Parameters:

tokenId - The non null Token Id of the token to remove.

options - Non null set of Options to provide to backing CTS implementation.

Returns:

The token that was deleted

Throws:

CoreTokenException - If the delete operation has failed.

deleteAsync

default Promise<PartialToken,CoreTokenException> deleteAsync(String tokenId)
                                                            throws CoreTokenException

Delete the Token from the store asynchronously based on its id. Note: It is often more efficient to delete the token based on the Id if you already have this information, rather than reading the Token first before removing it.

Parameters:

tokenId - The non null Token Id of the token to remove.

Returns:

A callable that will return the token that was delete

Throws:

CoreTokenException

deleteAsync

Promise<PartialToken,CoreTokenException> deleteAsync(String tokenId,
                                                           Options options)
                                                    throws CoreTokenException

Delete the Token from the store asynchronously based on its id. Note: It is often more efficient to delete the token based on the Id if you already have this information, rather than reading the Token first before removing it.

Parameters:

tokenId - The non null Token Id of the token to remove.

options - Non null set of Options to provide to backing CTS implementation.

Returns:

A callable that will return the token that was delete

Throws:

CoreTokenException

patch

default PartialToken patch(String tokenId,
                           TokenType tokenType,
                           TokenModifications modifications)
                    throws CoreTokenException

Patches a token which already exists in the persistent store with modifications.

Parameters:

tokenId - The ID of the token to modify.

tokenType - The expected token type of the provided token id.

modifications - The set of modifications to apply.

Returns:

The patched PartialToken

Throws:

CoreTokenException - If there was an error while performing the different TokenBlobStrategys on the provided Token, or if the operation itself has failed.

patchAsync

default Promise<PartialToken,CoreTokenException> patchAsync(String tokenId,
                                                                  TokenType tokenType,
                                                                  TokenModifications modifications)
                                                           throws CoreTokenException

Asynchronously patches a token which already exists in the persistent store with modifications.

Parameters:

tokenId - The ID of the token to modify.

tokenType - The expected token type of the provided token id.

modifications - The set of modifications to apply.

Returns:

A callable that will return the patched PartialToken TokenBlobStrategys on the provided Token, or if the operation itself has failed.

Throws:

CoreTokenException - If there was an error while performing the different

patch

PartialToken patch(String tokenId,
                   TokenType tokenType,
                   TokenModifications modifications,
                   Options options)
            throws CoreTokenException

Patches a token which already exists in the persistent store with modifications.

Parameters:

tokenId - The ID of the token to modify.

tokenType - The expected token type of the provided token id.

modifications - The set of modifications to apply.

options - Non null set of Options to provide to backing CTS implementation.

Returns:

The patched PartialToken

Throws:

CoreTokenException - If there was an error while performing the different TokenBlobStrategys on the provided Token, or if the operation itself has failed.

patchAsync

Promise<PartialToken,CoreTokenException> patchAsync(String tokenId,
                                                          TokenType tokenType,
                                                          TokenModifications modifications,
                                                          Options options)
                                                   throws CoreTokenException

Asynchronously patches a token which already exists in the persistent store with modifications.

Parameters:

tokenId - The ID of the token to modify.

tokenType - The expected token type of the provided token id.

modifications - The set of modifications to apply.

options - Non null set of Options to provide to backing CTS implementation.

Returns:

A callable that will return the patched PartialToken

Throws:

CoreTokenException - If there was an error while performing the different TokenBlobStrategys on the provided Token, or if the operation itself has failed.

addContinuousQueryListener

void addContinuousQueryListener(ContinuousQueryListener listener,
                                TokenFilter filter)
                         throws CoreTokenException

Performs a continuous query against the persistent store using the provided TokenFilter. The filter is assembled by the TokenFilterBuilder which provides the options on how to turn the query being performed. The filter is appropriate to the underlying persistent layer type. The continuous query will begin and the listener will be attached.

Parameters:

listener - A listener which is capable of handling the results from this continuous query.

filter - Non null filter.

Throws:

CoreTokenException - If there was any error whilst performing the query.

See Also:

TokenFilter, TokenFilterBuilder

removeContinuousQueryListener

void removeContinuousQueryListener(ContinuousQueryListener listener,
                                   TokenFilter filter)
                            throws CoreTokenException

Removes a ContinuousQueryListener from a specified TokenFilter.

Parameters:

listener - A listener which is already associated with a running continuous query.

filter - Non null filter.

Throws:

CoreTokenException

See Also:

TokenFilter, TokenFilterBuilder

stopContinuousQuery

void stopContinuousQuery(TokenFilter filter)

Removes all ContinuousQueryListeners and stops a ContinuousQuery generated for a specified TokenFilter.

Parameters:

filter - Non null filter.

See Also:

ContinuousQueryListener, ContinuousQuery

query

default Collection<Token> query(TokenFilter filter)
                         throws CoreTokenException

Performs a synchronous query against the persistent store using the provided TokenFilter. The filter is assembled by the TokenFilterBuilder which provides the options on how to turn the query being performed.

Parameters:

filter - Non null filter.

Returns:

Non null, but maybe empty.

Throws:

CoreTokenException - If there was any error whilst performing the query.

See Also:

TokenFilter, TokenFilterBuilder

query

Collection<Token> query(TokenFilter filter,
                        Options options)
                 throws CoreTokenException

Performs a synchronous query against the persistent store using the provided TokenFilter. The filter is assembled by the TokenFilterBuilder which provides the options on how to turn the query being performed.

Parameters:

filter - Non null filter.

options - Non null set of Options to provide to backing CTS implementation.

Returns:

Non null, but maybe empty.

Throws:

CoreTokenException - If there was any error whilst performing the query.

See Also:

TokenFilter, TokenFilterBuilder

attributeQuery

default Collection<PartialToken> attributeQuery(TokenFilter tokenFilter)
                                         throws CoreTokenException

Performs a partial Token query against the store synchronously. That is, a query which is aimed at specific attributes of a Token, rather than whole Tokens. The return result will consist of PartialTokens for this purpose. This function is useful for example, finding all Token IDs that match a certain criteria.

Parameters:

tokenFilter - Non null TokenFilter, with the return attributes defined.

Returns:

Non null, but maybe empty.

Throws:

CoreTokenException - If there was any error whilst performing the query.

See Also:

TokenFilter.addReturnAttribute(org.forgerock.am.cts.api.tokens.CoreTokenField), TokenFilterBuilder, PartialToken

attributeQuery

Collection<PartialToken> attributeQuery(TokenFilter tokenFilter,
                                        Options options)
                                 throws CoreTokenException

Performs a partial Token query against the store synchronously. That is, a query which is aimed at specific attributes of a Token, rather than whole Tokens. The return result will consist of PartialTokens for this purpose. This function is useful for example, finding all Token IDs that match a certain criteria.

Parameters:

tokenFilter - Non null TokenFilter, with the return attributes defined.

options - Non null set of Options to provide to backing CTS implementation.

Returns:

Non null, but maybe empty.

Throws:

CoreTokenException - If there was any error whilst performing the query.

See Also:

TokenFilter.addReturnAttribute(org.forgerock.am.cts.api.tokens.CoreTokenField), TokenFilterBuilder, PartialToken

attributeQueryAsync

default Promise<Collection<PartialToken>,CoreTokenException> attributeQueryAsync(TokenFilter tokenFilter)
                                                                                throws CoreTokenException

Performs a partial Token query against the store synchronously. That is, a query which is aimed at specific attributes of a Token, rather than whole Tokens. The PartialTokens which are read will be passed to the provided handler.

Parameters:

tokenFilter - Non null TokenFilter, with the return attributes defined.

Throws:

CoreTokenException - If there was any error whilst performing the query.

See Also:

TokenFilter.addReturnAttribute(org.forgerock.am.cts.api.tokens.CoreTokenField), TokenFilterBuilder, PartialToken

attributeQueryAsync

Promise<Collection<PartialToken>,CoreTokenException> attributeQueryAsync(TokenFilter tokenFilter,
                                                                               Options options)
                                                                        throws CoreTokenException

Performs a partial Token query against the store synchronously. That is, a query which is aimed at specific attributes of a Token, rather than whole Tokens. The PartialTokens which are read will be passed to the provided handler.

Parameters:

tokenFilter - Non null TokenFilter, with the return attributes defined.

options - Non null set of Options to provide to backing CTS implementation.

Throws:

CoreTokenException - If there was any error whilst performing the query.

See Also:

TokenFilter.addReturnAttribute(org.forgerock.am.cts.api.tokens.CoreTokenField), TokenFilterBuilder, PartialToken

deleteOnQueryAsync

default void deleteOnQueryAsync(TokenFilter tokenFilter)
                         throws CoreTokenException

Performs an asynchronous query against the persistent store using the provided TokenFilter and then deletes the matching tokens from the store.

Parameters:

tokenFilter - Non null filter.

Throws:

CoreTokenException - If there was a problem queuing the task to be performed.

See Also:

TokenFilterBuilder

deleteOnQueryAsync

Promise<Collection<PartialToken>,CoreTokenException> deleteOnQueryAsync(TokenFilter tokenFilter,
                                                                              Options options)
                                                                       throws CoreTokenException

Performs an asynchronous query against the persistent store using the provided TokenFilter and then deletes the matching tokens from the store.

Parameters:

tokenFilter - Non null filter.

options - Non null set of Options to provide to backing CTS implementation.

Throws:

CoreTokenException - If there was a problem queuing the task to be performed.

See Also:

TokenFilterBuilder