Package com.evolveum.midpoint.repo.api

Interface RepositoryService

  • All Known Implementing Classes:
    RepositoryCache
    public interface RepositoryService

    Identity Repository Interface.

    • Status: public
    • Stability: stable

    This service provides repository for objects that are commonly found in identity management deployments. It is used for storage and retrieval of objects. It also supports modifications (relative changes), searching and basic coordination.

    Supported object types:

    • All object types from Common Schema
    • All object types from Identity Schema
    • All object types from IDM Model Schema

    Identity repository may add some kind of basic logic in addition to a pure storage of data. E.g. it may check referential consistency, validate schema, etc.

    The implementation may store the objects and properties in any suitable way and it is not required to check any schema beyond the basic common schema structures. However, the implementation MAY be able to check additional schema definitions, e.g. to check for mandatory and allowed properties and property types. This may be either explicit (e.g. implementation checking against provided XML schema) or implicit, conforming to the constraints of the underlying storage (e.g. LDAP schema enforced by underlying directory server). One way or another, the implementation may fail to store the objects that violate the schema. The method how the schemas are "loaded" to the implementation is not defined by this interface. This interface even cannot "reveal" the schema to its users (at least not now). Therefore clients of this interface must be prepared to handle schema violation errors.

    The implementation is not required to index the data or provide any other optimizations. This depends on the specific implementation, its configuration and the underlying storage system. Qualitative constraints (such as performance) are NOT defined by this interface definition.

    Naming Conventions

    operations should be named as <operation><objectType> e.g. addUser, modifyAccount, searchObjects. The operations that returns single object instance or works on single object should be named in singular (e.g. addUser). The operation that return multiple instances should be named in plural (e.g. listObjects). Operations names should be unified as well:

    • add, modify, delete - writing to repository, single object, need OID
    • get - retrieving single object by OID
    • list - returning all objects, no or fixed search criteria
    • search - returning subset of objects with flexible search criteria

    Notes

    The definition of this interface is somehow "fuzzy" at places. E.g. allowing schema-aware implementation but not mandating it, recommending to remove duplicates, but tolerating them, etc. The reason for this is to have better fit to the underlying storage mechanisms and therefore more efficient and simpler implementation. It may complicate the clients if the code needs to be generic and fit each and every implementation of this interface. However, such code will be quite rare. Most of the custom code will be developed to work on a specific storage (e.g. Oracle DB or LDAP) and therefore can be made slightly implementation-specific. Changing the storage in a running IDM system is extremely unlikely.

    TODO

    • TODO: Atomicity, consistency
    • TODO: security constraints
    • TODO: inherently thread-safe
    • TODO: note about distributed storage systems and weak/eventual consistency
    • TODO: task coordination

    Version:
    3.1.1
    Author:
    Radovan Semancik

    • Method Detail

      • addObject

        @NotNull
<T extends ObjectType> @NotNull String addObject​(@NotNull
                                                 @NotNull PrismObject<T> object,
                                                 RepoAddOptions options,
                                                 @NotNull
                                                 @NotNull OperationResult parentResult)
                                          throws ObjectAlreadyExistsException,
                                                 SchemaException
        Add new object. The OID provided in the input message may be empty. In that case the OID will be assigned by the implementation of this method and it will be provided as return value. This operation should fail if such object already exists (if object with the provided OID already exists). Overwrite is possible if RepoAddOptions.isOverwrite() is true, but only for the object of the same type. The operation may fail if provided OID is in an unusable format for the storage. Generating own OIDs and providing them to this method is not recommended for normal operation. Should be atomic. Should not allow creation of two objects with the same OID (even if created in parallel). The operation may fail if the object to be created does not conform to the underlying schema of the storage system or the schema enforced by the implementation. Note: no need for explicit type parameter here. The object parameter contains the information.
        Parameters:
        object - object to create
        parentResult - parent OperationResult (in/out)
        Returns:
        OID assigned to the created object
        Throws:
        ObjectAlreadyExistsException - object with specified identifiers already exists, cannot add
        SchemaException - error dealing with storage schema, e.g. schema violation
        IllegalArgumentException - wrong OID format, etc.

      • modifyObject

        @NotNull
