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

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