org.keycloak.models.map.storage

## Interface MapStorage<K,V extends AbstractEntity<K>,M>

- Type Parameters:
    `K` - Type of the primary key. Various storages can
    `V` - Type of the stored values that contains all the data stripped of session state. In other words, in the entities there are only IDs and mostly primitive types / `String`, never references to `*Model` instances. See the `Abstract*Entity` classes in this module.
    `M` - Type of the `*Model` corresponding to the stored value, e.g. `UserModel`. This is used for filtering via model fields in `ModelCriteriaBuilder` which is necessary to abstract from physical layout and thus to support no-downtime upgrade.
  All Known Implementing Classes:
    ConcurrentHashMapStorage, UserSessionConcurrentHashMapStorage

      public interface MapStorage<K,V extends AbstractEntity<K>,M>

  Implementation of this interface interacts with a persistence storage storing various entities, e.g. users, realms. It contains basic object CRUD operations as well as bulk `read(org.keycloak.models.map.storage.ModelCriteriaBuilder)` and bulk `delete(org.keycloak.models.map.storage.ModelCriteriaBuilder)` operations, and operation for determining the number of the objects satisfying given criteria (`getCount(org.keycloak.models.map.storage.ModelCriteriaBuilder)`).
  Author:
    hmlnarik

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `V` | `create(K key, V value)` Creates an object in the store identified by given `key`.
    `ModelCriteriaBuilder<M>` | `createCriteriaBuilder()` Returns criteria builder for the storage engine.
    `MapKeycloakTransaction<K,V,M>` | `createTransaction(KeycloakSession session)` Creates a `MapKeycloakTransaction` object that tracks a new transaction related to this storage.
    `boolean` | `delete(K key)` Deletes object with the given `key` from the storage, if exists, no-op otherwise.
    `long` | `delete(ModelCriteriaBuilder<M> criteria)` Deletes objects that match the given criteria.
    `long` | `getCount(ModelCriteriaBuilder<M> criteria)` Returns the number of objects satisfying given `criteria` from the storage.
    `StringKeyConvertor<K>` | `getKeyConvertor()` Returns a `StringKeyConvertor` that is used to convert primary keys from `String` to internal representation and vice versa.
    `V` | `read(K key)` Returns object with the given `key` from the storage or `null` if object does not exist.
    `Stream<V>` | `read(ModelCriteriaBuilder<M> criteria)` Returns stream of objects satisfying given `criteria` from the storage.
    `V` | `update(K key, V value)` Updates the object with the given `id` in the storage if it already exists.

- - ### Method Detail

    - #### create

          V create(K key,
                   V value)

      Creates an object in the store identified by given `key`.
      Parameters:
        `key` - Key of the object as seen in the logical level
        `value` - Entity
      Returns:
        Reference to the entity created in the store
      Throws:
        `NullPointerException` - if object or its `key` is `null`

    - #### read

          V read(K key)

      Returns object with the given `key` from the storage or `null` if object does not exist.
      TODO: Consider returning `Optional<V>` instead.
      Parameters:
        `key` - Key of the object. Must not be `null`.
      Returns:
        See description
      Throws:
        `NullPointerException` - if the `key` is `null`

    - #### read

          Stream<V> read(ModelCriteriaBuilder<M> criteria)

      Returns stream of objects satisfying given `criteria` from the storage. The criteria are specified in the given criteria builder based on model properties.
      Parameters:
        `criteria` - Criteria filtering out the object, originally obtained from `createCriteriaBuilder()` method of this object. If `null`, it returns an empty stream.
      Returns:
        Stream of objects. Never returns `null`.
      Throws:
        `IllegalStateException` - If `criteria` is not compatible, i.e. has not been originally created by the `createCriteriaBuilder()` method of this object.

    - #### getCount

          long getCount(ModelCriteriaBuilder<M> criteria)

      Returns the number of objects satisfying given `criteria` from the storage. The criteria are specified in the given criteria builder based on model properties.
      Parameters:
        `criteria` -
      Returns:
        Number of objects. Never returns `null`.
      Throws:
        `IllegalStateException` - If `criteria` is not compatible, i.e. has not been originally created by the `createCriteriaBuilder()` method of this object.

    - #### update

          V update(K key,
                   V value)

      Updates the object with the given `id` in the storage if it already exists.
      Parameters:
        `key` - Primary key of the object to update
        `value` - Updated value
      Throws:
        `NullPointerException` - if object or its `id` is `null`

    - #### delete

          boolean delete(K key)

      Deletes object with the given `key` from the storage, if exists, no-op otherwise.
      Parameters:
        `key` -
      Returns:
        Returns `true` if the object has been deleted or result cannot be determined, `false` otherwise.

    - #### delete

          long delete(ModelCriteriaBuilder<M> criteria)

      Deletes objects that match the given criteria.
      Parameters:
        `criteria` -
      Returns:
        Number of removed objects (might return `-1` if not supported)
      Throws:
        `IllegalStateException` - If `criteria` is not compatible, i.e. has not been originally created by the `createCriteriaBuilder()` method of this object.

    - #### createCriteriaBuilder

          ModelCriteriaBuilder<M> createCriteriaBuilder()

      Returns criteria builder for the storage engine. The criteria are specified in the given criteria builder based on model properties.
      Note: While the criteria are formulated in terms of model properties, the storage engine may in turn process them into the best form that suits the underlying storage engine query language, e.g. to conditions on storage attributes or REST query parameters. If possible, do not delay filtering after the models are reconstructed from storage entities, in most cases this would be highly inefficient.
      Returns:
        See description. Never returns `null`

    - #### createTransaction

          MapKeycloakTransaction<K,V,M> createTransaction(KeycloakSession session)

      Creates a `MapKeycloakTransaction` object that tracks a new transaction related to this storage. In case of JPA or similar, the transaction object might be supplied by the container (via JTA) or shared same across storages accessing the same database within the same session; in other cases (e.g. plain map) a separate transaction handler might be created per each storage.
      Returns:
        See description. Never returns `null`

    - #### getKeyConvertor

          StringKeyConvertor<K> getKeyConvertor()

      Returns a `StringKeyConvertor` that is used to convert primary keys from `String` to internal representation and vice versa.
      Returns:
        See above. Never returns `null`.

Copyright © 2021 JBoss by Red Hat. All rights reserved.