public interface ProvisioningService

Provisioning Service Interface * Status: public * Stability: STABLE, only compatible changes are expected 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 NOTE: Because there is currently only a single implementation of this interface, we have the luxury to provide some implementation-level restrictions and comments here, without having to write them separately into the implementation class. This may change in the future.

Author:: Radovan Semancik

Method Summary

Modifier and Type

Method

Description

<T extends ObjectType> String

addObject(@NotNull PrismObject<T> object, @Nullable OperationProvisioningScriptsType scripts, @Nullable ProvisioningOperationOptions options, @NotNull ProvisioningOperationContext context, @NotNull Task task, @NotNull OperationResult parentResult)

Add new object.

default <T extends ObjectType> String

addObject(@NotNull PrismObject<T> object, @Nullable OperationProvisioningScriptsType scripts, @Nullable ProvisioningOperationOptions options, @NotNull Task task, @NotNull OperationResult parentResult)

This is method doesn't take ProvisioningOperationContext as a parameter to simplify backward compatibility for now.

<T extends ObjectType> void

applyDefinition(ObjectDelta<T> delta, Objectable object, Task task, OperationResult parentResult)

Applies appropriate definition to the shadow/resource delta.

<T extends ObjectType> void

applyDefinition(ObjectDelta<T> delta, Task task, OperationResult parentResult)

Applies appropriate definition to the shadow/resource delta.

<T extends ObjectType> void

applyDefinition(PrismObject<T> object, Task task, OperationResult parentResult)

Applies appropriate definition to the shadow.

<T extends ObjectType> void

applyDefinition(Class<T> type, ObjectQuery query, Task task, OperationResult parentResult)

Applies appropriate definition to the query.

ConstraintsCheckingResult

checkConstraints(ResourceObjectDefinition objectTypeDefinition, PrismObject<ShadowType> shadowObject, PrismObject<ShadowType> shadowObjectOld, ResourceType resource, String shadowOid, ConstraintViolationConfirmer constraintViolationConfirmer, ConstraintsCheckingStrategyType strategy, ProvisioningOperationContext context, @NotNull Task task, @NotNull OperationResult parentResult)

TODO description

@NotNull ResourceObjectClassification

classifyResourceObject(@NotNull ShadowType combinedObject, @NotNull ResourceType resource, @Nullable ObjectSynchronizationDiscriminatorType existingSorterResult, @NotNull Task task, @NotNull OperationResult result)

Classifies resource object, i.e.

<O extends ObjectType, T> ItemComparisonResult

