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.Set<ResourceObjectAttribute> addObject(ResourceObject object, java.util.Set<Operation> additionalOperations, OperationResult parentResult)
          TODO: This should return indication how the operation went, e.g.
 void configure(Configuration configuration, OperationResult parentResult)
          The connector instance will be configured to the state that it can immediately access the resource.
 void deleteObject(ResourceObjectDefinition objectClass, java.util.Set<Operation> additionalOperations, java.util.Set<ResourceObjectAttribute> identifiers, OperationResult parentResult)
           
 Property deserializeToken(java.lang.Object serializedToken)
          Creates a live Java object from a token previously serialized to string.
 java.util.List<Change> fetchChanges(ResourceObjectDefinition objectClass, Property lastToken, OperationResult parentResult)
          Token may be null.
 Property fetchCurrentToken(ResourceObjectDefinition objectClass, OperationResult parentResult)
          Returns the latest token.
 ResourceObject fetchObject(ResourceObjectDefinition objectClass, java.util.Set<ResourceObjectAttribute> identifiers, boolean returnDefaultAttributes, java.util.Set<ResourceObjectAttributeDefinition> attributesToReturn, OperationResult parentResult)
          Retrieves a specific object from the resource.
 Schema generateConnectorSchema()
           
 java.util.Set<java.lang.Object> getCapabilities(OperationResult parentResult)
          Retrieves native connector capabilities.
 Schema getResourceSchema(OperationResult parentResult)
          Retrieves the schema from the resource.
 void initialize(OperationResult parentResult)
          Get necessary information from the remote system.
 java.util.Set<AttributeModificationOperation> modifyObject(ResourceObjectDefinition objectClass, java.util.Set<ResourceObjectAttribute> identifiers, java.util.Set<Operation> changes, OperationResult parentResult)
          TODO: This should return indication how the operation went, e.g.
 void search(ResourceObjectDefinition objectClass, ResultHandler handler, OperationResult parentResult)
          Execute iterative search operation.
 void test(OperationResult parentResult)
           
 

Method Detail

configure

void configure(Configuration configuration,
               OperationResult parentResult)
               throws CommunicationException,
                      GenericFrameworkException,
                      SchemaException
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:
CommunicationException
GenericFrameworkException
SchemaException

generateConnectorSchema

Schema generateConnectorSchema()

initialize

void initialize(OperationResult parentResult)
                throws CommunicationException,
                       GenericFrameworkException
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

getCapabilities

java.util.Set<java.lang.Object> getCapabilities(OperationResult parentResult)
                                                throws CommunicationException,
                                                       GenericFrameworkException
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). The schema is retrieved from the connector instance and therefore it may be out-of-date. This must be called after a call to initialize() method.

Parameters:
parentResult -
Returns:
Throws:
CommunicationException
GenericFrameworkException

getResourceSchema

Schema getResourceSchema(OperationResult parentResult)
                         throws CommunicationException,
                                GenericFrameworkException
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. The schema is retrieved from the connector instance and therefore it may be out-of-date. This must be called after a call to initialize() method.

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

fetchObject

ResourceObject fetchObject(ResourceObjectDefinition objectClass,
                           java.util.Set<ResourceObjectAttribute> identifiers,
                           boolean returnDefaultAttributes,
                           java.util.Set<ResourceObjectAttributeDefinition> attributesToReturn,
                           OperationResult parentResult)
                           throws ObjectNotFoundException,
                                  CommunicationException,
                                  GenericFrameworkException,
                                  SchemaException
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

search

void search(ResourceObjectDefinition objectClass,
            ResultHandler 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.Set<ResourceObjectAttribute> addObject(ResourceObject 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<AttributeModificationOperation> modifyObject(ResourceObjectDefinition objectClass,
                                                           java.util.Set<ResourceObjectAttribute> identifiers,
                                                           java.util.Set<Operation> changes,
                                                           OperationResult parentResult)
                                                           throws ObjectNotFoundException,
                                                                  CommunicationException,
                                                                  GenericFrameworkException,
                                                                  SchemaException
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

deleteObject

void deleteObject(ResourceObjectDefinition objectClass,
                  java.util.Set<Operation> additionalOperations,
                  java.util.Set<ResourceObjectAttribute> identifiers,
                  OperationResult parentResult)
                  throws ObjectNotFoundException,
                         CommunicationException,
                         GenericFrameworkException
Throws:
ObjectNotFoundException
CommunicationException
GenericFrameworkException

deserializeToken

Property 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

Property fetchCurrentToken(ResourceObjectDefinition 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(ResourceObjectDefinition objectClass,
                                    Property lastToken,
                                    OperationResult parentResult)
                                    throws CommunicationException,
                                           GenericFrameworkException,
                                           SchemaException
Token may be null. That means "from the beginning of history".

Parameters:
lastToken -
Returns:
Throws:
CommunicationException
GenericFrameworkException
SchemaException

test

void test(OperationResult parentResult)


Copyright © 2011 evolveum. All Rights Reserved.