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:
TODO: rich operation result

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 deleteObject(javax.xml.namespace.QName objectClass, 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(javax.xml.namespace.QName objectClass, Property lastToken, OperationResult parentResult)
          Token may be null.
 Property fetchCurrentToken(javax.xml.namespace.QName objectClass, OperationResult parentResult)
          Returns the latest token.
 ResourceObject fetchObject(javax.xml.namespace.QName objectClass, java.util.Set<ResourceObjectAttribute> identifiers, OperationResult parentResult)
          Retrieves a specific object from the resource.
 ResourceObject fetchObject(ResourceObjectDefinition resourceObjectDefinition, java.util.Set<ResourceObjectAttribute> identifiers, OperationResult parentResult)
           
 Schema fetchResourceSchema(OperationResult parentResult)
          Retrieves the schema from the resource.
 void modifyObject(javax.xml.namespace.QName 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(javax.xml.namespace.QName objectClass, ResourceObjectDefinition definition, ResultHandler handler, OperationResult parentResult)
          Execute iterative search operation.
 void test(OperationResult parentResult)
           
 

Method Detail

fetchResourceSchema

Schema fetchResourceSchema(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 always "freshly" fetched from the resource, it is not cached in any way. Therefore this may be quite an expensive operation.

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

fetchObject

ResourceObject fetchObject(javax.xml.namespace.QName objectClass,
                           java.util.Set<ResourceObjectAttribute> identifiers,
                           OperationResult parentResult)
                           throws ObjectNotFoundException,
                                  CommunicationException,
                                  GenericFrameworkException
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.
ObjectNotFoundException
GenericFrameworkException

fetchObject

ResourceObject fetchObject(ResourceObjectDefinition resourceObjectDefinition,
                           java.util.Set<ResourceObjectAttribute> identifiers,
                           OperationResult parentResult)
                           throws ObjectNotFoundException,
                                  CommunicationException,
                                  GenericFrameworkException
Throws:
ObjectNotFoundException
CommunicationException
GenericFrameworkException

search

void search(javax.xml.namespace.QName objectClass,
            ResourceObjectDefinition definition,
            ResultHandler handler,
            OperationResult parentResult)
            throws CommunicationException,
                   GenericFrameworkException
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
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

void modifyObject(javax.xml.namespace.QName 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. 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(javax.xml.namespace.QName objectClass,
                  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(javax.xml.namespace.QName 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(javax.xml.namespace.QName 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.