<T extends ObjectType> @NotNull ModifyObjectResult<T> modifyObject​(@NotNull
                                                                   @NotNull Class<T> type,
                                                                   @NotNull
                                                                   @NotNull String oid,
                                                                   @NotNull
                                                                   @NotNull Collection<? extends ItemDelta<?,​?>> modifications,
                                                                   @NotNull
                                                                   @NotNull OperationResult parentResult)
                                                            throws ObjectNotFoundException,
                                                                   SchemaException,
                                                                   ObjectAlreadyExistsException

        Modifies object using relative change description.

        Must fail if user with provided OID does not exist. Must fail if any of the described changes cannot be applied. Should be atomic.

        If two or more modify operations are executed in parallel, the operations should be merged. In case that the operations are in conflict (e.g. one operation adding a value and the other removing the same value), the result is not deterministic.

        The operation may fail if the modified object does not conform to the underlying schema of the storage system or the schema enforced by the implementation.

        TODO: optimistic locking

        Note: the precondition is checked only if actual modification is going to take place (not e.g. if the list of modifications is empty).

        Parameters:
        parentResult - parent OperationResult (in/out)
        Throws:
        ObjectNotFoundException - specified object does not exist
        SchemaException - resulting object would violate the schema
        ObjectAlreadyExistsException - if resulting object would have name which already exists in another object of the same type
        IllegalArgumentException - wrong OID format, described change is not applicable

      • modifyObjectDynamically

        @Experimental
@NotNull
default <T extends ObjectType> @NotNull ModifyObjectResult<T> modifyObjectDynamically​(@NotNull
                                                                                      @NotNull Class<T> type,
                                                                                      @NotNull
                                                                                      @NotNull String oid,
                                                                                      @Nullable
                                                                                      @Nullable Collection<SelectorOptions<GetOperationOptions>> getOptions,
                                                                                      @NotNull
                                                                                      @NotNull RepositoryService.ModificationsSupplier<T> modificationsSupplier,
                                                                                      @Nullable
                                                                                      @Nullable RepoModifyOptions modifyOptions,
                                                                                      @NotNull
                                                                                      @NotNull OperationResult parentResult)
                                                                               throws ObjectNotFoundException,
                                                                                      SchemaException,
                                                                                      ObjectAlreadyExistsException
        Modifies an object dynamically. This means that the deltas are not provided by the caller, but computed by specified supplier, based on the current object state. This is to allow more complex atomic modifications with low overhead: Instead of calling getObject + compute deltas + modifyObject (with precondition that the object has not changed in the meanwhile) + repeating if the precondition fails, we now simply use modifyObjectDynamically that does all of this within a single DB transaction. BEWARE: Do not use unless really needed. Use modifyObject method instead.
        Parameters:
        type - Type of the object to modify
        oid - OID of the object to modify
        getOptions - Options to use when getting the original object state
        modificationsSupplier - Supplier of the modifications (item deltas) to be applied on the object
        modifyOptions - Options to be used when modifying the object
        parentResult - Operation result into which we put our result
        Throws:
        ObjectNotFoundException
        SchemaException
        ObjectAlreadyExistsException

      • searchReferences

        @NotNull
@NotNull SearchResultList<ObjectReferenceType> searchReferences​(@NotNull
                                                                @NotNull ObjectQuery query,
                                                                @Nullable
                                                                @Nullable Collection<SelectorOptions<GetOperationOptions>> options,
                                                                @NotNull
                                                                @NotNull OperationResult parentResult)
                                                         throws SchemaException
        Reference search - currently supporting roleMembershipRef and linkRef search. This returns reference objects extracted from the actual object(s) that own them, but selection of which (and cardinality of the result list) is based on a repository search. Query must not be null and its filter must be: * either a OWNER-BY filter, * or AND filter containing exactly one OWNER-BY filter and optionally one or more REF filters with empty path (self).
        Parameters:
        query - mandatory query with exactly one root OWNER-BY and additional REF filters
        Throws:
        SchemaException

      • searchObjects

        @NotNull
<T extends ObjectType> @NotNull SearchResultList<PrismObject<T>> searchObjects​(@NotNull
                                                                               @NotNull Class<T> type,
                                                                               @Nullable
                                                                               @Nullable ObjectQuery query,
                                                                               @Nullable
                                                                               @Nullable Collection<SelectorOptions<GetOperationOptions>> options,
                                                                               @NotNull
                                                                               @NotNull OperationResult parentResult)
                                                                        throws SchemaException

        Search for objects in the repository.

        If no search criteria specified, list of all objects of specified type is returned.

        Searches through all object types. Returns a list of objects that match search criteria.

        Returns empty list if object type is correct but there are no objects of that type. The ordering of the results is not significant and may be arbitrary unless sorting in the paging is used.

        Should fail if object type is wrong. Should fail if unknown property is specified in the query.

        Parameters:
        query - search query
        parentResult - parent OperationResult (in/out)
        Returns:
        all objects of specified type that match search criteria (subject to paging)
        Throws:
        IllegalArgumentException - wrong object type
        SchemaException - unknown property used in search query

      • countObjects

        <T extends ObjectType> int countObjects​(Class<T> type,
                                        ObjectQuery query,
                                        Collection<SelectorOptions<GetOperationOptions>> options,
                                        OperationResult parentResult)
                                 throws SchemaException

        Returns the number of objects that match specified criteria.

        If no search criteria specified, count of all objects of specified type is returned.

        Should fail if object type is wrong. Should fail if unknown property is specified in the query.

        Parameters:
        query - search query
        parentResult - parent OperationResult (in/out)
        Returns:
        count of objects of specified type that match search criteria (subject to paging)
        Throws:
        IllegalArgumentException - wrong object type
        SchemaException - unknown property used in search query

      • searchObjectsIterative

        <T extends ObjectType> SearchResultMetadata searchObjectsIterative​(Class<T> type,
                                                                   ObjectQuery query,
                                                                   ResultHandler<T> handler,
                                                                   Collection<SelectorOptions<GetOperationOptions>> options,
                                                                   boolean strictlySequential,
                                                                   OperationResult parentResult)
                                                            throws SchemaException
        Search for objects in the repository in an iterative fashion. Searches through all object types. Calls a specified handler for each object found. If no search criteria specified, list of all objects of specified type is returned. Searches through all object types. Returns a list of objects that match search criteria. Returns empty list if object type is correct but there are no objects of that type. The ordering of the results is not significant and may be arbitrary unless sorting in the paging is used. Should fail if object type is wrong. Should fail if unknown property is specified in the query. [NOTE] ==== New repository uses single reliable iteration method similar to strictly sequential paging and supports custom ordering (currently only one). New repository ignores strictlySequential parameter and related get options completely. In old repository there are three iteration methods (see IterationMethodType): - SINGLE_TRANSACTION: Fetches objects in single DB transaction. Not supported for all DBMSs. - SIMPLE_PAGING: Uses the "simple paging" method: takes objects (e.g.) numbered 0 to 49, then 50 to 99, then 100 to 149, and so on. The disadvantage is that if the order of objects is changed during operation (e.g. by inserting/deleting some of them) then some objects can be processed multiple times, where others can be skipped. - STRICTLY_SEQUENTIAL_PAGING: Uses the "strictly sequential paging" method: sorting returned objects by OID. This is (almost) reliable in such a way that no object would be skipped. However, custom paging cannot be used in this mode. If GetOperationOptions.iterationMethod is specified, it is used without any further considerations. Otherwise, the repository configuration determines whether to use SINGLE_TRANSACTION or a paging. In the latter case, strictlySequential flag determines between SIMPLE_PAGING (if false) and STRICTLY_SEQUENTIAL_PAGING (if true). If explicit GetOperationOptions.iterationMethod is not provided, and paging is prescribed, and strictlySequential flag is true and client-provided paging conflicts with the paging used by the iteration method, a warning is issued, and iteration method is switched to SIMPLE_PAGING. ==== Sources of conflicts: - ordering is specified - offset is specified (limit is not a problem)
        Parameters:
        query - search query
        handler - result handler
        strictlySequential - takes care not to skip any object nor to process objects more than once
        parentResult - parent OperationResult (in/out)
        Returns:
        summary information about the search result
        Throws:
        IllegalArgumentException - wrong object type
        SchemaException - unknown property used in search query

      • isDescendant

        <O extends ObjectType> boolean isDescendant​(PrismObject<O> object,
                                            String ancestorOrgOid)
                                     throws SchemaException
        Returns `true` if the `object` is under the organization identified with `ancestorOrgOid`. The `object` can either be an Org or any other object in which case all the targets of its `parentOrgRefs` are tested. Examples (from the perspective of the first parameter): * User belonging to Org with `ancestorOrgOid` returns true. * Organization under Org with `ancestorOrgOid` returns true (in any depth). * User belonging to Org under another Org with `ancestorOrgOid` returns true (any depth). * Organization with `ancestorOrgOid` returns `false`, as it is not considered to be its own descendant.
        Parameters:
        object - object of any type tested to belong under Org with `ancestorOrgOid`
        ancestorOrgOid - identifier of ancestor organization
        Throws:
        SchemaException

      • isAncestor

        <O extends ObjectType> boolean isAncestor​(PrismObject<O> object,
                                          String descendantOrgOid)
                                   throws SchemaException
        Returns `true` if the `object` is above organization identified with `descendantOrgOid`. Despite type parameter, only `PrismObject` can return `true`. Examples (from the perspective of the first parameter): * Any other type than `Org` used for `object` returns `false`. * Organization being a parent of another organization with `descendantOrgOid` returns `true`. This means that Organization with `descendantOrgOid` has `parentOrgRef` to `object`. * Organization higher in the organization hierarchy than Org with `descendantOrgOid` returns `true`, for any number of levels between them as long as it's possible to traverse from Org identified by `descendantOrgOid` to `object` using any number of `parentOrgRefs`. * Organization with `descendantOrgOid` returns `false`, as it is not considered to be its own ancestor.
        Parameters:
        object - potential ancestor organization
        descendantOrgOid - identifier of potential descendant organization
        Throws:
        SchemaException

      • searchShadowOwner

        @Deprecated
