com.evolveum.midpoint.provisioning.ucf.api
Interface ConnectorInstance

All Known Implementing Classes:
ConnectorInstanceIcfImpl

public interface ConnectorInstance

Connector instance configured for a specific resource. This is kind of connector facade. It is an API provided by the "Unified Connector Framework" to the midPoint provisioning component. There is no associated SPI yet. That may come in the future when this interface stabilizes a bit. This interface provides an unified facade to a connector capabilities in the Unified Connector Framework interface. The connector is configured to a specific resource instance and therefore can execute operations on resource. Calls to this interface always try to reach the resource and get the actual state on resource. The connectors are not supposed to cache any information. Therefore the methods do not follow get/set java convention as the data are not regular javabean properties.

Author:
Radovan Semancik
See Also:
ConnectorFactory

Method Summary
 java.util.Collection<ResourceAttribute<?>> addObject(PrismObject<? extends ResourceObjectShadowType> object, java.util.Set<Operation> additionalOperations, OperationResult parentResult)
          TODO: This should return indication how the operation went, e.g.
 void configure(PrismContainerValue configuration, OperationResult parentResult)
          The connector instance will be configured to the state that it can immediately access the resource.
 void deleteObject(ObjectClassComplexTypeDefinition objectClass, java.util.Set<Operation> additionalOperations, java.util.Collection<? extends ResourceAttribute> identifiers, OperationResult parentResult)
           
 PrismProperty<?> deserializeToken(java.lang.Object serializedToken)
          Creates a live Java object from a token previously serialized to string.
 java.util.List<Change> fetchChanges(ObjectClassComplexTypeDefinition objectClass, PrismProperty lastToken, OperationResult parentResult)
          Token may be null.
 PrismProperty<?> fetchCurrentToken(ObjectClassComplexTypeDefinition objectClass, OperationResult parentResult)
          Returns the latest token.
<T extends ResourceObjectShadowType>
PrismObject<T>
fetchObject(java.lang.Class<T> type, ObjectClassComplexTypeDefinition objectClassDefinition, java.util.Collection<? extends ResourceAttribute> identifiers, boolean returnDefaultAttributes, java.util.Collection<? extends ResourceAttributeDefinition> attributesToReturn, OperationResult parentResult)
          Retrieves a specific object from the resource.
 PrismSchema generateConnectorSchema()
           
 java.util.Collection<java.lang.Object> getCapabilities(OperationResult parentResult)
          Retrieves native connector capabilities.
 ResourceSchema getResourceSchema(OperationResult parentResult)
          Retrieves the schema from the resource.
 void initialize(OperationResult parentResult)
          Get necessary information from the remote system.
 java.util.Set<PropertyModificationOperation> modifyObject(ObjectClassComplexTypeDefinition objectClass, java.util.Collection<? extends ResourceAttribute> identifiers, java.util.Collection<Operation> changes, OperationResult parentResult)
          TODO: This should return indication how the operation went, e.g.
<T extends ResourceObjectShadowType>
void
search(java.lang.Class<T> type, ObjectClassComplexTypeDefinition objectClassDefinition, ObjectQuery query, ResultHandler<T> handler, OperationResult parentResult)
          Execute iterative search operation.
 void test(OperationResult parentResult)
           
 

Method Detail

configure

void configure(PrismContainerValue configuration,
               OperationResult parentResult)
               throws CommunicationException,
                      GenericFrameworkException,
                      SchemaException,
                      ConfigurationException
The connector instance will be configured to the state that it can immediately access the resource. The resource configuration is provided as a parameter to this method.

Parameters:
configuration -
Throws:
ConfigurationException
CommunicationException
GenericFrameworkException
SchemaException

generateConnectorSchema

PrismSchema generateConnectorSchema()

initialize

void initialize(OperationResult parentResult)
                throws CommunicationException,
                       GenericFrameworkException,
                       ConfigurationException
Get necessary information from the remote system. This method will initialized the configured connector. It may contact the remote system in order to do so, e.g. to download the schema. It will the cache the information inside connector instance until this method is called again. It must be called after configure() and before any other method that is accessing the resource.

Parameters:
parentResult -
Throws:
CommunicationException
GenericFrameworkException
ConfigurationException

getCapabilities

java.util.Collection<java.lang.Object> getCapabilities(OperationResult parentResult)
                                                       throws CommunicationException,
                                                              GenericFrameworkException,
                                                              ConfigurationException
Retrieves native connector capabilities. The capabilities specify what the connector can do without any kind of simulation or other workarounds. The set of capabilities may depend on the connector configuration (e.g. if a "disable" or password attribute was specified in the configuration or not). It may return null. Such case means that the capabilities cannot be determined.

Parameters:
parentResult -
Returns:
Throws:
CommunicationException
GenericFrameworkException
ConfigurationException

getResourceSchema

ResourceSchema getResourceSchema(OperationResult parentResult)
                                 throws CommunicationException,
                                        GenericFrameworkException,
                                        ConfigurationException
Retrieves the schema from the resource. The schema may be considered to be an XSD schema, but it is returned in a "parsed" format and it is in fact a bit stricter and richer midPoint schema. It may return null. Such case means that the schema cannot be determined.

Returns:
Up-to-date resource schema.
Throws:
CommunicationException - error in communication to the resource - nothing was fetched.
ConfigurationException
GenericFrameworkException
See Also:
PrismSchema

fetchObject

<T extends ResourceObjectShadowType> PrismObject<T> fetchObject(java.lang.Class<T> type,
                                                                ObjectClassComplexTypeDefinition objectClassDefinition,
                                                                java.util.Collection<? extends ResourceAttribute> identifiers,
                                                                boolean returnDefaultAttributes,
                                                                java.util.Collection<? extends ResourceAttributeDefinition> attributesToReturn,
                                                                OperationResult parentResult)
                                                            throws ObjectNotFoundException,
                                                                   CommunicationException,
                                                                   GenericFrameworkException,
                                                                   SchemaException,
                                                                   SecurityViolationException
Retrieves a specific object from the resource. This method is fetching an object from the resource that is identified by its primary identifier. It is a "targeted" method in this aspect and it will fail if the object is not found. The objectClass provided as a parameter to this method must correspond to one of the object classes in the schema. The object class must match the object. If it does not, the behavior of this operation is undefined. The returned ResourceObject is "disconnected" from schema. It means that any call to the getDefinition() method of the returned object will return null. TODO: object not found error

Parameters:
objectClass - objectClass of the object to fetch (QName).
identifiers - primary identifiers of the object.
Returns:
object fetched from the resource (no schema)
Throws:
CommunicationException - error in communication to the resource - nothing was fetched.
SchemaException - error converting object from native (connector) format
ObjectNotFoundException
GenericFrameworkException
SecurityViolationException

search

<T extends ResourceObjectShadowType> void search(java.lang.Class<T> type,
                                                 ObjectClassComplexTypeDefinition objectClassDefinition,
                                                 ObjectQuery query,
                                                 ResultHandler<T> handler,
                                                 OperationResult parentResult)
            throws CommunicationException,
                   GenericFrameworkException,
                   SchemaException
Execute iterative search operation. This method will execute search operation on the resource and will pass any objects that are found. A "handler" callback will be called for each of the objects found. The call to this method will return only after all the callbacks were called, therefore it is not asynchronous in a strict sense. TODO: filter

Parameters:
objectClass -
handler -
Throws:
CommunicationException
SchemaException - error converting object from the native (connector) format
GenericFrameworkException

addObject

java.util.Collection<ResourceAttribute<?>> addObject(PrismObject<? extends ResourceObjectShadowType> object,
                                                     java.util.Set<Operation> additionalOperations,
                                                     OperationResult parentResult)
                                                     throws CommunicationException,
                                                            GenericFrameworkException,
                                                            SchemaException,
                                                            ObjectAlreadyExistsException
