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:

  • Method Details

    • 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.

    • 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:

    • 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:

    • 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:

    • 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:

    • 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)
      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

    • 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)
      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

    • deleteAsync

      Promise<PartialToken,CoreTokenException> deleteAsync(String tokenId, Options options)
      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

    • 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.

    • 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.

    • 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:

    • 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:

    • stopContinuousQuery

      void stopContinuousQuery(TokenFilter filter)
      Removes all ContinuousQueryListeners and stops a ContinuousQuery generated for a specified TokenFilter.
      Parameters:
      filter - Non null filter.
      See Also:

    • 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:

    • 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:

    • 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:

    • 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:

    • deleteOnQuery

      default Collection<PartialToken> deleteOnQuery(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:

    • deleteOnQuery

      Collection<PartialToken> deleteOnQuery(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: