Package dev.getelements.elements.sdk.dao

Interface UniqueCodeDao

All Known Implementing Classes:
MongoUniqueCodeDao
public interface UniqueCodeDao
DAO for generating unique codes with a given prefix. The underlying implementation is responsible for ensuring that the generated codes are unique within the specified timeout period or until the code is explicitly released. The codes intended to be easily to read and recall, so the default length is kept short (4 characters). If a higher degree of uniqueness is required, the length can be increased. The implementation must generate codes that are unambiguous and avoid characters that can be easily confused (e.g., 'O' and '0', 'I' and '1'). Additionally, the generated codes avoid offensive or inappropriate combinations suitable for all audiences. Even for games or products that are intended for adult audiences, the codes should remain appropriate as the goal is to facilitate easy sharing and recall among users.
Author:
patrickt

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final record 
    UniqueCodeDao.GenerationParameters
    Generation parameters for generating unique codes.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    DEFAULT_CODE_LENGTH
    The default length for generated codes.
    static final long
    DEFAULT_LINGER_MS
    The default timeout for which the generated code will linger after being released. 5 minutes in milliseconds.
    static final int
    DEFAULT_MAX_GENERATION_ATTEMPTS
    The default maximum number of attempts to generate a unique code before giving up.
    static final long
    DEFAULT_TIMEOUT_MS
    The default timeout for which the generated code should remain unique. 1 hour in milliseconds.

  • Method Summary

    Modifier and Type
    Method
    Description
    Optional<UniqueCode>
    findCode(String code)
    Finds the UniqueCode object for the specified code.
    default UniqueCode
    generateCode()
    TGenerates a unique code with the default length and timeout.
    UniqueCode
    generateCode(UniqueCodeDao.GenerationParameters parameters)
    Generates a unique code with the default length.
    default UniqueCode
    getCode(String code)
    Gets the UniqueCode object for the specified code.
    default void
    releaseCode(String code)
    Releases the specified code, allowing it to be reused after a short linger period.
    default void
    resetTimeout(String code)
    Resets the timeout for the specified code, extending its uniqueness period.
    boolean
    tryReleaseCode(String code)
    Attempts to release the specified code within the given timeout period.
    boolean
    tryResetTimeout(String code)
    Tries to reset the timeout for the specified code, extending its uniqueness period.

  • Field Details

    • DEFAULT_CODE_LENGTH

      static final int DEFAULT_CODE_LENGTH
      The default length for generated codes.
      See Also:

    • DEFAULT_LINGER_MS

      static final long DEFAULT_LINGER_MS
      The default timeout for which the generated code will linger after being released. 5 minutes in milliseconds.
      See Also:

    • DEFAULT_TIMEOUT_MS

      static final long DEFAULT_TIMEOUT_MS
      The default timeout for which the generated code should remain unique. 1 hour in milliseconds.
      See Also:

    • DEFAULT_MAX_GENERATION_ATTEMPTS

      static final int DEFAULT_MAX_GENERATION_ATTEMPTS
      The default maximum number of attempts to generate a unique code before giving up.
      See Also:

  • Method Details

    • generateCode

      default UniqueCode generateCode()
      TGenerates a unique code with the default length and timeout.
      Returns:
      the generated unique code

    • generateCode

      UniqueCode generateCode(UniqueCodeDao.GenerationParameters parameters)
      Generates a unique code with the default length.
      Parameters:
      parameters - the generation parameters
      Returns:
      the generated unique code

    • getCode

      default UniqueCode getCode(String code)
      Gets the UniqueCode object for the specified code. Can be used to check if a code is still valid.
      Parameters:
      code - the code
      Returns:
      the UniqueCode object, never null
      Throws:
      UniqueCodeNotFoundException - if the code is not found

    • findCode

      Optional<UniqueCode> findCode(String code)
      Finds the UniqueCode object for the specified code.
      Parameters:
      code - the code or an empty Optional if not found
      Returns:
      the UniqueCode object wrapped in an Optional

    • resetTimeout

      default void resetTimeout(String code)
      Resets the timeout for the specified code, extending its uniqueness period.
      Parameters:
      code - the code to reset the timeout for

    • tryResetTimeout

      boolean tryResetTimeout(String code)
      Tries to reset the timeout for the specified code, extending its uniqueness period. If the code has been released, then this will have no effect.
      Parameters:
      code - the code
      Returns:
      true if the timeout was successfully reset, false otherwise

    • releaseCode

      default void releaseCode(String code)
      Releases the specified code, allowing it to be reused after a short linger period.
      Parameters:
      code - the code

    • tryReleaseCode

      boolean tryReleaseCode(String code)
      Attempts to release the specified code within the given timeout period. Once released, the code can be reused after a short linger period.
      Parameters:
      code - the code
      Returns:
      true if the code was successfully released, false otherwise