org.identityconnectors.framework.impl.api

Class AbstractConnectorFacade

java.lang.Object

org.identityconnectors.framework.impl.api.AbstractConnectorFacade

All Implemented Interfaces:

ConnectorFacade, APIOperation, AuthenticationApiOp, CreateApiOp, DeleteApiOp, DiscoverConfigurationApiOp, GetApiOp, ResolveUsernameApiOp, SchemaApiOp, ScriptOnConnectorApiOp, ScriptOnResourceApiOp, SearchApiOp, SyncApiOp, TestApiOp, UpdateApiOp, UpdateDeltaApiOp, ValidateApiOp

Direct Known Subclasses:

LocalConnectorFacadeImpl, RemoteConnectorFacadeImpl

public abstract class AbstractConnectorFacade
extends Object
implements ConnectorFacade

Implements all the methods of the facade.

Field Summary

Fields inherited from interface org.identityconnectors.framework.api.operations.APIOperation

NO_TIMEOUT

Constructor Summary

Constructors

Constructor and Description
AbstractConnectorFacade(APIConfigurationImpl configuration) Builds up the maps of supported operations and calls.
AbstractConnectorFacade(String configuration, AbstractConnectorInfo connectorInfo) Builds up the maps of supported operations and calls.

Method Summary

Modifier and Type	Method and Description
Uid	addAttributeValues(ObjectClass objclass, Uid uid, Set<Attribute> attrs, OperationOptions options) Update the object specified by the ObjectClass and Uid, adding to the current values of each attribute the values provided.
Uid	authenticate(ObjectClass objectClass, String username, GuardedString password, OperationOptions options) Most basic authentication available.
Uid	create(ObjectClass objectClass, Set<Attribute> createAttributes, OperationOptions options) Create a target object based on the specified attributes.
protected APIOperation	createLoggingProxy(Class<? extends APIOperation> api, APIOperation target) Creates a logging proxy.
protected APIOperation	createTimeoutProxy(Class<? extends APIOperation> api, APIOperation target) Creates the timeout proxy for the given operation.
void	delete(ObjectClass objectClass, Uid uid, OperationOptions options) Delete the object that the specified Uid identifies (if any).
Map<String,SuggestedValues>	discoverConfiguration() Discovers additional configuration properties.
protected APIConfigurationImpl	getAPIConfiguration()
String	getConnectorFacadeKey() Gets the unique generated identifier of this ConnectorFacade.
protected String	getInstanceName()
SyncToken	getLatestSyncToken(ObjectClass objectClass) Returns the token corresponding to the most recent synchronization event for any instance of the specified object class.
ConnectorObject	getObject(ObjectClass objectClass, Uid uid, OperationOptions options) Get a particular ConnectorObject based on the Uid.
APIOperation	getOperation(Class<? extends APIOperation> api) Return an instance of an API operation.
protected abstract APIOperation	getOperationImplementation(Class<? extends APIOperation> api) Gets the implementation of the given operation.
Set<Class<? extends APIOperation>>	getSupportedOperations() Get the set of operations that this ConnectorFacade will support.
protected APIOperation	newAPIOperationProxy(Class<? extends APIOperation> api, InvocationHandler handler) Creates a new APIOperation proxy given a handler.
Uid	removeAttributeValues(ObjectClass objclass, Uid uid, Set<Attribute> attrs, OperationOptions options) Update the object specified by the ObjectClass and Uid, removing from the current values of each attribute the values provided.
Uid	resolveUsername(ObjectClass objectClass, String username, OperationOptions options) Resolve the given authentication username to the corresponding Uid.
Object	runScriptOnConnector(ScriptContext request, OperationOptions options) Runs the script.
Object	runScriptOnResource(ScriptContext request, OperationOptions options) Runs a script on a specific target resource.
Schema	schema() Retrieve the basic schema of this Connector.
SearchResult	search(ObjectClass objectClass, Filter filter, ResultsHandler handler, OperationOptions options) Search the resource for all objects that match the object class and filter.
SyncToken	sync(ObjectClass objectClass, SyncToken token, SyncResultsHandler handler, OperationOptions options) Request synchronization events--i.e., native changes to target objects.
void	test() Tests the Configuration with the connector.
void	testPartialConfiguration() Tests partial configuration of the connector.
Uid	update(ObjectClass objectClass, Uid uid, Set<Attribute> attrs, OperationOptions options) Update the object specified by the ObjectClass and Uid, replacing the current values of each attribute with the values provided.
Set<AttributeDelta>	updateDelta(ObjectClass objectClass, Uid uid, Set<AttributeDelta> attrsDelta, OperationOptions options)
void	validate() Validates the configuration.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.identityconnectors.framework.api.ConnectorFacade

dispose

Constructor Detail

AbstractConnectorFacade

public AbstractConnectorFacade(APIConfigurationImpl configuration)

Builds up the maps of supported operations and calls.

AbstractConnectorFacade

public AbstractConnectorFacade(String configuration,
                               AbstractConnectorInfo connectorInfo)

Builds up the maps of supported operations and calls.

Method Detail

getOperation

public final APIOperation getOperation(Class<? extends APIOperation> api)

Return an instance of an API operation.

Specified by:

getOperation in interface ConnectorFacade

Returns:

null if the operation is not support otherwise return an instance of the operation.

See Also:

ConnectorFacade.getOperation(java.lang.Class)

getConnectorFacadeKey

public final String getConnectorFacadeKey()

Gets the unique generated identifier of this ConnectorFacade. It's not guaranteed that the equivalent configuration will generate the same configuration key. Always use the generated value and maintain it in the external application.

Specified by:

getConnectorFacadeKey in interface ConnectorFacade

Returns:

identifier of this ConnectorFacade instance.

getSupportedOperations

public final Set<Class<? extends APIOperation>> getSupportedOperations()

Get the set of operations that this ConnectorFacade will support.

Specified by:

getSupportedOperations in interface ConnectorFacade

schema

public final Schema schema()

Retrieve the basic schema of this Connector.

Specified by:

schema in interface SchemaApiOp

create

public final Uid create(ObjectClass objectClass,
                        Set<Attribute> createAttributes,
                        OperationOptions options)

Create a target object based on the specified attributes. The Connector framework always requires attribute ObjectClass. The Connector itself may require additional attributes. The API will confirm that the set contains the ObjectClass attribute and that no two attributes in the set have the same name.

Specified by:

create in interface CreateApiOp

Parameters:

objectClass - the type of object to create. Must not be null.

createAttributes - includes all the attributes necessary to create the target object (including the ObjectClass attribute).

options - additional options that impact the way this operation is run. May be null.

Returns:

the unique id for the object that is created. For instance in LDAP this would be the 'dn', for a database this would be the primary key, and for 'ActiveDirectory' this would be the GUID.

delete

public final void delete(ObjectClass objectClass,
                         Uid uid,
                         OperationOptions options)

Delete the object that the specified Uid identifies (if any).

Specified by:

delete in interface DeleteApiOp

Parameters:

objectClass - type of object to delete.

uid - The unique id that specifies the object to delete.

options - additional options that impact the way this operation is run. May be null.

search

public final SearchResult search(ObjectClass objectClass,
                                 Filter filter,
                                 ResultsHandler handler,
                                 OperationOptions options)

Search the resource for all objects that match the object class and filter.

Specified by:

search in interface SearchApiOp

Parameters:

objectClass - reduces the number of entries to only those that match the ObjectClass provided.

filter - Reduces the number of entries to only those that match the Filter provided, if any. May be null.

handler - class responsible for working with the objects returned from the search.

options - additional options that impact the way this operation is run. May be null.

Returns:

The query result or null.

update

public final Uid update(ObjectClass objectClass,
                        Uid uid,
                        Set<Attribute> attrs,
                        OperationOptions options)

Update the object specified by the ObjectClass and Uid, replacing the current values of each attribute with the values provided.

For each input attribute, replace all of the current values of that attribute in the target object with the values of that attribute.

If the target object does not currently contain an attribute that the input set contains, then add this attribute (along with the provided values) to the target object.

If the value of an attribute in the input set is null, then do one of the following, depending on which is most appropriate for the target:

• If possible, remove that attribute from the target object entirely.
• Otherwise, replace all of the current values of that attribute in the target object with a single value of null.

Specified by:

update in interface UpdateApiOp

Parameters:

objectClass - the type of object to modify. Must not be null.

uid - the uid of the object to modify. Must not be null.

attrs - set of new Attribute. the values in this set represent the new, merged values to be applied to the object. This set may also include operational attributes. Must not be null.

options - additional options that impact the way this operation is run. May be null.

Returns:

the Uid of the updated object in case the update changes the formation of the unique identifier.

updateDelta

public final Set<AttributeDelta> updateDelta(ObjectClass objectClass,
                                             Uid uid,
                                             Set<AttributeDelta> attrsDelta,
                                             OperationOptions options)

Specified by:

updateDelta in interface UpdateDeltaApiOp

addAttributeValues

public final Uid addAttributeValues(ObjectClass objclass,
                                    Uid uid,
                                    Set<Attribute> attrs,
                                    OperationOptions options)

Update the object specified by the ObjectClass and Uid, adding to the current values of each attribute the values provided.

For each attribute that the input set contains, add to the current values of that attribute in the target object all of the values of that attribute in the input set.

NOTE that this does not specify how to handle duplicate values. The general assumption for an attribute of a ConnectorObject is that the values for an attribute may contain duplicates. Therefore, in general simply append the provided values to the current value for each attribute.

IMPLEMENTATION NOTE: for connectors that merely implement UpdateOp and not UpdateAttributeValuesOp this method will be simulated by fetching, merging, and calling UpdateOp.update(ObjectClass, Uid, Set, OperationOptions). Therefore, connector implementations are encourage to implement UpdateAttributeValuesOp from a performance and atomicity standpoint.

Specified by:

addAttributeValues in interface UpdateApiOp

Parameters:

objclass - the type of object to modify. Must not be null.

uid - the uid of the object to modify. Must not be null.

attrs - set of Attribute deltas. The values for the attributes in this set represent the values to add to attributes in the object. merged. This set must not include operational attributes. Must not be null.

options - additional options that impact the way this operation is run. May be null.

Returns:

the Uid of the updated object in case the update changes the formation of the unique identifier.

removeAttributeValues

public final Uid removeAttributeValues(ObjectClass objclass,
                                       Uid uid,
                                       Set<Attribute> attrs,
                                       OperationOptions options)

Update the object specified by the ObjectClass and Uid, removing from the current values of each attribute the values provided.

For each attribute that the input set contains, remove from the current values of that attribute in the target object any value that matches one of the values of the attribute from the input set.

NOTE that this does not specify how to handle unmatched values. The general assumption for an attribute of a ConnectorObject is that the values for an attribute are merely representational state. Therefore, the implementer should simply ignore any provided value that does not match a current value of that attribute in the target object. Deleting an unmatched value should always succeed.

IMPLEMENTATION NOTE: for connectors that merely implement UpdateOp and not UpdateAttributeValuesOp this method will be simulated by fetching, merging, and calling UpdateOp.update(ObjectClass, Uid, Set, OperationOptions). Therefore, connector implementations are encourage to implement UpdateAttributeValuesOp from a performance and atomicity standpoint.

Specified by:

removeAttributeValues in interface UpdateApiOp

Parameters:

objclass - the type of object to modify. Must not be null.

uid - the uid of the object to modify. Must not be null.

attrs - set of Attribute deltas. The values for the attributes in this set represent the values to remove from attributes in the object. merged. This set must not include operational attributes. Must not be null.

options - additional options that impact the way this operation is run. May be null.

Returns:

the Uid of the updated object in case the update changes the formation of the unique identifier.

authenticate

public final Uid authenticate(ObjectClass objectClass,
                              String username,
                              GuardedString password,
                              OperationOptions options)

Most basic authentication available.

Specified by:

authenticate in interface AuthenticationApiOp

Parameters:

objectClass - The object class to use for authenticate. Will typically be an account. Must not be null.

username - string that represents the account or user id.

password - string that represents the password for the account or user.

options - additional options that impact the way this operation is run. May be null.

Returns:

Uid The uid of the account that was used to authenticate

resolveUsername

public final Uid resolveUsername(ObjectClass objectClass,
                                 String username,
                                 OperationOptions options)

Resolve the given authentication username to the corresponding Uid. The Uid is the one that AuthenticationApiOp.authenticate(org.identityconnectors.framework.common.objects.ObjectClass, java.lang.String, org.identityconnectors.common.security.GuardedString, org.identityconnectors.framework.common.objects.OperationOptions) would return in case of a successful authentication.

Specified by:

resolveUsername in interface ResolveUsernameApiOp

Parameters:

objectClass - The object class to use for authenticate. Will typically be an account. Must not be null.

username - string that represents the account or user id.

options - additional options that impact the way this operation is run. May be null.

Returns:

Uid The uid of the account that would be used to authenticate.

runScriptOnConnector

public final Object runScriptOnConnector(ScriptContext request,
                                         OperationOptions options)

Runs the script.

Specified by:

runScriptOnConnector in interface ScriptOnConnectorApiOp

Parameters:

request - The script and arguments to run.

options - Additional options that control how the script is run. The framework does not currently recognize any options but specific connectors might. Consult the documentation for each connector to identify supported options.

Returns:

The result of the script. The return type must be a type that the framework supports for serialization.

See Also:

for a list of supported return types.

runScriptOnResource

public final Object runScriptOnResource(ScriptContext request,
                                        OperationOptions options)

Runs a script on a specific target resource.

Specified by:

runScriptOnResource in interface ScriptOnResourceApiOp

Parameters:

request - The script and arguments to run.

options - Additional options which control how the script is run. Please refer to the connector documentation for supported options.

Returns:

The result of the script. The return type must be a type that the connector framework supports for serialization. See ObjectSerializerFactory for a list of supported return types.

getObject

public final ConnectorObject getObject(ObjectClass objectClass,
                                       Uid uid,
                                       OperationOptions options)

Get a particular ConnectorObject based on the Uid.

Specified by:

getObject in interface GetApiOp

Parameters:

objectClass - type of object to get.

uid - the unique id of the object that to get.

options - additional options that impact the way this operation is run. May be null.

Returns:

ConnectorObject based on the Uid provided or null if no such object could be found.

test

public final void test()

Tests the Configuration with the connector.

Specified by:

test in interface TestApiOp

validate

public final void validate()

Validates the configuration.

Specified by:

validate in interface ValidateApiOp

sync

public final SyncToken sync(ObjectClass objectClass,
                            SyncToken token,
                            SyncResultsHandler handler,
                            OperationOptions options)

Request synchronization events--i.e., native changes to target objects.

This method will call the specified handler once to pass back each matching synchronization event. Once this method returns, this method will no longer invoke the specified handler.

Each synchronization event contains a token that can be used to resume reading events starting from that point in the event stream. In typical usage, a client will save the token from the final synchronization event that was received from one invocation of this sync() method and then pass that token into that client's next call to this sync() method. This allows a client to "pick up where he left off" in receiving synchronization events. However, a client can pass the token from any synchronization event into a subsequent invocation of this sync() method. This will return synchronization events (that represent native changes that occurred) immediately subsequent to the event from which the client obtained the token.

A client that wants to read synchronization events "starting now" can call SyncApiOp.getLatestSyncToken(org.identityconnectors.framework.common.objects.ObjectClass) and then pass that token into this sync() method.

Specified by:

sync in interface SyncApiOp

Parameters:

objectClass - The class of object for which to return synchronization events. Must not be null.

token - The token representing the last token from the previous sync. The SyncResultsHandler will return any number of SyncDelta objects, each of which contains a token. Should be null if this is the client's first call to the sync() method for this connector.

handler - The result handler. Must not be null.

options - Options that affect the way this operation is run. May be null.

Returns:

The sync token or null.

getLatestSyncToken

public final SyncToken getLatestSyncToken(ObjectClass objectClass)

Returns the token corresponding to the most recent synchronization event for any instance of the specified object class.

An application that wants to receive synchronization events "starting now" --i.e., wants to receive only native changes that occur after this method is called-- should call this method and then pass the resulting token into the sync() method.

Specified by:

getLatestSyncToken in interface SyncApiOp

Parameters:

objectClass - the class of object for which to find the most recent synchronization event (if any).

Returns:

A token if synchronization events exist; otherwise null.

testPartialConfiguration

public final void testPartialConfiguration()

Tests partial configuration of the connector. It is similar to TestApiOp, however, it is supposed to be much more forgiving. While the TestApiOp.test() is supposed to test complete connector configuration, making sure that all features of the connector are working, this method does not make such a completeness requirement. The testPartialConfiguration() is supposed to test the very minimal configuration set, which is usually just a set of mandatory configuration properties. For most connectors this will be probably just a hostname, username and password.

This method returns successfully if the minimal configuration is correct, i.e. the connector could at least establish a basic connection to the resource. Return from this method does NOT indicate that connector is fully operational. This method will raise an appropriate exception in case that the configuration test fails.

Development note: Currently the connector does not have any means to know which configuration properties were explicitly configured, and which were set to default values. Therefore the connector does not know what parts of the configuration should be tested. E.g. CSV connector has "," as default value for separator. Connector has no way to tell whether the "," was explicitly configured by system administrator (hence it should test it), or it was set as a default value (hence it should NOT test it). For now, this is unlikely to be a major problem. There is probably some very basic set of configuration properties that are intuitively understood sa minimal configuration. Later, if that would cause problems, we can add a method to AbstractConfiguration or Configuration that could be used to retrieve a list of properties that were explicitly configured.

Specified by:

testPartialConfiguration in interface DiscoverConfigurationApiOp

discoverConfiguration

public final Map<String,SuggestedValues> discoverConfiguration()

Discovers additional configuration properties. The connector is supposed to use minimal configuration to connect to the resource, then use the connection to discover additional configuration properties. Discovered configuration properties are returned from this method (if any).

Only discovered values are present in the map. There is no need to add all configuration properties, or even repeat the configured values. Empty map means no suggestions, i.e. the current configuration is complete. Empty list of values in a specific means that there are no valid values. The connector suggests that the property should be configured with no value at all (null). In that case the connector knows that there should be no values. On the other hand, if a suggestion for a particular property is not present, the connector does not make any suggestion. The connector does not know anything about the property. Note: It may be difficult to distinguish explicitly configured properties and default values. Please see note in testPartialConfiguration() description.

Single-valued configuration properties can have multiple suggestions, e.i a list of suggested values can be returned. Individual suggested values should be considered to be options. One of them (or none at all) should be selected by the user. Similar approach applies to multi-valued configuration properties. However, in that case more than one of the values can be selected. I.e. the user can choose any combination of the suggested values (or no value at all).

Note: So far there is no support for suggesting several combinations of multi-valued configuration properties. This can be added later, by allowing suggested values to be collections (lists). However, this is not supported yet. For now the suggested values must be primitive (i.e. non-complex, non-collection) data types. We do not want to support it now, as it can be confusing in case that the value itself is complex (e.g a map). Therefore we leave this decision for the future when the design for complex values is more mature.

Specified by:

discoverConfiguration in interface DiscoverConfigurationApiOp

Returns:

Collection (map) of discovered configuration values. If no values can be discovered, empty collection should be returned. Null is not a legal return value.

newAPIOperationProxy

protected APIOperation newAPIOperationProxy(Class<? extends APIOperation> api,
                                            InvocationHandler handler)

Creates a new APIOperation proxy given a handler.

getOperationImplementation

protected abstract APIOperation getOperationImplementation(Class<? extends APIOperation> api)

Gets the implementation of the given operation.

Parameters:

api - The operation to implement.

Returns:

The implementation

getAPIConfiguration

protected final APIConfigurationImpl getAPIConfiguration()

createTimeoutProxy

protected final APIOperation createTimeoutProxy(Class<? extends APIOperation> api,
                                                APIOperation target)

Creates the timeout proxy for the given operation.

Parameters:

api - The operation

target - The underlying object

Returns:

The proxy

createLoggingProxy

protected final APIOperation createLoggingProxy(Class<? extends APIOperation> api,
                                                APIOperation target)

Creates a logging proxy.

Parameters:

api - The operation

target - The underlying object

Returns:

The proxy

getInstanceName

protected String getInstanceName()