com.evolveum.midpoint.provisioning.api
Interface ProvisioningService

All Known Implementing Classes:
ProvisioningServiceImpl

public interface ProvisioningService

Provisioning Service Interface.

Status: public Stability: DRAFT, some changes are likely

Version:
0.3
Author:
Radovan Semancik

This service retrieves information about resource objects and resources and handles changes to resource objects. Implementations of this interface will apply the changes to accounts, groups and other similar objects to the target resources. It also provides information about connectors and similar configuration of access to the resources.

Supported object types:

Supported extra data types:

TODO: better documentation


Field Summary
static java.lang.String TEST_CONNECTION_CONNECTOR_CONNECTION_OPERATION
          Check whether the connector can be initialized.
static java.lang.String TEST_CONNECTION_CONNECTOR_INIT_OPERATION
          Check whether the connector can be initialized.
static java.lang.String TEST_CONNECTION_CONNECTOR_SANITY_OPERATION
          Check whether the connector can be used to fetch some mandatory objects (e.g.
static java.lang.String TEST_CONNECTION_CONNECTOR_SCHEMA_OPERATION
          Check whether the connector can fetch and process resource schema.
static java.lang.String TEST_CONNECTION_CONNECTOR_VALIDATION_OPERATION
          Check whether the configuration is valid e.g.
static java.lang.String TEST_CONNECTION_OPERATION
          Prefix for all the "standardized" test resource tests.
 
Method Summary
<T extends ObjectType>
java.lang.String
addObject(T object, ScriptsType scripts, OperationResult parentResult)
          Add new object.
<T extends ObjectType>
void
deleteObject(java.lang.Class<T> type, java.lang.String oid, ScriptsType scripts, OperationResult parentResult)
          Deletes object with specified OID.
 java.util.Set<ConnectorType> discoverConnectors(ConnectorHostType hostType, OperationResult parentResult)
          Discovers local or remote connectors.
<T extends ObjectType>
T
getObject(java.lang.Class<T> type, java.lang.String oid, PropertyReferenceListType resolve, OperationResult parentResult)
          Returns object for provided OID.
 PropertyAvailableValuesListType getPropertyAvailableValues(java.lang.String oid, PropertyReferenceListType properties, OperationResult parentResult)
          Returns list of available values for specified properties.
<T extends ObjectType>
ResultList<T>
listObjects(java.lang.Class<T> objectType, PagingType paging, OperationResult parentResult)
          Returns all objects of specified type that are available to the implementation.
 ResultList<? extends ResourceObjectShadowType> listResourceObjects(java.lang.String resourceOid, javax.xml.namespace.QName objectClass, PagingType paging, OperationResult parentResult)
          Lists resource objects.
<T extends ObjectType>
void
modifyObject(java.lang.Class<T> type, ObjectModificationType objectChange, ScriptsType scripts, OperationResult parentResult)
          Modifies object using relative change description.
 void postInit(OperationResult parentResult)
          Finish initialization of provisioning system.
<T extends ObjectType>
ResultList<T>
searchObjects(java.lang.Class<T> type, QueryType query, PagingType paging, OperationResult parentResult)
          Search for objects.
 void searchObjectsIterative(QueryType query, PagingType paging, ResultHandler handler, OperationResult parentResult)
          Search for objects iteratively.
 int synchronize(java.lang.String resourceOid, Task task, OperationResult parentResult)
          Collect external changes on a resource and call the business logic with the accumulated change data.
 OperationResult testResource(java.lang.String resourceOid)
          Test the resource connection and basic resource connector functionality.
 

Field Detail

TEST_CONNECTION_OPERATION

static final java.lang.String TEST_CONNECTION_OPERATION
Prefix for all the "standardized" test resource tests.


TEST_CONNECTION_CONNECTOR_VALIDATION_OPERATION

static final java.lang.String TEST_CONNECTION_CONNECTOR_VALIDATION_OPERATION
Check whether the configuration is valid e.g. well-formed XML, valid with regard to schema, etc.


TEST_CONNECTION_CONNECTOR_INIT_OPERATION

static final java.lang.String TEST_CONNECTION_CONNECTOR_INIT_OPERATION
Check whether the connector can be initialized. E.g. connector classes can be loaded, it can process configuration, etc.


TEST_CONNECTION_CONNECTOR_CONNECTION_OPERATION

static final java.lang.String TEST_CONNECTION_CONNECTOR_CONNECTION_OPERATION
Check whether the connector can be initialized. E.g. connector classes can be loaded, it can process configuration, etc.


TEST_CONNECTION_CONNECTOR_SCHEMA_OPERATION

static final java.lang.String TEST_CONNECTION_CONNECTOR_SCHEMA_OPERATION
Check whether the connector can fetch and process resource schema.


TEST_CONNECTION_CONNECTOR_SANITY_OPERATION

static final java.lang.String TEST_CONNECTION_CONNECTOR_SANITY_OPERATION
Check whether the connector can be used to fetch some mandatory objects (e.g. fetch a "root" user).

Method Detail

getObject

<T extends ObjectType> T getObject(java.lang.Class<T> type,
                                   java.lang.String oid,
                                   PropertyReferenceListType resolve,
                                   OperationResult parentResult)
                               throws ObjectNotFoundException,
                                      CommunicationException,
                                      SchemaException
Returns object for provided OID. Must fail if object with the OID does not exists. Resource Object Shadows: The resource object shadow attributes may be retrieved from the local database, directly form the resource or a combination of both. The retrieval may fail due to resource failure, network failure or similar external cases. The retrieval may also take relatively long time (e.g. until it times out).

Parameters:
type - the type (class) of object to get
oid - OID of the object to get
resolve - list of properties to resolve in the fetched object
result - parent OperationResult (in/out)
Returns:
Object fetched from repository and/or resource
Throws:
ObjectNotFoundException - requested object does not exist
CommunicationException - error communicating with the resource
SchemaException - error dealing with resource schema
java.lang.IllegalArgumentException - wrong OID format, etc.
GenericConnectorException - unknown connector framework error

addObject

<T extends ObjectType> java.lang.String addObject(T object,
                                                  ScriptsType scripts,
                                                  OperationResult parentResult)
                           throws ObjectAlreadyExistsException,
                                  SchemaException,
                                  CommunicationException,
                                  ObjectNotFoundException
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.

Parameters:
object - object to create
scripts - scripts to execute before/after the operation
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 resource schema, e.g. schema violation
CommunicationException - error communicating with the resource
ObjectNotFoundException - appropriate connector object was not found
java.lang.IllegalArgumentException - wrong OID format, etc.
GenericConnectorException - unknown connector framework error

synchronize

int synchronize(java.lang.String resourceOid,
                Task task,
                OperationResult parentResult)
                throws ObjectNotFoundException,
                       CommunicationException,
                       SchemaException
Collect external changes on a resource and call the business logic with the accumulated change data. This method will be invoked by scheduler/sync thread. TODO: Better description

Parameters:
oid - OID of the resource for which to attempt synchronization
parentResult - parent OperationResult (in/out)
Returns:
the number of processed changes
Throws:
ObjectNotFoundException - specified resource definition (OID) does not exist
CommunicationException - error communicating with the resource
SchemaException - error dealing with resource schema
GenericConnectorException - unknown connector framework error

listObjects

<T extends ObjectType> ResultList<T> listObjects(java.lang.Class<T> objectType,
                                                 PagingType paging,
                                                 OperationResult parentResult)
Returns all objects of specified type that are available to the implementation. This can be considered as a simplified search operation. Returns empty list if object type is correct but there are no objects of that type. Should fail if object type is wrong.

Parameters:
objectType -
paging - paging specification to limit operation result (optional)
parentResult - parent OperationResult (in/out)
Returns:
all objects of specified type (subject to paging)
Throws:
java.lang.IllegalArgumentException - wrong object type
GenericConnectorException - unknown connector framework error

searchObjects

<T extends ObjectType> ResultList<T> searchObjects(java.lang.Class<T> type,
                                                   QueryType query,
                                                   PagingType paging,
                                                   OperationResult parentResult)
                                               throws SchemaException,
                                                      ObjectNotFoundException,
                                                      CommunicationException
Search for objects. 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. 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
GenericConnectorException - unknown connector framework error
SchemaException - unknown property used in search query
ObjectNotFoundException
CommunicationException

searchObjectsIterative

void searchObjectsIterative(QueryType query,
                            PagingType paging,
                            ResultHandler handler,
                            OperationResult parentResult)
                            throws SchemaException,
                                   ObjectNotFoundException,
                                   CommunicationException
Search for objects iteratively. Searches through all object types. Calls a specified handler for each object found. If nothing is found the handler is not called and the operation returns. 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)
handler - result handler
Throws:
java.lang.IllegalArgumentException - wrong object type
GenericConnectorException - unknown connector framework error
SchemaException - unknown property used in search query
ObjectNotFoundException - appropriate connector object was not found
CommunicationException

modifyObject

<T extends ObjectType> void modifyObject(java.lang.Class<T> type,
                                         ObjectModificationType objectChange,
                                         ScriptsType scripts,
                                         OperationResult parentResult)
                  throws ObjectNotFoundException,
                         SchemaException,
                         CommunicationException
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:
objectChange - specification of object changes
scripts - scripts that should be executed before of after operation
parentResult - parent OperationResult (in/out)
Throws:
ObjectNotFoundException - specified object does not exist
SchemaException - resulting object would violate the schema
java.lang.IllegalArgumentException - wrong OID format, described change is not applicable
GenericConnectorException - unknown connector framework error
CommunicationException

deleteObject

<T extends ObjectType> void deleteObject(java.lang.Class<T> type,
                                         java.lang.String oid,
                                         ScriptsType scripts,
                                         OperationResult parentResult)
                  throws ObjectNotFoundException,
                         CommunicationException,
                         SchemaException

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
scripts - scripts that should be executed before of after operation
parentResult - parent OperationResult (in/out)
Throws:
ObjectNotFoundException - specified object does not exist
java.lang.IllegalArgumentException - wrong OID format, described change is not applicable
GenericConnectorException - unknown connector framework error
CommunicationException
SchemaException

getPropertyAvailableValues

PropertyAvailableValuesListType getPropertyAvailableValues(java.lang.String oid,
                                                           PropertyReferenceListType properties,
                                                           OperationResult parentResult)
                                                           throws ObjectNotFoundException
Returns list of available values for specified properties. The returned values can be used as valid values for properties of the specific object. The provided values can be used e.g. for listing them in GUI list boxes, for early validation (pre-validation), displaying help messages, auto-complete, etc. In case the list of available values is too big or it is not available, the empty list should be returned, setting the "closed" flag to false.

Parameters:
oid - OID of the object for which to determine values
properties - list of properties for which to determine values
parentResult - parentResult parent OperationResult (in/out)
Returns:
list of available values
Throws:
ObjectNotFoundException - specified object does not exist
java.lang.IllegalArgumentException - wrong OID format
GenericConnectorException - unknown connector framework error

testResource

OperationResult testResource(java.lang.String resourceOid)
                             throws ObjectNotFoundException
Test the resource connection and basic resource connector functionality. This operation will NOT throw exception in case the resource connection fails. It such case it will indicate the failure in the return message, but the operation itself succeeds. The operations fails only if the provided arguments are wrong, in case of system error, system misconfiguration, etc.

Parameters:
resourceOid - OID of resource to test
Returns:
results of executed tests
Throws:
ObjectNotFoundException - specified object does not exist
java.lang.IllegalArgumentException - wrong OID format
GenericConnectorException - unknown connector framework error

discoverConnectors

java.util.Set<ConnectorType> discoverConnectors(ConnectorHostType hostType,
                                                OperationResult parentResult)
                                                throws CommunicationException
Discovers local or remote connectors. The operation will try to search for new connectors. It works either on local host (hostType is null) or on a remote host (hostType is not null). All discovered connectors are stored in the repository. It returns connectors that were discovered: those that were not in the repository before invocation of this operation.

Parameters:
hostType - definition of a connector host or null
parentResult - parentResult parent OperationResult (in/out)
Returns:
discovered connectors
Throws:
CommunicationException - error connecting to a remote host

listResourceObjects

ResultList<? extends ResourceObjectShadowType> listResourceObjects(java.lang.String resourceOid,
                                                                   javax.xml.namespace.QName objectClass,
                                                                   PagingType paging,
                                                                   OperationResult parentResult)
                                                                   throws SchemaException,
                                                                          ObjectNotFoundException,
                                                                          CommunicationException
Lists resource objects. This method differs from other method in this interface as it works with resource objects directly. It returns resource objects in a form of "detached shadow", that means fully-populated shadow objects with no OID. The results of this method may not be stored in the repository. The purpose of this method is to work directly with the resource without the potential problems of provisioning implementation. E.g. it may be used to test resource connectivity or correctness of resource setup. It may also be used to reach object types that are not directly supported as "shadows" by the provisioning implementation.

Parameters:
resourceOid - OID of the resource to fetch objects from
objectClass - Object class of the objects to fetch
paging - paging specification to limit operation result (optional)
parentResult - parent OperationResult (in/out)
Returns:
resource objects in a form of "detached shadows"
Throws:
ObjectNotFoundException - specified resource object does not exist
SchemaException - error handling resource schema
CommunicationException - error communicating with the resource

postInit

void postInit(OperationResult parentResult)
Finish initialization of provisioning system. The implementation may execute resource-intensive tasks in this method. All the dependencies should be already constructed, properly wired and initialized. Also logging and other infrastructure should be already set up.



Copyright © 2011 evolveum. All Rights Reserved.