TODO: This should return indication how the operation went, e.g. what changes were applied, what were not and what were not determined. The exception should be thrown only if the connector is sure that nothing was done on the resource. E.g. in case of connect timeout or connection refused. Timeout during operation should not cause the exception as something might have been done already. The connector may return some (or all) of the attributes of created object. The connector should do this only such operation is efficient, e.g. in case that the created object is normal return value from the create operation. The connector must not execute additional operation to fetch the state of created resource. In case that the new state is not such a normal result, the connector must return null. Returning empty set means that the connector supports returning of new state, but nothing was returned (e.g. due to a limiting configuration). Returning null means that connector does not support returning of new object state and the caller should explicitly invoke fetchObject() in case that the information is needed.

Parameters:
object -
additionalOperations -
Returns:
created object attributes. May be null.
Throws:
CommunicationException
SchemaException - resource schema violation
ObjectAlreadyExistsException - object already exists on the resource
GenericFrameworkException

modifyObject

java.util.Set<PropertyModificationOperation> modifyObject(ObjectClassComplexTypeDefinition objectClass,
                                                          java.util.Collection<? extends ResourceAttribute> identifiers,
                                                          java.util.Collection<Operation> changes,
                                                          OperationResult parentResult)
                                                          throws ObjectNotFoundException,
                                                                 CommunicationException,
                                                                 GenericFrameworkException,
                                                                 SchemaException,
                                                                 SecurityViolationException
TODO: This should return indication how the operation went, e.g. what changes were applied, what were not and what results are we not sure about. Returns a set of attributes that were changed as a result of the operation. This may include attributes that were changed as a side effect of the operations, e.g. attributes that were not originally specified in the "changes" parameter. The exception should be thrown only if the connector is sure that nothing was done on the resource. E.g. in case of connect timeout or connection refused. Timeout during operation should not cause the exception as something might have been done already.

Parameters:
identifiers -
changes -
Throws:
CommunicationException
SchemaException
ObjectNotFoundException
GenericFrameworkException
SecurityViolationException

deleteObject

void deleteObject(ObjectClassComplexTypeDefinition objectClass,
                  java.util.Set<Operation> additionalOperations,
                  java.util.Collection<? extends ResourceAttribute> identifiers,
                  OperationResult parentResult)
                  throws ObjectNotFoundException,
                         CommunicationException,
                         GenericFrameworkException
Throws:
ObjectNotFoundException
CommunicationException
GenericFrameworkException

deserializeToken

PrismProperty<?> deserializeToken(java.lang.Object serializedToken)
Creates a live Java object from a token previously serialized to string. Serialized token is not portable to other connectors or other resources. However, newer versions of the connector should understand tokens generated by previous connector version.

Parameters:
serializedToken -
Returns:

fetchCurrentToken

PrismProperty<?> fetchCurrentToken(ObjectClassComplexTypeDefinition objectClass,
                                   OperationResult parentResult)
                                   throws CommunicationException,
                                          GenericFrameworkException
Returns the latest token. In other words, returns a token that corresponds to a current state of the resource. If fetchChanges is immediately called with this token, nothing should be returned (Figuratively speaking, neglecting concurrent resource modifications).

Returns:
Throws:
CommunicationException
GenericFrameworkException

fetchChanges

java.util.List<Change> fetchChanges(ObjectClassComplexTypeDefinition objectClass,
                                    PrismProperty lastToken,
                                    OperationResult parentResult)
                                    throws CommunicationException,
                                           GenericFrameworkException,
                                           SchemaException,
                                           ConfigurationException
Token may be null. That means "from the beginning of history".

Parameters:
lastToken -
Returns:
Throws:
CommunicationException
GenericFrameworkException
SchemaException
ConfigurationException

test

void test(OperationResult parentResult)


Copyright © 2012 evolveum. All Rights Reserved.