com.evolveum.midpoint.repo.api

Interface RepositoryService

All Known Implementing Classes:

RepositoryCache, SqlRepositoryServiceImpl, TestSqlRepositoryServiceImpl

public interface RepositoryService

Identity Repository Interface.

• Status: public
• Stability: stable

Version:

3.1.1

Author:

Radovan Semancik

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

Field Summary

Fields

Modifier and Type	Field and Description
static String	ADD_OBJECT
static String	ADVANCE_SEQUENCE
static String	CLAIM_TASK Deprecated.
static String	CLASS_NAME_WITH_DOT
static String	CLEANUP_TASKS
static String	COUNT_OBJECTS
static String	DELETE_OBJECT
static String	EXECUTE_QUERY_DIAGNOSTICS
static String	GET_OBJECT
static String	GET_VERSION
static String	LIST_ACCOUNT_SHADOW Deprecated.
static String	LIST_OBJECTS
static String	LIST_RESOURCE_OBJECT_SHADOWS
static String	MODIFY_OBJECT
static String	RELEASE_TASK Deprecated.
static String	RETURN_UNUSED_VALUES_TO_SEQUENCE
static String	SEARCH_CONTAINERS
static String	SEARCH_OBJECTS
static String	SEARCH_OBJECTS_ITERATIVE
static String	SEARCH_SHADOW_OWNER

Method Summary

Methods

Modifier and Type	Method and Description
<T extends com.evolveum.midpoint.xml.ns._public.common.common_3.ObjectType> String	addObject(PrismObject<T> object, RepoAddOptions options, OperationResult parentResult) Add new object.
long	advanceSequence(String oid, OperationResult parentResult) This operation is guaranteed to be atomic.
<T extends com.evolveum.midpoint.xml.ns._public.common.common_3.ObjectType> int	countObjects(Class<T> type, ObjectQuery query, OperationResult parentResult) Returns the number of objects that match specified criteria.
<T extends com.evolveum.midpoint.xml.ns._public.common.common_3.ObjectType> void	deleteObject(Class<T> type, String oid, OperationResult parentResult) Deletes object with specified OID.
RepositoryQueryDiagResponse	executeQueryDiagnostics(RepositoryQueryDiagRequest request, OperationResult result) A bit of hack - execute arbitrary query, e.g.
<T extends com.evolveum.midpoint.xml.ns._public.common.common_3.ObjectType> PrismObject<T>	getObject(Class<T> type, String oid, Collection<SelectorOptions<GetOperationOptions>> options, OperationResult parentResult) Returns object for provided OID.
RepositoryDiag	getRepositoryDiag() Provide repository run-time configuration and diagnostic information.
<T extends com.evolveum.midpoint.xml.ns._public.common.common_3.ObjectType> String	getVersion(Class<T> type, String oid, OperationResult parentResult) Returns object version for provided OID.
boolean	isAnySubordinate(String upperOrgOid, Collection<String> lowerObjectOids)
PrismObject<com.evolveum.midpoint.xml.ns._public.common.common_3.UserType>	listAccountShadowOwner(String accountOid, OperationResult parentResult) Deprecated.
<T extends com.evolveum.midpoint.xml.ns._public.common.common_3.ShadowType> List<PrismObject<T>>	listResourceObjectShadows(String resourceOid, Class<T> resourceObjectShadowType, OperationResult parentResult) Search for resource object shadows of a specified type that belong to the specified resource.
<T extends com.evolveum.midpoint.xml.ns._public.common.common_3.ObjectType> void	modifyObject(Class<T> type, String oid, Collection<? extends ItemDelta> modifications, OperationResult parentResult) Modifies object using relative change description.
<T extends com.evolveum.midpoint.xml.ns._public.common.common_3.ObjectType> void	modifyObject(Class<T> type, String oid, Collection<? extends ItemDelta> modifications, RepoModifyOptions options, OperationResult parentResult)
void	repositorySelfTest(OperationResult parentResult) Runs a short, non-descructive repository self test.
void	returnUnusedValuesToSequence(String oid, Collection<Long> unusedValues, OperationResult parentResult) The sequence may ignore the values, e.g.
<T extends Containerable> SearchResultList<T>	searchContainers(Class<T> type, ObjectQuery query, Collection<SelectorOptions<GetOperationOptions>> options, OperationResult parentResult) Search for "sub-object" structures, i.e.
<T extends com.evolveum.midpoint.xml.ns._public.common.common_3.ObjectType> SearchResultList<PrismObject<T>>	searchObjects(Class<T> type, ObjectQuery query, Collection<SelectorOptions<GetOperationOptions>> options, OperationResult parentResult) Search for objects in the repository.
<T extends com.evolveum.midpoint.xml.ns._public.common.common_3.ObjectType> SearchResultMetadata	searchObjectsIterative(Class<T> type, ObjectQuery query, ResultHandler<T> handler, Collection<SelectorOptions<GetOperationOptions>> options, boolean strictlySequential, OperationResult parentResult) Search for objects in the repository in an iterative fashion.
<F extends com.evolveum.midpoint.xml.ns._public.common.common_3.FocusType> PrismObject<F>	searchShadowOwner(String shadowOid, Collection<SelectorOptions<GetOperationOptions>> options, OperationResult parentResult) Returns the object representing owner of specified shadow.
void	testOrgClosureConsistency(boolean repairIfNecessary, OperationResult testResult) Checks a closure for consistency, repairing any problems found.