compare(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> Integer

countObjects(@NotNull Class<T> type, @Nullable ObjectQuery query, @Nullable Collection<SelectorOptions<GetOperationOptions>> options, @NotNull ProvisioningOperationContext context, @NotNull Task task, @NotNull OperationResult parentResult)

Counts the objects of the respective type.

default <T extends ObjectType> Integer

countObjects(@NotNull Class<T> type, @Nullable ObjectQuery query, @Nullable Collection<SelectorOptions<GetOperationOptions>> options, @NotNull Task task, @NotNull OperationResult parentResult)

This is method doesn't take ProvisioningOperationContext as a parameter to simplify backward compatibility for now.

<T extends ObjectType> PrismObject<T>

deleteObject(Class<T> type, String oid, ProvisioningOperationOptions option, OperationProvisioningScriptsType scripts, ProvisioningOperationContext context, Task task, OperationResult parentResult)

Deletes object with specified OID.

default <T extends ObjectType> PrismObject<T>

deleteObject(Class<T> type, String oid, ProvisioningOperationOptions option, OperationProvisioningScriptsType scripts, Task task, OperationResult parentResult)

This is method doesn't take ProvisioningOperationContext as a parameter to simplify backward compatibility for now.

void

determineShadowState(PrismObject<ShadowType> shadow, Task task, OperationResult parentResult)

Determines shadow lifecycle state (shadow state for short), updating the shadow object.

@NotNull DiscoveredConfiguration

discoverConfiguration(@NotNull PrismObject<ResourceType> resource, @NotNull OperationResult parentResult)

Discovers additional configuration properties.

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()

void

expandConfigurationObject(@NotNull PrismObject<? extends ObjectType> configurationObject, @NotNull Task task, @NotNull OperationResult result)

Expands (in-memory) configuration object by (e.g.) resolving references to super/template objects, and so on.

@Nullable BareResourceSchema

fetchSchema(@NotNull PrismObject<ResourceType> resource, @NotNull OperationResult parentResult)

The operation fetches the resource schema using the connector configuration from provided resource object.

@Nullable String

generateShadowTag(@NotNull ShadowType combinedObject, @NotNull ResourceType resource, @NotNull ResourceObjectDefinition definition, @NotNull Task task, @NotNull OperationResult result)

Generates shadow tag (for multi-account scenarios).

List<ConnectorOperationalStatus>

getConnectorOperationalStatus(String resourceOid, Task task, OperationResult parentResult)

@Nullable ObjectOperationPolicyType

getDefaultOperationPolicy(@NotNull String resourceOid, @NotNull ResourceObjectTypeIdentification typeIdentification, @NotNull Task task, @NotNull OperationResult result)

Returns the default operation policy for given object type (if specified).

@NotNull CapabilityCollectionType

getNativeCapabilities(@NotNull String connOid, OperationResult result)

Method create collection of capabilities which connector support.

<T extends ObjectType> @NotNull PrismObject<T>

getObject(@NotNull Class<T> type, @NotNull String oid, @Nullable Collection<SelectorOptions<GetOperationOptions>> options, @NotNull ProvisioningOperationContext context, @NotNull Task task, @NotNull OperationResult parentResult)

Returns the object with specified OID.

default <T extends ObjectType> @NotNull PrismObject<T>

getObject(@NotNull Class<T> type, @NotNull String oid, @Nullable Collection<SelectorOptions<GetOperationOptions>> options, @NotNull Task task, @NotNull OperationResult parentResult)

This is method doesn't take ProvisioningOperationContext as a parameter to simplify backward compatibility for now.

ProvisioningDiag

getProvisioningDiag()

Returns a diagnostic information.

default @NotNull AbstractShadow

getShadow(@NotNull String oid, @Nullable Collection<SelectorOptions<GetOperationOptions>> options, @NotNull Task task, @NotNull OperationResult result)

A convenience method.

SystemConfigurationType

getSystemConfiguration()

Temporary and quick hack.

<T extends ObjectType> String

modifyObject(@NotNull Class<T> type, @NotNull String oid, @NotNull Collection<? extends ItemDelta<?,?>> modifications, @Nullable OperationProvisioningScriptsType scripts, @Nullable ProvisioningOperationOptions options, @NotNull ProvisioningOperationContext context, @NotNull Task task, @NotNull OperationResult parentResult)

Modifies object using relative change description.

default <T extends ObjectType> String

modifyObject(@NotNull Class<T> type, @NotNull String oid, @NotNull Collection<? extends ItemDelta<?,?>> modifications, @Nullable OperationProvisioningScriptsType scripts, @Nullable ProvisioningOperationOptions options, @NotNull Task task, @NotNull OperationResult parentResult)

This is method doesn't take ProvisioningOperationContext as a parameter to simplify backward compatibility for now.

void

postInit(OperationResult parentResult)

Finish initialization of provisioning system.

void

processAsynchronousUpdates(@NotNull ResourceOperationCoordinates coordinates, @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(@NotNull PrismObject<ShadowType> shadow, ProvisioningOperationOptions options, ProvisioningOperationContext context, @NotNull Task task, @NotNull OperationResult parentResult)

Makes sure that the shadow is in accord with the reality.

default void

refreshShadow(PrismObject<ShadowType> shadow, ProvisioningOperationOptions options, Task task, OperationResult parentResult)

This is method doesn't take ProvisioningOperationContext as a parameter to simplify backward compatibility for now.

<T extends ObjectType> @NotNull SearchResultList<PrismObject<T>>

searchObjects(@NotNull Class<T> type, @Nullable ObjectQuery query, @Nullable Collection<SelectorOptions<GetOperationOptions>> options, @NotNull ProvisioningOperationContext context, @NotNull Task task, @NotNull OperationResult parentResult)

Searches for objects.

default <T extends ObjectType> @NotNull SearchResultList<PrismObject<T>>

searchObjects(@NotNull Class<T> type, @Nullable ObjectQuery query, @Nullable Collection<SelectorOptions<GetOperationOptions>> options, @NotNull Task task, @NotNull OperationResult parentResult)

This is method doesn't take ProvisioningOperationContext as a parameter to simplify backward compatibility for now.

<T extends ObjectType> SearchResultMetadata

searchObjectsIterative(@NotNull Class<T> type, @Nullable ObjectQuery query, @Nullable Collection<SelectorOptions<GetOperationOptions>> options, @NotNull ResultHandler<T> handler, @NotNull ProvisioningOperationContext context, @NotNull Task task, @NotNull OperationResult parentResult)

Search for objects iteratively.

default <T extends ObjectType> SearchResultMetadata

searchObjectsIterative(@NotNull Class<T> type, @Nullable ObjectQuery query, @Nullable Collection<SelectorOptions<GetOperationOptions>> options, @NotNull ResultHandler<T> handler, @NotNull Task task, @NotNull OperationResult parentResult)

This is method doesn't take ProvisioningOperationContext as a parameter to simplify backward compatibility for now.

default @NotNull SearchResultList<? extends AbstractShadow>

searchShadows(@Nullable ObjectQuery query, @Nullable Collection<SelectorOptions<GetOperationOptions>> options, @NotNull Task task, @NotNull OperationResult result)

A convenience method.

default <T extends ObjectType> SearchResultMetadata

searchShadowsIterative(@Nullable ObjectQuery query, @Nullable Collection<SelectorOptions<GetOperationOptions>> options, @NotNull ObjectHandler<AbstractShadow> handler, @NotNull Task task, @NotNull OperationResult result)

A convenience method.

void

setSynchronizationSorterEvaluator(SynchronizationSorterEvaluator evaluator)

Provides a sorter evaluator to the provisioning service.

void

shutdown()

@NotNull SynchronizationResult

synchronize(@NotNull ResourceOperationCoordinates coordinates, @Nullable LiveSyncOptions options, @NotNull LiveSyncTokenStorage tokenStorage, @NotNull LiveSyncEventHandler handler, @NotNull ProvisioningOperationContext context, @NotNull Task task, @NotNull OperationResult parentResult)

Fetches synchronization change events (LiveSyncEvent) from a resource and passes them into specified LiveSyncEventHandler.

default @NotNull SynchronizationResult

synchronize(@NotNull ResourceOperationCoordinates coordinates, @Nullable LiveSyncOptions options, @NotNull LiveSyncTokenStorage tokenStorage, @NotNull LiveSyncEventHandler handler, @NotNull Task task, @NotNull OperationResult parentResult)

This is method doesn't take ProvisioningOperationContext as a parameter to simplify backward compatibility for now.

default @NotNull OperationResult

testPartialConfiguration(@NotNull PrismObject<ResourceType> resource, @NotNull Task task, @NotNull OperationResult parentResult)

Test partial resource connection.

default @NotNull OperationResult

testResource(@NotNull PrismObject<ResourceType> resource, @NotNull Task task, OperationResult parentResult)

@NotNull OperationResult

testResource(@NotNull PrismObject<ResourceType> resource, @Nullable ResourceTestOptions options, @NotNull Task task, OperationResult parentResult)

Test the resource connection and basic resource connector functionality.

default @NotNull OperationResult

testResource(@NotNull String resourceOid, @NotNull Task task, @NotNull OperationResult parentResult)

@NotNull OperationResult

testResource(@NotNull String resourceOid, @Nullable ResourceTestOptions options, @NotNull Task task, @NotNull OperationResult parentResult)

Tests the resource connection and basic resource connector functionality.

void

updateShadowMarksAndPolicies(PrismObject<ShadowType> shadow, boolean isNew, Task task, OperationResult parentResult)

Determines effective shadow marks and policies, updating the shadow object in memory.

Method Details
- getObject
  
  @NotNull <T extends ObjectType> @NotNull PrismObject<T> getObject(@NotNull @NotNull Class<T> type, @NotNull @NotNull String oid, @Nullable @Nullable Collection<SelectorOptions<GetOperationOptions>> options, @NotNull @NotNull ProvisioningOperationContext context, @NotNull @NotNull Task task, @NotNull @NotNull OperationResult parentResult) throws ObjectNotFoundException, CommunicationException, SchemaException, ConfigurationException, SecurityViolationException, ExpressionEvaluationException
  
  Returns the object with specified OID. (It must fail if there is no object with that OID in the repository.) The functionality vary vastly by the type of object requested. == ShadowType objects The resource object shadow may be retrieved from the repository, directly from 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). === Options support [%autowidth] [%header] |=== | Option | Support | retrieve | only as far as attributes are concerned - ignored e.g. for the associations (why?) | resolve | do not use (effects are unclear) | resolveNames | do not use (effects are unclear) | noFetch | yes | raw | yes | tolerateRawData | do not use | doNotDiscovery | yes | relationalValueSearchQuery | ignored | allowNotFound | partially supported | readOnly | ignored (shadows are heavily updated after fetching from repo, anyway) | pointInTimeType | yes | staleness | yes | forceRefresh | yes | forceRetry | yes | distinct | ignored | attachDiagData | do not use (effects are unclear) | definitionProcessing | ignored | iterationMethod | ignored | executionPhase | ignored | errorHandling | partially supported |=== === The `raw`, `noFetch`, and regular modes [%autowidth] [%header] |=== | Mode | Shadow LC state set* | Shadow refresh | Read from resource | Classification | Futurization (see below) | raw | no | none | no | from repository | no | noFetch | yes | quick | no | from repository | yes | regular | yes | depends | depends | depends | yes |=== (*) This is `shadowLifecycleState` property that does not exist in the repository (yet). It is computed by the implementation of this method. === Required resource capabilities The "read" capability of resource and relevant object type (if applicable) is checked. Operation fails if it is not present or enabled. If "caching-only" is set, reading from resource is avoided. === Shadow refresh The shadow is refreshed after it's fetched from the repository in the following modes: [%autowidth] [%header] |=== | Condition | Refresh mode | resource in maintenance | none (may change in future) | forceRefresh option | full | forceRetry option | full | refreshOnRead is set | full | otherwise | quick |=== - "Full refresh" is equivalent to refreshShadow(PrismObject, ProvisioningOperationOptions, Task, OperationResult). - "Quick refresh" is a subset of it: deleting expired pending operations and deleting the expired dead shadow. This may change in the future. === Avoiding reading from the resource Reading from the resource is avoided in specific conditions, namely if: . The resource or object type has "caching-only" read capability. . Resource is in maintenance mode. . A shadow is in specific near-birth or near-death state. See the implementation (`GetOperation`) for details. . Using the cached version is required by the staleness and point-in-time options. In specific conditions the implementation may decide to handle the fact that the object does not exist on the resource. === Post-processing of the resource object fetched When a resource object is successfully read from the resource, the following should occur: . Shadow is classified - either if it was not classified yet, or the resource is in "development mode" (see below). . Repository shadow is updated with known data obtained from the resource. This includes e.g. cached attributes. === Shadow futurization When `future` point of time is requested, the pending operations are applied to the last known state of the shadow. (Fetched either from the resource or from repository.) The current implementation is not 100% correct, as it tries to apply all attribute deltas even if the base object does not have all the attributes available. === Shadow fetch result specifics When the resource object is being fetched from the resource, and: . CommunicationException occurs, the status is `PARTIAL_ERROR` (and repo shadow is returned), . resource is in maintenance, the status is `PARTIAL_ERROR` (and repo shadow is returned), . ObjectNotFoundException occurs, the status is `HANDLED_ERROR` (and repo shadow with the `dead` flag is returned). The reason is that the exception was, in fact, handled. The current state of the object is correctly reported. === Potential side effects . Quick or full shadow refresh - before the GET issued against resource (or after the repo load if noFetch is set). The shadow may be even deleted by the refresh. . Discovery process (an event is sent to the listener, typically to model). . Shadow is updated with the information obtained from the resource: cached identifiers and/or other attributes, probably `dead` and `exists` properties. . ... TODO think about compatibility of these side effects with the limitations prescribed by development/execution mode. === Effects of development and execution mode The following configuration items should be respected: * `lifecycleState` in resource and/or object type - drives e.g. the classification process * shadow production/non-production flag - also drives the classification TODO specify in mode details == ResourceType objects The returned object will conform to the following: [%autowidth] [%header] |=== | State/condition | Is expanded | Configuration is resolved | Has capabilities and schema | Is put into cache | current version is in cache | yes | yes | yes (taken from cache) | it is already there | is abstract | yes | no | if present in repo | no | is complete in repo | yes | yes | yes (taken from repo) | yes | is incomplete in repo, noFetch = false | yes | yes | yes (fetched) | yes (if no problems) | is incomplete in repo, noFetch = true | yes | yes | if present in repo | no | raw = true | no | only the definitions | if present in repo | no |=== Notes: . If the current version of the object is in the resource cache, it is returned right from it. . "Is expanded" = the references to super-resources are resolved. . "Configuration is resolved" = definitions of individual configuration properties (from the connector schema) are applied; also, the expressions in these properties are evaluated. . "Has capabilities and schema" = whether native capabilities and schema information is present in the returned object. "If present in repo" means that the information from the repository are returned. . "Is put into cache" = whether the resource is put into the resource cache, so it can be cheaply retrieved afterwards. . "Is complete in repo" means that both capabilities and schema are fetched - see ResourceTypeUtil.isComplete(ResourceType). === Options support [%autowidth] [%header] |=== | Option | Support | retrieve | do not use (effects are unclear) | resolve | do not use (effects are unclear) | resolveNames | do not use (effects are unclear) | noFetch | yes | raw | yes | tolerateRawData | do not use | doNotDiscovery | ignored | relationalValueSearchQuery | ignored | allowNotFound | partially supported | readOnly | yes | pointInTimeType | ignored | staleness | ignored | forceRefresh | ignored | forceRetry | ignored | distinct | ignored | attachDiagData | do not use (effects are unclear) | definitionProcessing | ignored | iterationMethod | ignored | executionPhase | ignored | errorHandling | ignored |=== === Potential side effects . If a resource undergoes completion, the capabilities and/or schema are updated in the repository. . The complete resource may be put into the cache. === Effects of development and execution mode They are none. The definition of the resource is the same, regardless of the mode we run in. For example, it is cached regardless of the mode. However, the interpretation of the definition differs, but that is outside the scope of this method. (This may change if we would e.g. apply some "patches" specific to individual modes.) == ConnectorType and other objects These objects are just retrieved from the repository. They are not treated in any special way now. === Potential side effects None. === Effects of development and execution mode None. == Notes . Concrete type of object (`ShadowType`, `ResourceType`, and so on) must be provided by the client. Using generic `ObjectType` will not work. . The operation result is cleaned up before returning. . The fetch result (ObjectType.getFetchResult()) is stored into object being returned. It reflects the result of the whole operation: fetching from the resource, if applicable, but also e.g. application of definitions to an object retrieved in raw mode. Storing of "success" result may be skipped. == Limitations / Known issues . Getting shadows: Definitions of associations (identifiers) are not always refined (in noFetch mode).
  
  Parameters:
  
  type - the type (class) of object to get
  
  oid - OID of the object to get
  
  parentResult - parent OperationResult (in/out)
  
  Returns:
  
  Object fetched from repository and/or resource
  
  Throws:
  
  ObjectNotFoundException - requested object (does not need to be the shadow we are looking for!) does not exist
  
  CommunicationException - error communicating with the resource
  
  SchemaException - error dealing with resource schema
  
  ConfigurationException - wrong resource or connector configuration
  
  SecurityViolationException - security violation while communicating with the connector or processing provisioning policies
  
  IllegalArgumentException - wrong OID format, etc.
  
  GenericConnectorException - unknown connector framework error
  
  ExpressionEvaluationException
- getShadow
  
  @NotNull default @NotNull AbstractShadow getShadow(@NotNull @NotNull String oid, @Nullable @Nullable Collection<SelectorOptions<GetOperationOptions>> options, @NotNull @NotNull Task task, @NotNull @NotNull OperationResult result) throws ObjectNotFoundException, CommunicationException, SchemaException, ConfigurationException, SecurityViolationException, ExpressionEvaluationException
  
  A convenience method.
  
  Throws:
  
  ObjectNotFoundException
  
  CommunicationException
  
  SchemaException
  
  ConfigurationException
  
  SecurityViolationException
  
  ExpressionEvaluationException
- getObject
  
  @NotNull default <T extends ObjectType> @NotNull PrismObject<T> getObject(@NotNull @NotNull Class<T> type, @NotNull @NotNull String oid, @Nullable @Nullable Collection<SelectorOptions<GetOperationOptions>> options, @NotNull @NotNull Task task, @NotNull @NotNull OperationResult parentResult) throws ObjectNotFoundException, CommunicationException, SchemaException, ConfigurationException, SecurityViolationException, ExpressionEvaluationException
  
  This is method doesn't take ProvisioningOperationContext as a parameter to simplify backward compatibility for now. It shouldn't be used, will be deprecated and removed after tests were updated accordingly.
  
  Throws:
  
  ObjectNotFoundException
  
  CommunicationException
  
  SchemaException
  
  ConfigurationException
  
  SecurityViolationException
  
  ExpressionEvaluationException
- addObject
  
  <T extends ObjectType> String addObject(@NotNull @NotNull PrismObject<T> object, @Nullable @Nullable OperationProvisioningScriptsType scripts, @Nullable @Nullable ProvisioningOperationOptions options, @NotNull @NotNull ProvisioningOperationContext context, @NotNull @NotNull Task task, @NotNull @NotNull 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 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
  
  IllegalArgumentException - wrong OID format, etc.
  
  GenericConnectorException - unknown connector framework error
  
  SecurityViolationException - Security violation while communicating with the connector or processing provisioning policies
  
  ConfigurationException
  
  PolicyViolationException
  
  ExpressionEvaluationException
- addObject
  
  default <T extends ObjectType> String addObject(@NotNull @NotNull PrismObject<T> object, @Nullable @Nullable OperationProvisioningScriptsType scripts, @Nullable @Nullable ProvisioningOperationOptions options, @NotNull @NotNull Task task, @NotNull @NotNull OperationResult parentResult) throws ObjectAlreadyExistsException, SchemaException, CommunicationException, ObjectNotFoundException, ConfigurationException, SecurityViolationException, PolicyViolationException, ExpressionEvaluationException
  
  This is method doesn't take ProvisioningOperationContext as a parameter to simplify backward compatibility for now. It shouldn't be used, will be deprecated and removed after tests were updated accordingly.
  
  Throws:
  
  ObjectAlreadyExistsException
  
  SchemaException
  
  CommunicationException
  
  ObjectNotFoundException
  
  ConfigurationException
  
  SecurityViolationException
  
  PolicyViolationException
  
  ExpressionEvaluationException
- synchronize
  
  @NotNull @NotNull SynchronizationResult synchronize(@NotNull @NotNull ResourceOperationCoordinates coordinates, @Nullable @Nullable LiveSyncOptions options, @NotNull @NotNull LiveSyncTokenStorage tokenStorage, @NotNull @NotNull LiveSyncEventHandler handler, @NotNull @NotNull ProvisioningOperationContext context, @NotNull @NotNull Task task, @NotNull @NotNull OperationResult parentResult) throws ObjectNotFoundException, CommunicationException, SchemaException, ConfigurationException, SecurityViolationException, ExpressionEvaluationException, PolicyViolationException
  
  Fetches synchronization change events (LiveSyncEvent) from a resource and passes them into specified LiveSyncEventHandler. Uses provided LiveSyncTokenStorage to get and update the token that indicates the current position in the stream of live sync change events. It is typically invoked from a live sync activity (task). Notes regarding the `shadowCoordinates` parameter: * Resource OID is obligatory. * If neither object class nor kind are specified, all object classes on the resource are synchronized (if supported by the connector/resource). * If object class name is specified (but kind and intent are not), the object class to synchronize is determined using object class name. * If both kind and intent are specified, object type is determined based on them. It is then checked against object class name - the object class for given object type must match the specified object class name, if it's provided. * If only kind is specified (without intent), the default object type is found; and checked against object class name just like above. See ResourceSchemaUtil.findDefinitionForBulkOperation(ResourceType, ShadowKindType, String, QName) for the details. Note that it's not possible to specify intent without kind. Also, `unknown` values for kind or intent are not supported.
  
  Parameters:
  
  coordinates - Where to attempt synchronization. See description above.
  
  options - Options driving the synchronization process (execution mode, batch size, ...)
  
  tokenStorage - Interface for getting and setting the token for the activity
  
  handler - Handler that processes live sync events
  
  context - Provisioning context used to pass information from upper layers
  
  parentResult - Parent OperationResult to where we write our own subresults.
  
  Throws:
  
  ObjectNotFoundException - Some of key objects (resource, task, ...) do not exist
  
  CommunicationException - Error communicating with the resource
  
  SchemaException - Error dealing with resource schema
  
  SecurityViolationException - Security violation while communicating with the connector or processing provisioning policies
  
  GenericConnectorException - Unknown connector framework error
  
  ConfigurationException
  
  ExpressionEvaluationException
  
  PolicyViolationException
- synchronize
  
  @NotNull default @NotNull SynchronizationResult synchronize(@NotNull @NotNull ResourceOperationCoordinates coordinates, @Nullable @Nullable 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
  
  This is method doesn't take ProvisioningOperationContext as a parameter to simplify backward compatibility for now. It shouldn't be used, will be deprecated and removed after tests were updated accordingly.
  
  Throws:
  
  ObjectNotFoundException
  
  CommunicationException
  
  SchemaException
  
  ConfigurationException
  
  SecurityViolationException
  
  ExpressionEvaluationException
  
  PolicyViolationException
- processAsynchronousUpdates
  
  void processAsynchronousUpdates(@NotNull @NotNull ResourceOperationCoordinates coordinates, @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.
  
  Parameters:
  
  coordinates - What objects to synchronize. Note that although it is possible to specify other parameters in addition to resource OID (e.g. objectClass), these settings are not supported now.
  
  Throws:
  
  ObjectNotFoundException
  
  SchemaException
  
  CommunicationException
  
  ConfigurationException
  
  ExpressionEvaluationException
- 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 ProvisioningOperationContext context, @NotNull @NotNull Task task, @NotNull @NotNull OperationResult parentResult) throws SchemaException, ObjectNotFoundException, CommunicationException, ConfigurationException, SecurityViolationException, ExpressionEvaluationException
  
  Searches for objects. Returns a list of objects that match search criteria. The list is never null. It is empty if there are no matching objects. The method call should fail if object type is wrong. Should fail if the query is wrong, e.g. if it contains a reference to an unknown attribute. == Processing of ShadowType objects === Options support [%autowidth] [%header] |=== | Option | Support | retrieve | for attributes and associations | resolve | do not use (effects are unclear) | resolveNames | do not use (effects are unclear) | noFetch | yes | raw | yes | tolerateRawData | do not use | doNotDiscovery | ignored (TODO check if it is really ignored) | relationalValueSearchQuery | ignored | allowNotFound | ignored | readOnly | ignored (shadows are heavily updated after fetching from repo, anyway) | pointInTimeType | ignored (no futurization) | staleness | limited support | forceRefresh | ignored | forceRetry | ignored | distinct | supported for repository search, ignored for resource search | attachDiagData | do not use (effects are unclear) | definitionProcessing | ignored | iterationMethod | ignored | executionPhase | ignored | errorHandling | yes |=== === Specifying the "coordinates" When dealing with shadow queries in non-raw mode, there are the following requirements on the query: . there must be exactly one `resourceRef` obtainable from the query (i.e. present in the conjunction at the root level), . and .. either `kind` is specified (optionally with `intent` and/or `objectClass`), .. or `objectClass` is specified (and both `kind` and `intent` are not specified). See also ObjectQueryUtil.getOperationCoordinates(ObjectFilter). (For the raw mode the requirements are currently the same; however, we may relax them in the future.) === Interpreting the query for on-resource search ==== If `kind` is specified In this case, a specific _object type_ definition is looked up: either by `kind` and `intent` (if the latter is present), or - if `intent` is not specified - by looking for a type marked as "default for its kind". The search is then executed against this object type, taking its delineation (object class, base context, additional filters) into account. If `objectClass` is specified as well, it is just checked against the value in given object type definition. (Hence it is not necessary nor advisable to specify object class when kind is specified.) ==== If only `objectClass` is specified Here the implementation searches for all objects of given `objectClass`. However, there are few things that must be done during the search, for example determining "attributes to get" i.e. what attributes should be explicitly requested. These things depend on object class or object type definition. Therefore, the implementation has to look up appropriate definition first. It does so by looking up raw or refined object class definition. Also, if there is a type definition marked as "default for object class", it is used. However, even if such a type definition is found, the delineation (base context, filters, and so on) are ignored: as stated above, all objects of given object class are searched for. See ResourceSchemaUtil.findDefinitionForBulkOperation(ResourceType, ShadowKindType, String, QName) and ResourceSchemaUtil.findObjectDefinitionPrecisely(ResourceType, ShadowKindType, String, QName) for the details. === Extra resource objects Note that when using kind and/or intent, the method may return objects that do not match these conditions. It depends on how precise is the respective type definition, namely if its delineation: base context, hierarchy scope, and/or object filter(s) precisely describe objects that belong to this type. If these features do not describe the type adequately (e.g. if the classification has to be done using conditions written in Groovy), then the returned set of objects may contain ones that are not of requested type. It is then the responsibility of the caller to sort these extra objects out. === Potential side effects . Shadow is updated with the information obtained from the resource: cached identifiers and/or other attributes, probably `dead` and `exists` properties. . #TODO# === Effects of development and execution mode #TODO# == Processing of ResourceType objects Just like the getObject(Class, String, Collection, Task, OperationResult) method, the resources returned from this one are processed according to the inheritance rules, unless the `raw` mode is applied. Beware that - obviously - the search query is applied to find the original resource objects, not the "processed" ones. #TODO expand this part# #TODO side effects# === Effects of development and execution mode #TODO# == Fetch result The fetch result (ObjectType.getFetchResult()) should be present in objects returned (namely, if the processing was not entirely successful). Beware that the details of storing it may differ between this method and getObject(Class, String, Collection, Task, OperationResult).
  
  Returns:
  
  all objects of specified type that match search criteria (subject to paging)
  
  Throws:
  
  IllegalArgumentException - wrong object type
  
  GenericConnectorException - unknown connector framework error
  
  SchemaException - unknown property used in search query
  
  SecurityViolationException - Security violation while communicating with the connector or processing provisioning policies
  
  ObjectNotFoundException
  
  CommunicationException
  
  ConfigurationException
  
  ExpressionEvaluationException
- searchShadows
  
  @NotNull default @NotNull SearchResultList<? extends AbstractShadow> searchShadows(@Nullable @Nullable ObjectQuery query, @Nullable @Nullable Collection<SelectorOptions<GetOperationOptions>> options, @NotNull @NotNull Task task, @NotNull @NotNull OperationResult result) throws SchemaException, ExpressionEvaluationException, CommunicationException, SecurityViolationException, ConfigurationException, ObjectNotFoundException
  
  A convenience method.
  
  Throws:
  
  SchemaException
  
  ExpressionEvaluationException
  
  CommunicationException
  
  SecurityViolationException
  
  ConfigurationException
  
  ObjectNotFoundException
- searchObjects
  
  @NotNull default <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 Task task, @NotNull @NotNull OperationResult parentResult) throws SchemaException, ObjectNotFoundException, CommunicationException, ConfigurationException, SecurityViolationException, ExpressionEvaluationException
  
  This is method doesn't take ProvisioningOperationContext as a parameter to simplify backward compatibility for now. It shouldn't be used, will be deprecated and removed after tests were updated accordingly.
  
  Throws:
  
  SchemaException
  
  ObjectNotFoundException
  
  CommunicationException
  
  ConfigurationException
  
  SecurityViolationException
  
  ExpressionEvaluationException
- countObjects
  
  <T extends ObjectType> Integer countObjects(@NotNull @NotNull Class<T> type, @Nullable @Nullable ObjectQuery query, @Nullable @Nullable Collection<SelectorOptions<GetOperationOptions>> options, @NotNull @NotNull ProvisioningOperationContext context, @NotNull @NotNull Task task, @NotNull @NotNull OperationResult parentResult) throws SchemaException, ObjectNotFoundException, CommunicationException, ConfigurationException, SecurityViolationException, ExpressionEvaluationException
  
  Counts the objects of the respective type. == ShadowType objects These are counted in repository or on resource (if it has appropriate capability). #TODO the description, including the options# === Potential side effects #TODO# === Effects of development and execution mode #TODO# == Other object types These are counted simply in the repository service.
  
  Parameters:
  
  query - See searchObjects(Class, ObjectQuery, Collection, Task, OperationResult) description.
  
  options - If noFetch or raw, we count only shadows from the repository.
  
  Throws:
  
  SchemaException
  
  ObjectNotFoundException
  
  CommunicationException
  
  ConfigurationException
  
  SecurityViolationException
  
  ExpressionEvaluationException
- countObjects
  
  default <T extends ObjectType> Integer countObjects(@NotNull @NotNull Class<T> type, @Nullable @Nullable ObjectQuery query, @Nullable @Nullable Collection<SelectorOptions<GetOperationOptions>> options, @NotNull @NotNull Task task, @NotNull @NotNull OperationResult parentResult) throws SchemaException, ObjectNotFoundException, CommunicationException, ConfigurationException, SecurityViolationException, ExpressionEvaluationException
  
  This is method doesn't take ProvisioningOperationContext as a parameter to simplify backward compatibility for now. It shouldn't be used, will be deprecated and removed after tests were updated accordingly.
  
  Throws:
  
  SchemaException
  
  ObjectNotFoundException
  
  CommunicationException
  
  ConfigurationException
  
  SecurityViolationException
  
  ExpressionEvaluationException
- searchObjectsIterative
  
  <T extends ObjectType> SearchResultMetadata searchObjectsIterative(@NotNull @NotNull Class<T> type, @Nullable @Nullable ObjectQuery query, @Nullable @Nullable Collection<SelectorOptions<GetOperationOptions>> options, @NotNull @NotNull ResultHandler<T> handler, @NotNull @NotNull ProvisioningOperationContext context, @NotNull @NotNull Task task, @NotNull @NotNull 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. See searchObjects(Class, ObjectQuery, Collection, Task, OperationResult) description for more information.
  Parameters:
  
  query - search query
  
  handler - result handler
  
  parentResult - parent OperationResult (in/out)
  
  Throws:
  
  IllegalArgumentException - wrong object type
  
  GenericConnectorException - unknown connector framework error
  
  SchemaException - unknown property used in search query
  
  ObjectNotFoundException - appropriate connector object was not found
  
  SecurityViolationException - Security violation while communicating with the connector or processing provisioning policies
  
  CommunicationException
  
  ConfigurationException
  
  ExpressionEvaluationException
  
  See Also:
  
  searchObjects(Class, ObjectQuery, Collection, Task, OperationResult)
- searchObjectsIterative
  
  default <T extends ObjectType> SearchResultMetadata searchObjectsIterative(@NotNull @NotNull Class<T> type, @Nullable @Nullable ObjectQuery query, @Nullable @Nullable Collection<SelectorOptions<GetOperationOptions>> options, @NotNull @NotNull ResultHandler<T> handler, @NotNull @NotNull Task task, @NotNull @NotNull OperationResult parentResult) throws SchemaException, ObjectNotFoundException, CommunicationException, ConfigurationException, SecurityViolationException, ExpressionEvaluationException
  
  This is method doesn't take ProvisioningOperationContext as a parameter to simplify backward compatibility for now. It shouldn't be used, will be deprecated and removed after tests were updated accordingly.
  
  Throws:
  
  SchemaException
  
  ObjectNotFoundException
  
  CommunicationException
  
  ConfigurationException
  
  SecurityViolationException
  
  ExpressionEvaluationException
- searchShadowsIterative
  
  @Experimental default <T extends ObjectType> SearchResultMetadata searchShadowsIterative(@Nullable @Nullable ObjectQuery query, @Nullable @Nullable Collection<SelectorOptions<GetOperationOptions>> options, @NotNull @NotNull ObjectHandler<AbstractShadow> handler, @NotNull @NotNull Task task, @NotNull @NotNull OperationResult result) throws SchemaException, ObjectNotFoundException, CommunicationException, ConfigurationException, SecurityViolationException, ExpressionEvaluationException
  
  A convenience method.
  
  Throws:
  
  SchemaException
  
  ObjectNotFoundException
  
  CommunicationException
  
  ConfigurationException
  
  SecurityViolationException
  
  ExpressionEvaluationException
- modifyObject
  
  <T extends ObjectType> String modifyObject(@NotNull @NotNull Class<T> type, @NotNull @NotNull String oid, @NotNull @NotNull Collection<? extends ItemDelta<?,?>> modifications, @Nullable @Nullable OperationProvisioningScriptsType scripts, @Nullable @Nullable ProvisioningOperationOptions options, @NotNull @NotNull ProvisioningOperationContext context, @NotNull @NotNull Task task, @NotNull @NotNull 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 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 TODO decide if it's OK that the callee modifies the `modifications` collection by adding side-effects provided by the connector.
  
  Parameters:
  
  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
  
  IllegalArgumentException - wrong OID format, described change is not applicable
  
  GenericConnectorException - unknown connector framework error
  
  SecurityViolationException - Security violation while communicating with the connector or processing provisioning policies
  
  ObjectAlreadyExistsException - if resulting object would have name which already exists in another object of the same type
  
  CommunicationException
  
  ConfigurationException
  
  PolicyViolationException
  
  ExpressionEvaluationException
- modifyObject
  
  default <T extends ObjectType> String modifyObject(@NotNull @NotNull Class<T> type, @NotNull @NotNull String oid, @NotNull @NotNull Collection<? extends ItemDelta<?,?>> modifications, @Nullable @Nullable OperationProvisioningScriptsType scripts, @Nullable @Nullable ProvisioningOperationOptions options, @NotNull @NotNull Task task, @NotNull @NotNull OperationResult parentResult) throws ObjectNotFoundException, SchemaException, CommunicationException, ConfigurationException, SecurityViolationException, PolicyViolationException, ObjectAlreadyExistsException, ExpressionEvaluationException
  
  This is method doesn't take ProvisioningOperationContext as a parameter to simplify backward compatibility for now. It shouldn't be used, will be deprecated and removed after tests were updated accordingly.
  
  Throws:
  
  ObjectNotFoundException
  
  SchemaException
  
  CommunicationException
  
  ConfigurationException
  
  SecurityViolationException
  
  PolicyViolationException
  
  ObjectAlreadyExistsException
  
  ExpressionEvaluationException
- deleteObject
  
  <T extends ObjectType> PrismObject<T> deleteObject(Class<T> type, String oid, ProvisioningOperationOptions option, OperationProvisioningScriptsType scripts, ProvisioningOperationContext context, 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 delete
  
  scripts - scripts that should be executed before of after operation
  
  parentResult - 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 exist
  
  SecurityViolationException - security violation while communicating with the connector or processing provisioning policies
  
  IllegalArgumentException - wrong OID format, described change is not applicable
  
  GenericConnectorException - unknown connector framework error
  
  CommunicationException
  
  SchemaException
  
  ConfigurationException
  
  PolicyViolationException
  
  ExpressionEvaluationException
- deleteObject
  
  default <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
  
  This is method doesn't take ProvisioningOperationContext as a parameter to simplify backward compatibility for now. It shouldn't be used, will be deprecated and removed after tests were updated accordingly.
  
  Throws:
  
  ObjectNotFoundException
  
  CommunicationException
  
  SchemaException
  
  ConfigurationException
  
  SecurityViolationException
  
  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 execute
  
  parentResult - parent OperationResult (in/out)
  
  Throws:
  
  ObjectNotFoundException - specified object does not exist
  
  SchemaException - resulting object would violate the schema
  
  IllegalArgumentException - wrong OID format, described change is not applicable
  
  GenericConnectorException - unknown connector framework error
  
  SecurityViolationException - Security violation while communicating with the connector or processing provisioning policies
  
  ObjectAlreadyExistsException - if resulting object would have name which already exists in another object of the same type
  
  CommunicationException
  
  ConfigurationException
  
  ExpressionEvaluationException
- testResource
  
  @NotNull @NotNull OperationResult testResource(@NotNull @NotNull String resourceOid, @Nullable @Nullable ResourceTestOptions options, @NotNull @NotNull Task task, @NotNull @NotNull OperationResult parentResult) throws ObjectNotFoundException, SchemaException, ConfigurationException
  
  Tests 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. Operation result handling: The method records its operation into the provided `parentResult` in a usual way. However, as the client is usually interested in details of the processing, the method returns the reference to the relevant part of the operation result tree, representing the actual "test connection" operation. Care is taken to ensure that part is nicely displayable to the user. The operation codes in the returned OperationResult are defined by TestResourceOpNames enumeration class. See ResourceTestOptions for an explanation of the options and their default values.
  Parameters:
  
  resourceOid - OID of resource to test
  
  Returns:
  
  results of executed tests
  
  Throws:
  
  ObjectNotFoundException - resource or other required object (e.g. parent resource) does not exist
  
  IllegalArgumentException - wrong OID format
  
  GenericConnectorException - unknown connector framework error
  
  SchemaException
  
  ConfigurationException
  
  See Also:
  
  TestResourceOpNames
- testResource
  
  @NotNull default @NotNull OperationResult testResource(@NotNull @NotNull String resourceOid, @NotNull @NotNull Task task, @NotNull @NotNull OperationResult parentResult) throws ObjectNotFoundException, SchemaException, ConfigurationException
  
  Throws:
  
  ObjectNotFoundException
  
  SchemaException
  
  ConfigurationException
- testResource
  
  @NotNull @NotNull OperationResult testResource(@NotNull @NotNull PrismObject<ResourceType> resource, @Nullable @Nullable ResourceTestOptions options, @NotNull @NotNull Task task, OperationResult parentResult) throws ObjectNotFoundException, SchemaException, ConfigurationException
  
  Test the resource connection and basic resource connector functionality. This operation will *not* throw exception in case the resource connection fails. For more information about operation result handling please see testResource(String, Task, OperationResult) method description. TODO describe the difference to testResource(String, Task, OperationResult) and expected use of this method Notes: 1. The resource object must be mutable. 2. Normally it is expected that it will not have OID. But it may have one. The resource is _not_ updated in the repository, though, unless ResourceTestOptions.updateInRepository(Boolean) is explicitly set to Boolean.TRUE.
  Parameters:
  
  resource - resource to test
  
  Returns:
  
  results of executed tests
  
  Throws:
  
  GenericConnectorException - unknown connector framework error
  
  ObjectNotFoundException - some of required objects (like the parent resource) does not exist
  
  SchemaException
  
  ConfigurationException
  
  See Also:
  
  TestResourceOpNames
- testResource
  
  @NotNull default @NotNull OperationResult testResource(@NotNull @NotNull PrismObject<ResourceType> resource, @NotNull @NotNull Task task, OperationResult parentResult) throws ObjectNotFoundException, SchemaException, ConfigurationException
  
  Throws:
  
  ObjectNotFoundException
  
  SchemaException
  
  ConfigurationException
- testPartialConfiguration
  
  @NotNull default @NotNull OperationResult testPartialConfiguration(@NotNull @NotNull PrismObject<ResourceType> resource, @NotNull @NotNull Task task, @NotNull @NotNull OperationResult parentResult) throws SchemaException, ConfigurationException, ObjectNotFoundException
  
  Test partial resource connection. Actually, this is a convenience method for calling testResource(PrismObject, Task, OperationResult) with the ResourceTestOptions.testMode(ResourceTestOptions.TestMode) set to ResourceTestOptions.TestMode.PARTIAL (more detailed explanation is in the `PARTIAL` value documentation).
  Parameters:
  
  resource - resource to test
  
  Returns:
  
  results of executed tests
  
  Throws:
  
  GenericConnectorException - unknown connector framework error
  
  SchemaException
  
  ConfigurationException
  
  ObjectNotFoundException
  
  See Also:
  
  TestResourceOpNames
- discoverConfiguration
  
  @NotNull @NotNull DiscoveredConfiguration discoverConfiguration(@NotNull @NotNull PrismObject<ResourceType> resource, @NotNull @NotNull OperationResult parentResult)
  
  Discovers additional configuration properties. The resource object should contain minimal connector configuration properties to connect to the resource, then use the connection to discover additional configuration properties. Discovered configuration properties are returned from this method as Prism properties wrapped in DiscoveredConfiguration. DiscoveredConfiguration will be empty if it does not exist.
  
  Parameters:
  
  resource - resource with minimal connector configuration
  
  Returns:
  
  Suggested configuration properties wrapped in DiscoveredConfiguration.
- fetchSchema
  
  @Nullable @Nullable BareResourceSchema fetchSchema(@NotNull @NotNull PrismObject<ResourceType> resource, @NotNull @NotNull OperationResult parentResult)
  
  The operation fetches the resource schema using the connector configuration from provided resource object.
  
  Parameters:
  
  resource - resource with connector configuration
  
  Returns:
  
  Resource schema fetched by connector
- 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 null
  
  parentResult - 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
  
  Throws:
  
  SchemaException
  
  ObjectNotFoundException
  
  CommunicationException
  
  ConfigurationException
  
  ExpressionEvaluationException
- refreshShadow
  
  void refreshShadow(@NotNull @NotNull PrismObject<ShadowType> shadow, ProvisioningOperationOptions options, ProvisioningOperationContext context, @NotNull @NotNull Task task, @NotNull @NotNull OperationResult parentResult) throws SchemaException, ObjectNotFoundException, CommunicationException, ConfigurationException, ObjectAlreadyExistsException, SecurityViolationException, ExpressionEvaluationException, EncryptionException
  
  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.
  
  Throws:
  
  SchemaException
  
  ObjectNotFoundException
  
  CommunicationException
  
  ConfigurationException
  
  ObjectAlreadyExistsException
  
  SecurityViolationException
  
  ExpressionEvaluationException
  
  EncryptionException
- refreshShadow
  
  default void refreshShadow(PrismObject<ShadowType> shadow, ProvisioningOperationOptions options, Task task, OperationResult parentResult) throws SchemaException, ObjectNotFoundException, CommunicationException, ConfigurationException, ObjectAlreadyExistsException, SecurityViolationException, ExpressionEvaluationException, EncryptionException
  
  This is method doesn't take ProvisioningOperationContext as a parameter to simplify backward compatibility for now. It shouldn't be used, will be deprecated and removed after tests were updated accordingly.
  
  Throws:
  
  SchemaException
  
  ObjectNotFoundException
  
  CommunicationException
  
  ConfigurationException
  
  ObjectAlreadyExistsException
  
  SecurityViolationException
  
  ExpressionEvaluationException
  
  EncryptionException
- 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.
  
  Throws:
  
  SchemaException
  
  ObjectNotFoundException
  
  CommunicationException
  
  ConfigurationException
  
  ExpressionEvaluationException
- 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
  
  Throws:
  
  SchemaException
  
  ObjectNotFoundException
  
  CommunicationException
  
  ConfigurationException
  
  ExpressionEvaluationException
- 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.
  
  Throws:
  
  SchemaException
  
  ObjectNotFoundException
  
  CommunicationException
  
  ConfigurationException
  
  ExpressionEvaluationException
- 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.
  
  Throws:
  
  SchemaException
  
  ObjectNotFoundException
  
  CommunicationException
  
  ConfigurationException
  
  ExpressionEvaluationException
- updateShadowMarksAndPolicies
  
  void updateShadowMarksAndPolicies(PrismObject<ShadowType> shadow, boolean isNew, Task task, OperationResult parentResult) throws SchemaException, ObjectNotFoundException, CommunicationException, ConfigurationException, ExpressionEvaluationException, SecurityViolationException
  
  Determines effective shadow marks and policies, updating the shadow object in memory. This is to be used for externally acquired shadows, to make them look like all other shadows returned from the provisioning module. Usually called along with determineShadowState(PrismObject, Task, OperationResult). TODO consider merging these methods The `isNew` parameter should be true if we believe the shadow does not exist yet (on the resource nor in the repo). TODO reconsider the `isNew` parameter
  
  Throws:
  
  SchemaException
  
  ObjectNotFoundException
  
  CommunicationException
  
  ConfigurationException
  
  ExpressionEvaluationException
  
  SecurityViolationException
- 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. The query (for shadows) must comply with requirements similar to ones of searchObjects(Class, ObjectQuery, Collection, Task, OperationResult) method. See also ResourceSchemaUtil.findObjectDefinitionPrecisely(ResourceType, ShadowKindType, String, QName).
  
  Throws:
  
  SchemaException
  
  ObjectNotFoundException
  
  CommunicationException
  
  ConfigurationException
  
  ExpressionEvaluationException
- 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(ResourceObjectDefinition objectTypeDefinition, PrismObject<ShadowType> shadowObject, PrismObject<ShadowType> shadowObjectOld, ResourceType resource, String shadowOid, ConstraintViolationConfirmer constraintViolationConfirmer, ConstraintsCheckingStrategyType strategy, ProvisioningOperationContext context, @NotNull @NotNull Task task, @NotNull @NotNull OperationResult parentResult) throws CommunicationException, ObjectAlreadyExistsException, SchemaException, SecurityViolationException, ConfigurationException, ObjectNotFoundException, ExpressionEvaluationException
  
  TODO description
  
  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.
  
  Throws:
  
  ObjectNotFoundException
  
  CommunicationException
  
  SchemaException
  
  ConfigurationException
  
  SecurityViolationException
  
  ExpressionEvaluationException
  
  EncryptionException
- shutdown
  
  void shutdown()
- getSystemConfiguration
  
  SystemConfigurationType getSystemConfiguration()
  
  Temporary and quick hack. TODO fix this
- setSynchronizationSorterEvaluator
  
  void setSynchronizationSorterEvaluator(SynchronizationSorterEvaluator evaluator)
  
  Provides a sorter evaluator to the provisioning service.
- classifyResourceObject
  
  @NotNull @NotNull ResourceObjectClassification classifyResourceObject(@NotNull @NotNull ShadowType combinedObject, @NotNull @NotNull ResourceType resource, @Nullable @Nullable ObjectSynchronizationDiscriminatorType existingSorterResult, @NotNull @NotNull Task task, @NotNull @NotNull OperationResult result) throws SchemaException, ExpressionEvaluationException, CommunicationException, SecurityViolationException, ConfigurationException, ObjectNotFoundException
  
  Classifies resource object, i.e. determines its kind and intent (not the tag!). . Ignores existing shadow classification. . Invokes synchronization sorter, if it's defined for the resource. . Even if new classification is determined, does _not_ update shadow in the repository. If you need to classify an unclassified (and not fetched yet) shadow, it may be generally better to call getObject(Class, String, Collection, Task, OperationResult) method. It attempts to classify any unclassified objects retrieved.
  
  Parameters:
  
  combinedObject - Resource object combined with its shadow. Full "shadowization" is not required.
  
  Throws:
  
  SchemaException
  
  ExpressionEvaluationException
  
  CommunicationException
  
  SecurityViolationException
  
  ConfigurationException
  
  ObjectNotFoundException
- generateShadowTag
  
  @Nullable @Nullable String generateShadowTag(@NotNull @NotNull ShadowType combinedObject, @NotNull @NotNull ResourceType resource, @NotNull @NotNull ResourceObjectDefinition definition, @NotNull @NotNull Task task, @NotNull @NotNull OperationResult result) throws SchemaException, ExpressionEvaluationException, CommunicationException, SecurityViolationException, ConfigurationException, ObjectNotFoundException
  
  Generates shadow tag (for multi-account scenarios). . Ignores existing shadow tag. . Does _not_ update shadow in the repository.
  
  Throws:
  
  SchemaException
  
  ExpressionEvaluationException
  
  CommunicationException
  
  SecurityViolationException
  
  ConfigurationException
  
  ObjectNotFoundException
- expandConfigurationObject
  
  @Experimental void expandConfigurationObject(@NotNull @NotNull PrismObject<? extends ObjectType> configurationObject, @NotNull @NotNull Task task, @NotNull @NotNull OperationResult result) throws SchemaException, ConfigurationException, ObjectNotFoundException
  
  Expands (in-memory) configuration object by (e.g.) resolving references to super/template objects, and so on. The expansion is done in-place i.e. the object is directly modified by the operation. Provenance metadata are filled-in, see the description in OriginMarker. Assumes that there are no value metadata on entry! Currently implemented for resources.
  
  Throws:
  
  SchemaException
  
  ConfigurationException
  
  ObjectNotFoundException
- getNativeCapabilities
  
  @Experimental @NotNull @NotNull CapabilityCollectionType getNativeCapabilities(@NotNull @NotNull String connOid, OperationResult result) throws SchemaException, CommunicationException, ConfigurationException, ObjectNotFoundException
  
  Method create collection of capabilities which connector support. EXPERIMENTAL feature.
  
  Returns:
  
  Return supported operations for connector.
  
  Throws:
  
  SchemaException
  
  CommunicationException
  
  ConfigurationException
  
  ObjectNotFoundException
- getDefaultOperationPolicy
  
  @Nullable @Nullable ObjectOperationPolicyType getDefaultOperationPolicy(@NotNull @NotNull String resourceOid, @NotNull @NotNull ResourceObjectTypeIdentification typeIdentification, @NotNull @NotNull Task task, @NotNull @NotNull OperationResult result) throws SchemaException, ExpressionEvaluationException, CommunicationException, SecurityViolationException, ConfigurationException, ObjectNotFoundException
  
  Returns the default operation policy for given object type (if specified).
  
  Throws:
  
  SchemaException
  
  ExpressionEvaluationException
  
  CommunicationException
  
  SecurityViolationException
  
  ConfigurationException
  
  ObjectNotFoundException

Interface ProvisioningService

Method Summary

Method Details

getObject

getShadow

getObject

addObject

addObject

synchronize

synchronize

processAsynchronousUpdates

searchObjects

searchShadows

searchObjects

countObjects

countObjects

searchObjectsIterative

searchObjectsIterative

searchShadowsIterative

modifyObject

modifyObject

deleteObject

deleteObject

executeScript

testResource

testResource

testResource

testResource

testPartialConfiguration

discoverConfiguration

fetchSchema

discoverConnectors

getConnectorOperationalStatus

refreshShadow

refreshShadow

applyDefinition

applyDefinition

applyDefinition

determineShadowState

updateShadowMarksAndPolicies

applyDefinition

provisioningSelfTest

getProvisioningDiag

postInit

checkConstraints

enterConstraintsCheckerCache

exitConstraintsCheckerCache

compare

shutdown

getSystemConfiguration

setSynchronizationSorterEvaluator

classifyResourceObject

generateShadowTag

expandConfigurationObject

getNativeCapabilities

getDefaultOperationPolicy