com.evolveum.midpoint.repo.api
Interface RepositoryService

All Known Implementing Classes:
RepositoryCache, SqlRepositoryServiceImpl

public interface RepositoryService

Identity Repository Interface.

Status: public Stability: draft

Version:
0.3
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:

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:

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


Field Summary
static java.lang.String ADD_OBJECT
           
static java.lang.String CLAIM_TASK
           
static java.lang.String CLASS_NAME_WITH_DOT
           
static java.lang.String COUNT_OBJECTS
           
static java.lang.String DELETE_OBJECT
           
static java.lang.String GET_OBJECT
           
static java.lang.String LIST_ACCOUNT_SHADOW
           
static java.lang.String LIST_OBJECTS
           
static java.lang.String LIST_RESOURCE_OBJECT_SHADOWS
           
static java.lang.String MODIFY_OBJECT
           
static java.lang.String RELEASE_TASK
           
static java.lang.String SEARCH_OBJECTS
           
 
Method Summary
<T extends ObjectType>
java.lang.String
addObject(PrismObject<T> object, OperationResult parentResult)
          Add new object.
 void claimTask(java.lang.String oid, OperationResult parentResult)
          Deprecated. 
<T extends ObjectType>
int
countObjects(java.lang.Class<T> type, ObjectQuery query, OperationResult parentResult)
           
<T extends ObjectType>
void
deleteObject(java.lang.Class<T> type, java.lang.String oid, OperationResult parentResult)
          Deletes object with specified OID.
<T extends ObjectType>
PrismObject<T>
getObject(java.lang.Class<T> type, java.lang.String oid, OperationResult parentResult)
          Returns object for provided OID.
 PrismObject<UserType> listAccountShadowOwner(java.lang.String accountOid, OperationResult parentResult)
          Returns the User object representing owner of specified account (account shadow).
<T extends ResourceObjectShadowType>
java.util.List<PrismObject<T>>
listResourceObjectShadows(java.lang.String resourceOid, java.lang.Class<T> resourceObjectShadowType, OperationResult parentResult)
          Search for resource object shadows of a specified type that belong to the specified resource.
<T extends ObjectType>
void
modifyObject(java.lang.Class<T> type, java.lang.String oid, java.util.Collection<? extends ItemDelta> modifications, OperationResult parentResult)
          Modifies object using relative change description.
 void releaseTask(java.lang.String oid, OperationResult parentResult)
          Deprecated. 
<T extends ObjectType>
java.util.List<PrismObject<T>>
searchObjects(java.lang.Class<T> type, ObjectQuery query, OperationResult parentResult)
          Search for objects in the repository.
 

Field Detail

CLASS_NAME_WITH_DOT

static final java.lang.String CLASS_NAME_WITH_DOT

GET_OBJECT

static final java.lang.String GET_OBJECT

LIST_OBJECTS

static final java.lang.String LIST_OBJECTS

LIST_ACCOUNT_SHADOW

static final java.lang.String LIST_ACCOUNT_SHADOW

ADD_OBJECT

static final java.lang.String ADD_OBJECT

DELETE_OBJECT

static final java.lang.String DELETE_OBJECT

CLAIM_TASK

static final java.lang.String CLAIM_TASK

RELEASE_TASK

static final java.lang.String RELEASE_TASK

SEARCH_OBJECTS

static final java.lang.String SEARCH_OBJECTS

LIST_RESOURCE_OBJECT_SHADOWS

static final java.lang.String LIST_RESOURCE_OBJECT_SHADOWS

MODIFY_OBJECT

static final java.lang.String MODIFY_OBJECT

COUNT_OBJECTS

static final java.lang.String COUNT_OBJECTS
Method Detail

getObject

<T extends ObjectType> PrismObject<T> getObject(java.lang.Class<T> type,
                                                java.lang.String oid,
                                                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
java.lang.IllegalArgumentException - wrong OID format, etc.

addObject

<T extends ObjectType> java.lang.String addObject(PrismObject<T> object,
                                                  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
java.lang.IllegalArgumentException - wrong OID format, etc.

searchObjects

<T extends ObjectType> java.util.List<PrismObject<T>> searchObjects(java.lang.Class<T> type,
                                                                    ObjectQuery query,
                                                                    OperationResult parentResult)
                                                                throws SchemaException

Search for objects in the repository.

If no search criteria specified, list 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:
java.lang.IllegalArgumentException - wrong object type
SchemaException - unknown property used in search query

countObjects

<T extends ObjectType> int countObjects(java.lang.Class<T> type,
                                        ObjectQuery query,
                                        OperationResult parentResult)
                 throws SchemaException
Throws:
SchemaException

modifyObject

<T extends ObjectType> void modifyObject(java.lang.Class<T> type,
                                         java.lang.String oid,
                                         java.util.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
java.lang.IllegalArgumentException - wrong OID format, described change is not applicable

deleteObject

<T extends ObjectType> void deleteObject(java.lang.Class<T> type,
                                         java.lang.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
java.lang.IllegalArgumentException - wrong OID format, described change is not applicable

listAccountShadowOwner

PrismObject<UserType> listAccountShadowOwner(java.lang.String accountOid,
                                             OperationResult parentResult)
                                             throws ObjectNotFoundException

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
java.lang.IllegalArgumentException - wrong OID format

listResourceObjectShadows

<T extends ResourceObjectShadowType> java.util.List<PrismObject<T>> listResourceObjectShadows(java.lang.String resourceOid,
                                                                                              java.lang.Class<T> resourceObjectShadowType,
                                                                                              OperationResult parentResult)
                                                                                          throws ObjectNotFoundException

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
java.lang.IllegalArgumentException - wrong OID format

claimTask

@Deprecated
void claimTask(java.lang.String oid,
                          OperationResult parentResult)
               throws ObjectNotFoundException,
                      ConcurrencyException,
                      SchemaException
Deprecated. 

Claim a task.

The task can be claimed only by a single node in the cluster. Attempt to claim an already claimed task results in an exception. The claim must be atomic. It is kind of a lock for the system.

Parameters:
oid - task OID
parentResult - parentResult parent OperationResult (in/out)
Throws:
ObjectNotFoundException - the task with specified OID was not found
ConcurrencyException - attempt to claim already claimed task
SchemaException - error dealing with storage schema
java.lang.IllegalArgumentException - wrong OID format or a specified object is not a task

releaseTask

@Deprecated
void releaseTask(java.lang.String oid,
                            OperationResult parentResult)
                 throws ObjectNotFoundException,
                        SchemaException
Deprecated. 

Release a claimed task.

Note: Releasing a task that is not claimed is not an error. Warning should be logged, but this should not throw any exception.

Parameters:
oid - task OID
parentResult - parentResult parent OperationResult (in/out)
Throws:
ObjectNotFoundException - the task with specified OID was not found
SchemaException - error dealing with storage schema
java.lang.IllegalArgumentException - wrong OID format or a specified object is not a task


Copyright © 2012 evolveum. All Rights Reserved.