Field Detail

CLASS_NAME_WITH_DOT

static final String CLASS_NAME_WITH_DOT

GET_OBJECT

static final String GET_OBJECT

LIST_OBJECTS

static final String LIST_OBJECTS

LIST_ACCOUNT_SHADOW

@Deprecated
static final String LIST_ACCOUNT_SHADOW

Deprecated.

ADD_OBJECT

static final String ADD_OBJECT

DELETE_OBJECT

static final String DELETE_OBJECT

CLAIM_TASK

@Deprecated
static final String CLAIM_TASK

Deprecated.

RELEASE_TASK

@Deprecated
static final String RELEASE_TASK

Deprecated.

SEARCH_OBJECTS

static final String SEARCH_OBJECTS

SEARCH_CONTAINERS

static final String SEARCH_CONTAINERS

LIST_RESOURCE_OBJECT_SHADOWS

static final String LIST_RESOURCE_OBJECT_SHADOWS

MODIFY_OBJECT

static final String MODIFY_OBJECT

COUNT_OBJECTS

static final String COUNT_OBJECTS

GET_VERSION

static final String GET_VERSION

SEARCH_OBJECTS_ITERATIVE

static final String SEARCH_OBJECTS_ITERATIVE

CLEANUP_TASKS

static final String CLEANUP_TASKS

SEARCH_SHADOW_OWNER

static final String SEARCH_SHADOW_OWNER

ADVANCE_SEQUENCE

static final String ADVANCE_SEQUENCE

RETURN_UNUSED_VALUES_TO_SEQUENCE

static final String RETURN_UNUSED_VALUES_TO_SEQUENCE

EXECUTE_QUERY_DIAGNOSTICS

static final String EXECUTE_QUERY_DIAGNOSTICS

Method Detail

getObject

<T extends com.evolveum.midpoint.xml.ns._public.common.common_3.ObjectType> PrismObject<T> getObject(Class<T> type,
                                                                                                   String oid,
                                                                                                   Collection<SelectorOptions<GetOperationOptions>> options,
                                                                                                   OperationResult parentResult)
                                                                                                 throws ObjectNotFoundException,
                                                                                                        SchemaException

Returns object for provided OID. Must fail if object with the OID does not exists.

Parameters:

oid - OID of the object to get

parentResult - parent OperationResult (in/out)

Returns:

Object fetched from repository

Throws:

ObjectNotFoundException - requested object does not exist

SchemaException - error dealing with storage schema

IllegalArgumentException - wrong OID format, etc.

getVersion

<T extends com.evolveum.midpoint.xml.ns._public.common.common_3.ObjectType> String getVersion(Class<T> type,
                                                                                            String oid,
                                                                                            OperationResult parentResult)
                  throws ObjectNotFoundException,
                         SchemaException

Returns object version for provided OID. Must fail if object with the OID does not exists. This is a supposed to be a very lightweight and cheap operation. It is used to support efficient caching of expensive objects.

Parameters:

oid - OID of the object to get

parentResult - parent OperationResult (in/out)

Returns:

Object version

Throws:

ObjectNotFoundException - requested object does not exist

SchemaException - error dealing with storage schema

IllegalArgumentException - wrong OID format, etc.

addObject

<T extends com.evolveum.midpoint.xml.ns._public.common.common_3.ObjectType> String addObject(PrismObject<T> object,
                                                                                           RepoAddOptions options,
                                                                                           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).

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.

searchObjects