default <F extends FocusType> PrismObject<F> searchShadowOwner​(String shadowOid,
                                                               Collection<SelectorOptions<GetOperationOptions>> options,
                                                               OperationResult parentResult)
        Deprecated.
        TODO: we want to remove this in midScale

        Returns the object representing owner of specified shadow.

        Implements the backward "owns" association between account shadow and user. Forward association is implemented by linkRef reference in subclasses of FocusType.

        Returns null if there is no owner for the shadow.

        This is a "search" operation even though it may return at most one owner. However the operation implies searching the repository for an owner, which may be less efficient that following a direct association. Hence it is called "search" to indicate that there may be non-negligible overhead.

        This method should not die even if the specified shadow does not exist. Even if the shadow is gone, it still may be used in some linkRefs. This method should be able to find objects with such linkRefs otherwise we will not be able to do proper cleanup.

        Parameters:
        shadowOid - OID of shadow
        parentResult - parentResult parent OperationResult (in/out)
        Returns:
        Object representing owner of specified account (subclass of FocusType)
        Throws:
        IllegalArgumentException - wrong OID format

      • advanceSequence

        long advanceSequence​(String oid,
                     OperationResult parentResult)
              throws ObjectNotFoundException,
                     SchemaException
        This operation is guaranteed to be atomic. If two threads or even two nodes request a value from the same sequence at the same time then different values will be returned.
        Parameters:
        oid - sequence OID
        parentResult - Operation result
        Returns:
        next unallocated counter value
        Throws:
        ObjectNotFoundException - the sequence does not exist
        SchemaException - the sequence cannot produce a value (e.g. maximum counter reached)

      • getRepositoryDiag

        RepositoryDiag getRepositoryDiag()
        Provide repository run-time configuration and diagnostic information. May execute diagnostic query on the database.

      • isNative

        default boolean isNative()

      • supports

        boolean supports​(@NotNull
                 @NotNull Class<? extends ObjectType> type)
        Returns `true` if the given object type is supported.

      • supportsMarks

        default boolean supportsMarks()

      • repositorySelfTest

        void repositorySelfTest​(OperationResult parentResult)
        Runs a short, non-destructive repository self test. This methods should never throw a (checked) exception. All the results should be recorded under the provided result structure (including fatal errors).

        This should implement ONLY self-tests that are IMPLEMENTATION-SPECIFIC. It must not implement self-tests that are generic and applies to all repository implementations. Such self-tests must be implemented in higher layers.

        If the repository has no self-tests then the method should return immediately without changing the result structure. It must not throw an exception in this case.

      • testOrgClosureConsistency

        void testOrgClosureConsistency​(boolean repairIfNecessary,
                               OperationResult testResult)
        Checks a closure for consistency, repairing any problems found. This methods should never throw a (checked) exception. All the results should be in the returned result structure (including fatal errors).

        The current implementation expects closure to be of reasonable size - so it could be fetched into main memory as well as recomputed online (perhaps up to ~250K entries). In future, this method will be reimplemented.

        BEWARE, this method locks out the M_ORG_CLOSURE table, so org-related operations would wait until it completes.

        TODO this method is SQL service specific; it should be generalized/fixed somehow.

      • executeQueryDiagnostics

        RepositoryQueryDiagResponse executeQueryDiagnostics​(RepositoryQueryDiagRequest request,
                                                    OperationResult result)
        A bit of hack - execute arbitrary query, e.g. hibernate query in case of SQL repository. Use with all the care!
        Parameters:
        request - Diagnostics request
        result - Operation result
        Returns:
        diagnostics response

      • createAndRegisterConflictWatcher

        ConflictWatcher createAndRegisterConflictWatcher​(@NotNull
                                                 @NotNull String oid)

      • unregisterConflictWatcher

        void unregisterConflictWatcher​(ConflictWatcher watcher)