Interface ProvisioningService
-
public interface ProvisioningService
Provisioning Service Interface.
Status: public Stability: STABLE, only compatible changes are expected
- Version:
- 3.7.1
- 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:
- Resource
- Shadow
- Connector
TODO: better documentation
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description <T extends ObjectType>
StringaddObject(PrismObject<T> object, OperationProvisioningScriptsType scripts, ProvisioningOperationOptions options, Task task, OperationResult parentResult)
Add new object.<T extends ObjectType>
voidapplyDefinition(ObjectDelta<T> delta, Objectable object, Task task, OperationResult parentResult)
Applies appropriate definition to the shadow/resource delta.<T extends ObjectType>
voidapplyDefinition(ObjectDelta<T> delta, Task task, OperationResult parentResult)
Applies appropriate definition to the shadow/resource delta.<T extends ObjectType>
voidapplyDefinition(PrismObject<T> object, Task task, OperationResult parentResult)
Applies appropriate definition to the shadow.<T extends ObjectType>
voidapplyDefinition(Class<T> type, ObjectQuery query, Task task, OperationResult parentResult)
Applies appropriate definition to the query.ConstraintsCheckingResult
checkConstraints(RefinedObjectClassDefinition shadowDefinition, PrismObject<ShadowType> shadowObject, PrismObject<ShadowType> shadowObjectOld, ResourceType resourceType, String shadowOid, ResourceShadowDiscriminator resourceShadowDiscriminator, ConstraintViolationConfirmer constraintViolationConfirmer, ConstraintsCheckingStrategyType strategy, Task task, OperationResult parentResult)
<O extends ObjectType,T>
ItemComparisonResultcompare(Class<O> type, String oid, ItemPath path, T expectedValue, Task task, OperationResult result)
Compare value on the resource with the provided value.<T extends ObjectType>
IntegercountObjects(Class<T> type, ObjectQuery query, Collection<SelectorOptions<GetOperationOptions>> options, Task task, OperationResult parentResult)
Options: if noFetch or raw, we count only shadows from the repository.<T extends ObjectType>
PrismObject<T>deleteObject(Class<T> type, String oid, ProvisioningOperationOptions option, OperationProvisioningScriptsType scripts, Task task, OperationResult parentResult)
Deletes object with specified OID.void
determineShadowState(PrismObject<ShadowType> shadow, Task task, OperationResult parentResult)
Determines shadow lifecycle state (shadow state for short), updating the shadow object.Set<ConnectorType>
discoverConnectors(ConnectorHostType hostType, OperationResult parentResult)
Discovers local or remote connectors.void
enterConstraintsCheckerCache()
Object
executeScript(String resourceOid, ProvisioningScriptType script, Task task, OperationResult parentResult)
Executes a single provisioning script.void
exitConstraintsCheckerCache()
List<ConnectorOperationalStatus>
getConnectorOperationalStatus(String resourceOid, Task task, OperationResult parentResult)
<T extends ObjectType>
PrismObject<T>getObject(Class<T> type, String oid, Collection<SelectorOptions<GetOperationOptions>> options, Task task, OperationResult parentResult)
Returns object for provided OID.ProvisioningDiag
getProvisioningDiag()
Returns a diagnostic information.SystemConfigurationType
getSystemConfiguration()
Temporary and quick hack.<T extends ObjectType>
StringmodifyObject(Class<T> type, String oid, Collection<? extends ItemDelta<?,?>> modifications, OperationProvisioningScriptsType scripts, ProvisioningOperationOptions options, Task task, OperationResult parentResult)
Modifies object using relative change description.void
postInit(OperationResult parentResult)
Finish initialization of provisioning system.void
processAsynchronousUpdates(@NotNull ResourceShadowDiscriminator shadowCoordinates, @NotNull AsyncUpdateEventHandler handler, @NotNull Task task, @NotNull OperationResult parentResult)
Processes asynchronous updates for a given resource.void
provisioningSelfTest(OperationResult parentTestResult, Task task)
Runs a short, non-destructive internal provisioning test.void
refreshShadow(PrismObject<ShadowType> shadow, ProvisioningOperationOptions options, Task task, OperationResult parentResult)
Makes sure that the shadow is in accord with the reality.<T extends ObjectType>
@NotNull SearchResultList<PrismObject<T>>searchObjects(Class<T> type, ObjectQuery query, Collection<SelectorOptions<GetOperationOptions>> options, Task task, OperationResult parentResult)
Search for objects.<T extends ObjectType>
SearchResultMetadatasearchObjectsIterative(Class<T> type, ObjectQuery query, Collection<SelectorOptions<GetOperationOptions>> options, ResultHandler<T> handler, Task task, OperationResult parentResult)
Search for objects iteratively.void
setResourceObjectClassifier(ResourceObjectClassifier classifier)
Provides a classifier to the provisioning service.void
shutdown()
@NotNull SynchronizationResult
synchronize(@NotNull ResourceShadowDiscriminator shadowCoordinates, LiveSyncOptions options, @NotNull LiveSyncTokenStorage tokenStorage, @NotNull LiveSyncEventHandler handler, @NotNull Task task, @NotNull OperationResult parentResult)
Collect external changes on a resource and call the business logic with the accumulated change data.OperationResult
testResource(String resourceOid, Task task)
Test the resource connection and basic resource connector functionality.
-
-
-
Method Detail
-
getObject
<T extends ObjectType> PrismObject<T> getObject(Class<T> type, String oid, Collection<SelectorOptions<GetOperationOptions>> options, Task task, OperationResult parentResult) throws ObjectNotFoundException, CommunicationException, SchemaException, ConfigurationException, SecurityViolationException, ExpressionEvaluationException
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 getoid
- OID of the object to getparentResult
- parent OperationResult (in/out)- Returns:
- Object fetched from repository and/or resource
- Throws:
ObjectNotFoundException
- requested object does not existCommunicationException
- error communicating with the resourceSchemaException
- error dealing with resource schemaConfigurationException
- Wrong resource or connector configurationSecurityViolationException
- Security violation while communicating with the connector or processing provisioning policiesIllegalArgumentException
- wrong OID format, etc.GenericConnectorException
- unknown connector framework errorExpressionEvaluationException
-
addObject
<T extends ObjectType> String addObject(PrismObject<T> object, OperationProvisioningScriptsType scripts, ProvisioningOperationOptions options, Task task, OperationResult parentResult) throws ObjectAlreadyExistsException, SchemaException, CommunicationException, ObjectNotFoundException, ConfigurationException, SecurityViolationException, PolicyViolationException, ExpressionEvaluationException
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 createscripts
- scripts to execute before/after the operationparentResult
- parent OperationResult (in/out)- Returns:
- OID assigned to the created object
- Throws:
ObjectAlreadyExistsException
- object with specified identifiers already exists, cannot addSchemaException
- error dealing with resource schema, e.g. schema violationCommunicationException
- error communicating with the resourceObjectNotFoundException
- appropriate connector object was not foundConfigurationException
IllegalArgumentException
- wrong OID format, etc.GenericConnectorException
- unknown connector framework errorSecurityViolationException
- Security violation while communicating with the connector or processing provisioning policiesPolicyViolationException
ExpressionEvaluationException
-
synchronize
@NotNull @NotNull SynchronizationResult synchronize(@NotNull @NotNull ResourceShadowDiscriminator shadowCoordinates, LiveSyncOptions options, @NotNull @NotNull LiveSyncTokenStorage tokenStorage, @NotNull @NotNull LiveSyncEventHandler handler, @NotNull @NotNull Task task, @NotNull @NotNull OperationResult parentResult) throws ObjectNotFoundException, CommunicationException, SchemaException, ConfigurationException, SecurityViolationException, ExpressionEvaluationException, PolicyViolationException
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:
shadowCoordinates
- where to attempt synchronizationparentResult
- parent OperationResult (in/out)- Returns:
- the number of processed changes
- Throws:
ObjectNotFoundException
- some of key objects (resource, task, ...) do not existCommunicationException
- error communicating with the resourceSchemaException
- error dealing with resource schemaSecurityViolationException
- Security violation while communicating with the connector or processing provisioning policiesGenericConnectorException
- unknown connector framework errorConfigurationException
ExpressionEvaluationException
PolicyViolationException
-
processAsynchronousUpdates
void processAsynchronousUpdates(@NotNull @NotNull ResourceShadowDiscriminator shadowCoordinates, @NotNull @NotNull AsyncUpdateEventHandler handler, @NotNull @NotNull Task task, @NotNull @NotNull OperationResult parentResult) throws ObjectNotFoundException, SchemaException, CommunicationException, ConfigurationException, ExpressionEvaluationException
Processes asynchronous updates for a given resource. The control is not returned to the caller until processing is finished. The end of processing is usually triggered from the outside: by stopping the owning task. (So the implementor of this method should keep an eye on task.canRun() state.) Processing can be also finished when the resource encounters a fatal error. This behaviour should be configurable in the future. If the task is not of RunningTask type, the only way how to stop processing is to interrupt the thread or to close the asynchronous updates data source. Execution of updates is done in the context of the task worker threads (i.e. lightweight asynchronous subtask), if there are any. If there are none, execution is done in the thread that receives the message. Note that although it is possible to specify other parameters in addition to resource OID (e.g. objectClass), these settings are not supported now.
-
searchObjects
@NotNull <T extends ObjectType> @NotNull SearchResultList<PrismObject<T>> searchObjects(Class<T> type, ObjectQuery query, Collection<SelectorOptions<GetOperationOptions>> options, Task task, OperationResult parentResult) throws SchemaException, ObjectNotFoundException, CommunicationException, ConfigurationException, SecurityViolationException, ExpressionEvaluationException
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 querytask
-parentResult
- parent OperationResult (in/out) @return all objects of specified type that match search criteria (subject to paging)- Throws:
IllegalArgumentException
- wrong object typeGenericConnectorException
- unknown connector framework errorSchemaException
- unknown property used in search queryConfigurationException
SecurityViolationException
- Security violation while communicating with the connector or processing provisioning policiesObjectNotFoundException
CommunicationException
ExpressionEvaluationException
-
countObjects
<T extends ObjectType> Integer countObjects(Class<T> type, ObjectQuery query, Collection<SelectorOptions<GetOperationOptions>> options, Task task, OperationResult parentResult) throws SchemaException, ObjectNotFoundException, CommunicationException, ConfigurationException, SecurityViolationException, ExpressionEvaluationException
Options: if noFetch or raw, we count only shadows from the repository.
-
searchObjectsIterative
<T extends ObjectType> SearchResultMetadata searchObjectsIterative(Class<T> type, ObjectQuery query, Collection<SelectorOptions<GetOperationOptions>> options, ResultHandler<T> handler, Task task, OperationResult parentResult) throws SchemaException, ObjectNotFoundException, CommunicationException, ConfigurationException, SecurityViolationException, ExpressionEvaluationException
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 queryhandler
- result handlertask
-parentResult
- parent OperationResult (in/out)- Throws:
IllegalArgumentException
- wrong object typeGenericConnectorException
- unknown connector framework errorSchemaException
- unknown property used in search queryObjectNotFoundException
- appropriate connector object was not foundConfigurationException
SecurityViolationException
- Security violation while communicating with the connector or processing provisioning policiesCommunicationException
ExpressionEvaluationException
-
modifyObject
<T extends ObjectType> String modifyObject(Class<T> type, String oid, Collection<? extends ItemDelta<?,?>> modifications, OperationProvisioningScriptsType scripts, ProvisioningOperationOptions options, Task task, OperationResult parentResult) throws ObjectNotFoundException, SchemaException, CommunicationException, ConfigurationException, SecurityViolationException, PolicyViolationException, ObjectAlreadyExistsException, ExpressionEvaluationException
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:
scripts
- scripts that should be executed before of after operationparentResult
- parent OperationResult (in/out)- Throws:
ObjectNotFoundException
- specified object does not existSchemaException
- resulting object would violate the schemaIllegalArgumentException
- wrong OID format, described change is not applicableGenericConnectorException
- unknown connector framework errorSecurityViolationException
- Security violation while communicating with the connector or processing provisioning policiesObjectAlreadyExistsException
- if resulting object would have name which already exists in another object of the same typeCommunicationException
ConfigurationException
PolicyViolationException
ExpressionEvaluationException
-
deleteObject
<T extends ObjectType> PrismObject<T> deleteObject(Class<T> type, String oid, ProvisioningOperationOptions option, OperationProvisioningScriptsType scripts, Task task, OperationResult parentResult) throws ObjectNotFoundException, CommunicationException, SchemaException, ConfigurationException, SecurityViolationException, PolicyViolationException, ExpressionEvaluationException
Deletes object with specified OID. Delete operation always deletes the resource object - or at least tries to. But this operation may or may not delete the repository shadow. The shadow may remain in a dead (tombstone) state. In that case the delete operation returns such shadow to indicate that repository shadow was not deleted. Must fail if object with specified OID does not exist. Should be atomic.- Parameters:
oid
- OID of object to deletescripts
- scripts that should be executed before of after operationparentResult
- parent OperationResult (in/out)- Returns:
- Current (usually dead) repository shadow - if it exists after delete. Otherwise returns null. For objects different from shadows (and when using raw deletion) returns null.
- Throws:
ObjectNotFoundException
- specified object does not existSecurityViolationException
- security violation while communicating with the connector or processing provisioning policiesIllegalArgumentException
- wrong OID format, described change is not applicableGenericConnectorException
- unknown connector framework errorCommunicationException
SchemaException
ConfigurationException
PolicyViolationException
ExpressionEvaluationException
-
executeScript
Object executeScript(String resourceOid, ProvisioningScriptType script, Task task, OperationResult parentResult) throws ObjectNotFoundException, SchemaException, CommunicationException, ConfigurationException, SecurityViolationException, ObjectAlreadyExistsException, ExpressionEvaluationException
Executes a single provisioning script.- Parameters:
script
- script to executeparentResult
- parent OperationResult (in/out)- Returns:
- Throws:
ObjectNotFoundException
- specified object does not existSchemaException
- resulting object would violate the schemaIllegalArgumentException
- wrong OID format, described change is not applicableGenericConnectorException
- unknown connector framework errorSecurityViolationException
- Security violation while communicating with the connector or processing provisioning policiesObjectAlreadyExistsException
- if resulting object would have name which already exists in another object of the same typeCommunicationException
ConfigurationException
ExpressionEvaluationException
-
testResource
OperationResult testResource(String resourceOid, Task task) 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. The operation codes in the return value are defined by ConnectorTestOperation enumeration class.- Parameters:
resourceOid
- OID of resource to test- Returns:
- results of executed tests
- Throws:
ObjectNotFoundException
- specified object does not existIllegalArgumentException
- wrong OID formatGenericConnectorException
- unknown connector framework error- See Also:
ConnectorTestOperation
-
discoverConnectors
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 nullparentResult
- parentResult parent OperationResult (in/out)- Returns:
- discovered connectors
- Throws:
CommunicationException
- error connecting to a remote host
-
getConnectorOperationalStatus
List<ConnectorOperationalStatus> getConnectorOperationalStatus(String resourceOid, Task task, OperationResult parentResult) throws SchemaException, ObjectNotFoundException, CommunicationException, ConfigurationException, ExpressionEvaluationException
-
refreshShadow
void refreshShadow(PrismObject<ShadowType> shadow, ProvisioningOperationOptions options, Task task, OperationResult parentResult) throws SchemaException, ObjectNotFoundException, CommunicationException, ConfigurationException, ObjectAlreadyExistsException, SecurityViolationException, ExpressionEvaluationException
Makes sure that the shadow is in accord with the reality. If there are any unfinished operations associated with the shadow then this method will try to finish them. If there are pending (async) operations then this method will update their status. And so on. However, this is NOT reconciliation function that will make sure that the resource object attributes are OK with all the policies. This is just a provisioning-level operation.
-
applyDefinition
<T extends ObjectType> void applyDefinition(ObjectDelta<T> delta, Task task, OperationResult parentResult) throws SchemaException, ObjectNotFoundException, CommunicationException, ConfigurationException, ExpressionEvaluationException
Applies appropriate definition to the shadow/resource delta.
-
applyDefinition
<T extends ObjectType> void applyDefinition(ObjectDelta<T> delta, Objectable object, Task task, OperationResult parentResult) throws SchemaException, ObjectNotFoundException, CommunicationException, ConfigurationException, ExpressionEvaluationException
Applies appropriate definition to the shadow/resource delta. The provided object is used to get necessary information, and it's (sometimes) updated as well. TODO this should be specified better
-
applyDefinition
<T extends ObjectType> void applyDefinition(PrismObject<T> object, Task task, OperationResult parentResult) throws SchemaException, ObjectNotFoundException, CommunicationException, ConfigurationException, ExpressionEvaluationException
Applies appropriate definition to the shadow.
-
determineShadowState
void determineShadowState(PrismObject<ShadowType> shadow, Task task, OperationResult parentResult) throws SchemaException, ObjectNotFoundException, CommunicationException, ConfigurationException, ExpressionEvaluationException
Determines shadow lifecycle state (shadow state for short), updating the shadow object.
-
applyDefinition
<T extends ObjectType> void applyDefinition(Class<T> type, ObjectQuery query, Task task, OperationResult parentResult) throws SchemaException, ObjectNotFoundException, CommunicationException, ConfigurationException, ExpressionEvaluationException
Applies appropriate definition to the query.
-
provisioningSelfTest
void provisioningSelfTest(OperationResult parentTestResult, Task task)
Runs a short, non-destructive internal provisioning test. It tests provisioning framework and general setup. Use ModelService.testResource for testing individual resource configurations.
-
getProvisioningDiag
ProvisioningDiag getProvisioningDiag()
Returns a diagnostic information.- See Also:
ProvisioningDiag
-
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.
-
checkConstraints
ConstraintsCheckingResult checkConstraints(RefinedObjectClassDefinition shadowDefinition, PrismObject<ShadowType> shadowObject, PrismObject<ShadowType> shadowObjectOld, ResourceType resourceType, String shadowOid, ResourceShadowDiscriminator resourceShadowDiscriminator, ConstraintViolationConfirmer constraintViolationConfirmer, ConstraintsCheckingStrategyType strategy, Task task, OperationResult parentResult) throws CommunicationException, ObjectAlreadyExistsException, SchemaException, SecurityViolationException, ConfigurationException, ObjectNotFoundException, ExpressionEvaluationException
-
enterConstraintsCheckerCache
void enterConstraintsCheckerCache()
-
exitConstraintsCheckerCache
void exitConstraintsCheckerCache()
-
compare
<O extends ObjectType,T> ItemComparisonResult compare(Class<O> type, String oid, ItemPath path, T expectedValue, Task task, OperationResult result) throws ObjectNotFoundException, CommunicationException, SchemaException, ConfigurationException, SecurityViolationException, ExpressionEvaluationException, EncryptionException
Compare value on the resource with the provided value. This method is used to compare resource attributes or passwords, e.g. for the purposes of password policy. Note: comparison may be quite an expensive and heavy weight operation, e.g. it may try authenticating the user on the resource.
-
shutdown
void shutdown()
-
getSystemConfiguration
SystemConfigurationType getSystemConfiguration()
Temporary and quick hack. TODO fix this
-
setResourceObjectClassifier
void setResourceObjectClassifier(ResourceObjectClassifier classifier)
Provides a classifier to the provisioning service.
-
-