<T extends com.evolveum.midpoint.xml.ns._public.common.common_3.ObjectType> SearchResultList<PrismObject<T>> searchObjects(Class<T> type,
                                                                                                                         ObjectQuery query,
                                                                                                                         Collection<SelectorOptions<GetOperationOptions>> options,
                                                                                                                         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

paging - paging specification to limit operation result (optional)

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

searchContainers

<T extends Containerable> SearchResultList<T> searchContainers(Class<T> type,
                                                             ObjectQuery query,
                                                             Collection<SelectorOptions<GetOperationOptions>> options,
                                                             OperationResult parentResult)
                                                           throws SchemaException

Search for "sub-object" structures, i.e. containers. Currently, only one type of search is available: certification case search.

Type Parameters:

T -

Parameters:

type -

query -

options -

parentResult -

Returns:

Throws:

SchemaException

searchObjectsIterative

<T extends com.evolveum.midpoint.xml.ns._public.common.common_3.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.

Parameters:

query - search query

handler - result handler

strictlySequential - takes care not to skip any object nor to process objects more than once; currently requires paging NOT to be used - uses its own paging

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 com.evolveum.midpoint.xml.ns._public.common.common_3.ObjectType> int countObjects(Class<T> type,
                                                                                           ObjectQuery query,
                                                                                           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

paging - paging specification to limit operation result (optional)

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

isAnySubordinate

boolean isAnySubordinate(String upperOrgOid,
                       Collection<String> lowerObjectOids)
                         throws SchemaException

Throws:

SchemaException

modifyObject

<T extends com.evolveum.midpoint.xml.ns._public.common.common_3.ObjectType> void modifyObject(Class<T> type,
                                                                                            String oid,
                                                                                            Collection<? extends ItemDelta> modifications,
                                                                                            OperationResult parentResult)
                  throws ObjectNotFoundException,
                         SchemaException,
                         ObjectAlreadyExistsException

Modifies object using relative change description.

Must fail if user with provided OID does not exists. 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

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

modifyObject

<T extends com.evolveum.midpoint.xml.ns._public.common.common_3.ObjectType> void modifyObject(Class<T> type,
                                                                                            String oid,
                                                                                            Collection<? extends ItemDelta> modifications,
                                                                                            RepoModifyOptions options,
                                                                                            OperationResult parentResult)
                  throws ObjectNotFoundException,
                         SchemaException,
                         ObjectAlreadyExistsException

Throws:

ObjectNotFoundException

SchemaException

ObjectAlreadyExistsException

deleteObject

<T extends com.evolveum.midpoint.xml.ns._public.common.common_3.ObjectType> void deleteObject(Class<T> type,
                                                                                            String oid,
                                                                                            OperationResult parentResult)
                  throws ObjectNotFoundException

Deletes object with specified OID.

Must fail if object with specified OID does not exists. Should be atomic.

Parameters:

oid - OID of object to delete

parentResult - parent OperationResult (in/out)

Throws:

ObjectNotFoundException - specified object does not exist

IllegalArgumentException - wrong OID format, described change is not applicable

listAccountShadowOwner

@Deprecated
PrismObject<com.evolveum.midpoint.xml.ns._public.common.common_3.UserType> listAccountShadowOwner(String accountOid,
                                                                                                           OperationResult parentResult)
                                                                                                  throws ObjectNotFoundException

Deprecated.

Returns the User object representing owner of specified account (account shadow).

May return null if there is no owner specified for the account.

May only be called with OID of AccountShadow object.

Implements the backward "owns" association between account shadow and user. Forward association is implemented by property "account" of user object.

This is a "list" 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 "list" to indicate that there may be non-negligible overhead.

Parameters:

accountOid - OID of account shadow

parentResult - parentResult parent OperationResult (in/out)

Returns:

User object representing owner of specified account

Throws:

ObjectNotFoundException - specified object does not exist

IllegalArgumentException - wrong OID format

searchShadowOwner

<F extends com.evolveum.midpoint.xml.ns._public.common.common_3.FocusType> PrismObject<F> searchShadowOwner(String shadowOid,
                                                                                                          Collection<SelectorOptions<GetOperationOptions>> options,
                                                                                                          OperationResult parentResult)

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

listResourceObjectShadows

<T extends com.evolveum.midpoint.xml.ns._public.common.common_3.ShadowType> List<PrismObject<T>> listResourceObjectShadows(String resourceOid,
                                                                                                                         Class<T> resourceObjectShadowType,
                                                                                                                         OperationResult parentResult)
                                                                                                                       throws ObjectNotFoundException,
                                                                                                                              SchemaException

Search for resource object shadows of a specified type that belong to the specified resource.

Returns a list of such object shadows or empty list if nothing was found.

Implements the backward "has" association between resource and resource object shadows. Forward association is implemented by property "resource" of resource object shadow.

May only be called with OID of Resource object.

Parameters:

resourceOid - OID of resource definition (ResourceType)

parentResult - parentResult parent OperationResult (in/out)

Returns:

resource object shadows of a specified type from specified resource

Throws:

ObjectNotFoundException - specified object does not exist

SchemaException - found object is not type of ShadowType

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 -

Returns:

next unallocated counter value

Throws:

ObjectNotFoundException - the sequence does not exist

SchemaException - the sequence cannot produce a value (e.g. maximum counter reached)

returnUnusedValuesToSequence

void returnUnusedValuesToSequence(String oid,
                                Collection<Long> unusedValues,
                                OperationResult parentResult)
                                  throws ObjectNotFoundException,
                                         SchemaException

The sequence may ignore the values, e.g. if value re-use is disabled or when the list of unused values is full. In such a case the values will be ignored silently and no error is indicated.

Parameters:

oid -

unusedValues -

parentResult -

Throws:

ObjectNotFoundException

SchemaException

getRepositoryDiag

RepositoryDiag getRepositoryDiag()

Provide repository run-time configuration and diagnostic information.

repositorySelfTest

void repositorySelfTest(OperationResult parentResult)

Runs a short, non-descructive 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 -

result -

Returns: