Class BasicRegistry<T>

java.lang.Object
fr.inria.rules.integraal.api.external.registries.BasicRegistry<T>
Type Parameters:
T - The type of values stored in the registry.
Direct Known Subclasses:
IterableLabeledRegistry, LabeledRegistry
public class BasicRegistry<T> extends Object
A registry that stores values of type T with String keys.

The registry supports explicit key-value insertion and also provides automatic key generation using NamesGenerator. Duplicate keys are not allowed.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    UNDEFINED
    Special marker used to denote the absence of a user-defined key.

  • Constructor Summary

    Constructors
    Constructor
    Description
    BasicRegistry(String prefix)
    Constructs a BasicRegistry with a prefix used for autogenerated keys.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    clear()
    Removes all entries from the registry.
    boolean
    containsKey(String key)
    Returns true if the given key exists in the registry.
    boolean
    containsValue(T value)
    Returns true if the given value is present in the registry.
    Set<Map.Entry<String,T>>
    entrySet()
    Returns a set view of the entries contained in this registry.
    protected String
    generateKey(String key, T value)
    Generates the final key to use for storing the given value.
    T
    get(String key)
    Retrieves the unique value associated with the given key.
    protected String
    insert(String key, T value)
    Performs the actual insertion of the key-value pair into the map.
    boolean
    isEmpty()
    Returns true if the registry contains no entries.
    Set<String>
    keySet()
    Returns a set view of the keys contained in this registry.
    String
    put(String key, T value)
    Inserts a value into the registry under the given key, or generates a key if none is provided.
    String
    put(T value)
    Convenience method that inserts the given value using an auto-generated key.
    void
    putAll(BasicRegistry<? extends T> other)
    Adds all entries from another BasicRegistry into this registry.
    void
    putAll(Map<? extends String, ? extends T> other)
    Adds all entries from the given map to this registry, enforcing non-null keys/values and disallowing any duplicate keys.
    T
    remove(String key)
    Removes the entry associated with the given key.
    protected String
    rollback(String key, T value, RuntimeException e)
    Performs rollback actions when an exception occurs during the validation phase.
    int
    size()
    Returns the number of entries in the registry.
    protected void
    validateParams(String key, T value)
    Validates that the key-value pair can be safely inserted into the map.
    Collection<T>
    values()
    Returns a collection view of the values contained in this registry.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • UNDEFINED

      public static final String UNDEFINED
      Special marker used to denote the absence of a user-defined key.

      This value must be consistent with Labeled.NOLABEL to ensure that BasicRegistry and LabeledRegistry interpret "undefined" in the same way. Divergence would break key-label consistency logic.

      See Also:

  • Constructor Details

    • BasicRegistry

      public BasicRegistry(String prefix) throws NullPointerException
      Constructs a BasicRegistry with a prefix used for autogenerated keys.
      Parameters:
      prefix - the prefix to use for generated keys
      Throws:
      NullPointerException - when the prefix is null

  • Method Details

    • size

      public int size()
      Returns the number of entries in the registry.
      Returns:
      the number of key-value pairs stored

    • isEmpty

      public boolean isEmpty()
      Returns true if the registry contains no entries.
      Returns:
      true if empty, false otherwise

    • get

      public T get(String key) throws NoSuchElementException
      Retrieves the unique value associated with the given key.
      Parameters:
      key - the key to search for
      Returns:
      the unique value associated with the key
      Throws:
      NoSuchElementException - when no value has been found

    • containsKey

      public boolean containsKey(String key)
      Returns true if the given key exists in the registry.
      Parameters:
      key - the key to check
      Returns:
      true if the key exists, false otherwise

    • put

      public String put(String key, T value) throws IllegalStateException, NullPointerException, RegistryInsertionException
      Inserts a value into the registry under the given key, or generates a key if none is provided.

      If the specified key is UNDEFINED, a unique key will be generated using a NamesGenerator. Otherwise, the provided key is used. In both cases, the method ensures the key is not already associated with a different value.

      Unlike Map.put(Object, Object), this method returns the actual key used, not the value. This is intentional to allow retrieval of auto-generated keys.

      This method delegates to four other methods to fulfill its responsibilities:

      Parameters:
      key - the desired key to associate with the value. If UNDEFINED, a new key is auto-generated.
      value - the non-null value to insert into the registry
      Returns:
      the key used to store the value (either provided or generated)
      Throws:
      IllegalStateException - if:
      • the key already exists and is associated with a different value
      • a unique key could not be generated within the allowed attempts
      NullPointerException - if either key or value is null
      RegistryInsertionException - if the insertion fails despite passing validation. This should never occur under normal conditions.

    • generateKey

      protected String generateKey(String key, T value) throws IllegalStateException
      Generates the final key to use for storing the given value.

      If the provided key is not equal to UNDEFINED, it is returned unchanged. Otherwise, this method attempts to generate a unique key using the NamesGenerator, appending a timestamp and a configured prefix.

      The method ensures that the generated key does not collide with existing entries in the map. If a unique key cannot be found within MAX_RETRY attempts, an exception is thrown.

      Parameters:
      key - the initial key, possibly UNDEFINED
      value - the value to be stored
      Returns:
      a key guaranteed to be non-null and not already present in the map
      Throws:
      IllegalStateException - if a unique key could not be generated within allowed attempts

    • validateParams

      protected void validateParams(String key, T value) throws IllegalStateException
      Validates that the key-value pair can be safely inserted into the map.

      By default, this method checks that if the key already exists, it must be associated with the same object instance (reference equality).

      Subclasses can override this method to implement custom validation logic.

      Parameters:
      key - the key to validate
      value - the value to validate
      Throws:
      IllegalStateException - if the key already exists and is mapped to a different value

    • insert

      protected String insert(String key, T value) throws RegistryInsertionException
      Performs the actual insertion of the key-value pair into the map.

      This method should not perform validation, but rather assume the key and value have been verified already. The default implementation inserts the pair into the map and returns the key.

      Subclasses may override to perform custom insertion strategies.

      Parameters:
      key - the key to insert
      value - the value to associate with the key
      Returns:
      the key used for insertion
      Throws:
      RegistryInsertionException - if the insertion fails unexpectedly

    • rollback

      protected String rollback(String key, T value, RuntimeException e) throws RuntimeException
      Performs rollback actions when an exception occurs during the validation phase.

      This method is intended to undo any side effects or preparatory steps taken during validateParams(String, Object). For example, if validation reserves a resource or updates shared state, rollback should revert those changes.

      It is not called when insert(String, Object) fails; in that case, the RegistryInsertionException is propagated directly as insertion failures are considered unrecoverable and indicative of a deeper issue.

      The default implementation simply rethrows the exception with no rollback behavior. Subclasses can override this method to implement rollback semantics as needed.

      Parameters:
      key - the key involved in the operation
      value - the value that was being validated
      e - the exception that occurred during validation
      Returns:
      never returns normally; always rethrows an exception
      Throws:
      RuntimeException - the same or a new exception to propagate

    • put

      public String put(T value) throws IllegalStateException, NullPointerException
      Convenience method that inserts the given value using an auto-generated key.

      This is a shorthand for calling put(String, Object) with UNDEFINED as the key, triggering automatic key generation.

      Parameters:
      value - the value to insert; must not be null
      Returns:
      the generated key used for insertion
      Throws:
      NullPointerException - if the value is null
      IllegalStateException - if a unique key could not be generated or validation fails
      RegistryInsertionException - if insertion fails unexpectedly
      See Also:

    • putAll

      public void putAll(Map<? extends String, ? extends T> other) throws IllegalStateException, NullPointerException
      Adds all entries from the given map to this registry, enforcing non-null keys/values and disallowing any duplicate keys. This method performs a full validation before inserting anything, ensuring that: The input map is not null All keys and values in the map are non-null No key in the input map is already present in this registry If any of these checks fail, an appropriate exception is thrown and no changes are made to the registry.
      Parameters:
      other - a map of entries to add to the registry
      Throws:
      NullPointerException - if the map, any key, or any value is null
      IllegalStateException - if any key already exists in this registry for a distinct value

    • putAll

      public void putAll(BasicRegistry<? extends T> other) throws IllegalStateException, NullPointerException
      Adds all entries from another BasicRegistry into this registry.

      This is a convenience method that delegates to putAll(Map) while ensuring the same validations and rules apply.

      Parameters:
      other - another BasicRegistry containing entries to copy
      Throws:
      NullPointerException - if the registry or any of its keys/values is null
      IllegalStateException - if any key in other already exists in this registry with a distinct value

    • remove

      public T remove(String key) throws NoSuchElementException
      Removes the entry associated with the given key.
      Parameters:
      key - the key to remove
      Returns:
      the removed value
      Throws:
      NoSuchElementException - if the key is not present

    • clear

      public void clear()
      Removes all entries from the registry.

    • containsValue

      public boolean containsValue(T value)
      Returns true if the given value is present in the registry.
      Parameters:
      value - the value to check
      Returns:
      true if the value exists, false otherwise

    • keySet

      public Set<String> keySet()
      Returns a set view of the keys contained in this registry.
      Returns:
      a set of keys

    • values

      public Collection<T> values()
      Returns a collection view of the values contained in this registry.
      Returns:
      a collection of values

    • entrySet

      public Set<Map.Entry<String,T>> entrySet()
      Returns a set view of the entries contained in this registry.
      Returns:
      a set of key-value entries