org.forgerock.openicf.misc.scriptedcommon

Class ScriptedConnectorBase<C extends ScriptedConfiguration>

java.lang.Object

org.forgerock.openicf.misc.scriptedcommon.ScriptedConnectorBase<C>

All Implemented Interfaces:

groovy.lang.GroovyObject, AuthenticateOp, CreateOp, DeleteOp, ResolveUsernameOp, SchemaOp, ScriptOnConnectorOp, ScriptOnResourceOp, SearchOp<Filter>, SPIOperation, SyncOp, TestOp, UpdateOp

Direct Known Subclasses:

ScriptedConnector, ScriptedCRESTConnector, ScriptedPoolableConnector, ScriptedRESTConnector, ScriptedSQLConnector, SSHConnector

public class ScriptedConnectorBase<C extends ScriptedConfiguration>
extends Object
implements AuthenticateOp, CreateOp, DeleteOp, ResolveUsernameOp, SchemaOp, ScriptOnConnectorOp, ScriptOnResourceOp, SearchOp<Filter>, SyncOp, TestOp, UpdateOp, groovy.lang.GroovyObject

Field Summary

Fields

Modifier and Type	Field and Description
static String	ATTRIBUTES
static String	BUILDER
protected C	configuration
static String	CONFIGURATION
static String	CONNECTION
static String	FILTER
static String	GROOVY
static String	HANDLER
static String	ID
static String	LOGGER
static String	OBJECT_CLASS
static String	OPERATION
static String	OPTIONS
static String	PASSWORD
static String	QUERY
static String	SCHEMA
static String	TOKEN
static String	UID
static String	USERNAME

Constructor Summary

Constructors

Constructor and Description
ScriptedConnectorBase()

Method Summary

Modifier and Type	Method and Description
Uid	addAttributeValues(ObjectClass objectClass, Uid uid, Set<Attribute> valuesToAdd, OperationOptions options)
Uid	authenticate(ObjectClass objectClass, String username, GuardedString password, OperationOptions options) Simple authentication with two parameters presumed to be user name and password.
Uid	create(ObjectClass objectClass, Set<Attribute> createAttributes, OperationOptions options) The Connector developer is responsible for taking the attributes given (which always includes the ObjectClass) and create an object and its Uid.
protected groovy.lang.Binding	createBinding(groovy.lang.Binding arguments, OperationType action, ObjectClass objectClass, Uid uid, Set<Attribute> attributes, OperationOptions options)
FilterTranslator<Filter>	createFilterTranslator(ObjectClass objectClass, OperationOptions options) Creates a filter translator that will translate a specified filter into one or more native queries.
void	delete(ObjectClass objectClass, Uid uid, OperationOptions options) The Connector developer is responsible for calling the native delete methods to remove the object specified by its unique id.
void	dispose()
protected Object	evaluateScript(String scriptName, groovy.lang.Binding arguments, groovy.lang.Closure<Object> scriptEvaluator)
protected Object	executeAddAttributeValues(String scriptName, ObjectClass objectClass, Uid uid, Set<Attribute> valuesToAdd, OperationOptions options)
protected Object	executeAuthenticate(String scriptName, ObjectClass objectClass, String username, GuardedString password, OperationOptions options)
protected Uid	executeCreate(String scriptName, ObjectClass objectClass, Set<Attribute> createAttributes, OperationOptions options)
protected void	executeDelete(String scriptName, ObjectClass objectClass, Uid uid, OperationOptions options)
protected Object	executeGetLatestSyncToken(String scriptName, ObjectClass objectClass)
void	executeQuery(ObjectClass objectClass, Filter query, ResultsHandler handler, OperationOptions options) ConnectorFacade calls this method once for each native query that the FilterTranslator produces in response to the Filter passed into SearchApiOp.
protected Object	executeQuery(String scriptName, ObjectClass objectClass, Filter query, groovy.lang.Closure<Boolean> handler, OperationOptions options)
protected Object	executeRemoveAttributeValues(String scriptName, ObjectClass objectClass, Uid uid, Set<Attribute> valuesToRemove, OperationOptions options)
protected Object	executeResolveUsername(String scriptName, ObjectClass objectClass, String username, OperationOptions options)
protected Object	executeRunScriptOnResource(String scriptName, ScriptContext request, OperationOptions options)
protected Object	executeSchema(String scriptName, Class<? extends Connector> connectorClass)
protected Object	executeSync(String scriptName, ObjectClass objectClass, SyncToken token, groovy.lang.Closure<Boolean> handler, OperationOptions options)
protected void	executeTest(String scriptName)
protected Object	executeUpdate(String scriptName, ObjectClass objectClass, Uid uid, Set<Attribute> replaceAttributes, OperationOptions options)
protected Object	genericUpdate(String scriptName, OperationType method, ObjectClass objectClass, Uid uid, Set<Attribute> attributes, OperationOptions options)
Configuration	getConfiguration()
SyncToken	getLatestSyncToken(ObjectClass objectClass) Returns the token corresponding to the most recent synchronization event.
groovy.lang.MetaClass	getMetaClass()
Object	getProperty(String property)
ScriptedConfiguration	getScriptedConfiguration()
protected groovy.lang.Closure<Object>	getScriptEvaluator()
void	init(Configuration config)
Object	invokeMethod(String method, Object arguments)
Uid	removeAttributeValues(ObjectClass objectClass, Uid uid, Set<Attribute> valuesToRemove, OperationOptions options)
Uid	resolveUsername(ObjectClass objectClass, String username, OperationOptions options) Resolve an object to its Uid based on its username.
protected Uid	returnUid(OperationType action, ObjectClass objectClass, Object uidAfter)
Object	runScriptOnConnector(ScriptContext request, OperationOptions options) Runs the script request.
Object	runScriptOnResource(ScriptContext request, OperationOptions options) Run the specified script on the target resource that this connector manages.
Schema	schema() Describes the types of objects this Connector supports.
void	setMetaClass(groovy.lang.MetaClass mc)
void	setProperty(String property, Object value)
void	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.
Uid	update(ObjectClass objectClass, Uid uid, Set<Attribute> replaceAttributes, OperationOptions options) Update the object specified by the ObjectClass and Uid, replacing the current values of each attribute with the values provided.

Methods inherited from class java.lang.Object

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

Field Detail

USERNAME

public static final String USERNAME

See Also:

Constant Field Values

PASSWORD

public static final String PASSWORD

See Also:

Constant Field Values

OPERATION

public static final String OPERATION

See Also:

Constant Field Values

OBJECT_CLASS

public static final String OBJECT_CLASS

See Also:

Constant Field Values

UID

public static final String UID

See Also:

Constant Field Values

ID

public static final String ID

See Also:

Constant Field Values

ATTRIBUTES

public static final String ATTRIBUTES

See Also:

Constant Field Values

OPTIONS

public static final String OPTIONS

See Also:

Constant Field Values

CONNECTION

public static final String CONNECTION

See Also:

Constant Field Values

SCHEMA

public static final String SCHEMA

See Also:

Constant Field Values

CONFIGURATION

public static final String CONFIGURATION

See Also:

Constant Field Values

LOGGER

public static final String LOGGER

See Also:

Constant Field Values

TOKEN

public static final String TOKEN

See Also:

Constant Field Values

HANDLER

public static final String HANDLER

See Also:

Constant Field Values

QUERY

public static final String QUERY

See Also:

Constant Field Values

BUILDER

public static final String BUILDER

See Also:

Constant Field Values

FILTER

public static final String FILTER

See Also:

Constant Field Values

GROOVY

public static final String GROOVY

See Also:

Constant Field Values

configuration

protected C extends ScriptedConfiguration configuration

Constructor Detail

ScriptedConnectorBase

public ScriptedConnectorBase()

Method Detail

getMetaClass

public groovy.lang.MetaClass getMetaClass()

Specified by:

getMetaClass in interface groovy.lang.GroovyObject

setMetaClass

public void setMetaClass(groovy.lang.MetaClass mc)

Specified by:

setMetaClass in interface groovy.lang.GroovyObject

invokeMethod

public Object invokeMethod(String method,
                           Object arguments)

Specified by:

invokeMethod in interface groovy.lang.GroovyObject

getProperty

public Object getProperty(String property)

Specified by:

getProperty in interface groovy.lang.GroovyObject

setProperty

public void setProperty(String property,
                        Object value)

Specified by:

setProperty in interface groovy.lang.GroovyObject

getConfiguration

public Configuration getConfiguration()

getScriptedConfiguration

public ScriptedConfiguration getScriptedConfiguration()

init

public void init(Configuration config)

dispose

public void dispose()

authenticate

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

Description copied from interface: AuthenticateOp

Simple authentication with two parameters presumed to be user name and password. The Connector developer is expected to attempt to authenticate these credentials natively. If the authentication fails the developer should throw a type of RuntimeException either IllegalArgumentException or if a native exception is available and if its of type RuntimeException simple throw it. If the native exception is not a RuntimeException wrap it in one and throw it. This will provide the most detail for logging problem and failed attempts.

The developer is of course encourage to try and throw the most informative exception as possible. In that regards there are several exceptions provided in the exceptions package. For instance one of the most common is InvalidPasswordException.

Specified by:

authenticate in interface AuthenticateOp

Parameters:

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

username - the name based credential for authentication.

password - the password based credential for authentication.

options - additional options that impact the way this operation is run. If the caller passes null, the framework will convert this into an empty set of options, so SPI need not worry about this ever being null.

Returns:

Uid The uid of the account that was used to authenticate

executeAuthenticate

protected Object executeAuthenticate(String scriptName,
                                     ObjectClass objectClass,
                                     String username,
                                     GuardedString password,
                                     OperationOptions options)

create

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

Description copied from interface: CreateOp

The Connector developer is responsible for taking the attributes given (which always includes the ObjectClass) and create an object and its Uid. The Connector developer must return the Uid so that the caller can refer to the created object.

*Note: There will never be a Uid passed in with the attribute set for this method. If the resource supports some sort of mutable Uid, you should create your own resource-specific attribute for it, such as unix_uid.

Specified by:

create in interface CreateOp

Parameters:

objectClass - the type of object to create. Will never be null.

createAttributes - includes all the attributes necessary to create the resource object including the ObjectClass attribute and Name attribute.

options - additional options that impact the way this operation is run. If the caller passes null, the framework will convert this into an empty set of options, so SPI need not worry about this ever being 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.

executeCreate

protected Uid executeCreate(String scriptName,
                            ObjectClass objectClass,
                            Set<Attribute> createAttributes,
                            OperationOptions options)

delete

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

Description copied from interface: DeleteOp

The Connector developer is responsible for calling the native delete methods to remove the object specified by its unique id.

Specified by:

delete in interface DeleteOp

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. If the caller passes null, the framework will convert this into an empty set of options, so SPI need not worry about this ever being null.

executeDelete

protected void executeDelete(String scriptName,
                             ObjectClass objectClass,
                             Uid uid,
                             OperationOptions options)
                      throws Exception

Throws:

Exception

resolveUsername

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

Description copied from interface: ResolveUsernameOp

Resolve an object to its Uid based on its username. This is a companion to the simple authentication. The difference is that this method does not have a password parameter and does not try to authenticate the credentials; instead, it returns the Uid corresponding to the username. Implementations method must, however, validate the username (i.e., they must throw and exception if the username does not correspond to an existing object).

If the username validation fails, the developer should throw a type of RuntimeException either IllegalArgumentException or if a native exception is available and if its of type RuntimeException simple throw it. If the native exception is not a RuntimeException wrap it in one and throw it. This will provide the most detail for logging problem and failed attempts.

The developer is of course encourage to try and throw the most informative exception as possible. In that regards there are several exceptions provided in the exceptions package. For instance one of the most common is UnknownUidException.

Specified by:

resolveUsername in interface ResolveUsernameOp

Parameters:

objectClass - The object class to resolve the username for. Will typically be an account. Will not be null.

username - the username to resolve. Will not be null.

options - additional options that impact the way this operation is run. If the caller passes null, the framework will convert this into an empty set of options, so SPI need not worry about this ever being null.

Returns:

Uid The uid of the object corresponding to the username.

executeResolveUsername

protected Object executeResolveUsername(String scriptName,
                                        ObjectClass objectClass,
                                        String username,
                                        OperationOptions options)

schema

public Schema schema()

Description copied from interface: SchemaOp

Describes the types of objects this Connector supports. This method is considered an operation since determining supported objects may require configuration information and allows this determination to be dynamic.

The special Uid attribute should never appear in the schema, as it is not a true attribute of an object, rather a reference to it. If your resource object-class has a writable unique id attribute that is different than its Name, then your schema should contain a resource-specific attribute that represents this unique id. For example, a Unix account object might contain unix_uid.

Specified by:

schema in interface SchemaOp

Returns:

basic schema supported by this Connector.

executeSchema

protected Object executeSchema(String scriptName,
                               Class<? extends Connector> connectorClass)

runScriptOnConnector

public Object runScriptOnConnector(ScriptContext request,
                                   OperationOptions options)

Description copied from interface: ScriptOnConnectorOp

Runs the script request.

Specified by:

runScriptOnConnector in interface ScriptOnConnectorOp

Parameters:

request - The script and arguments to run.

options - Additional options that control how the script is run.

Returns:

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

runScriptOnResource

public Object runScriptOnResource(ScriptContext request,
                                  OperationOptions options)

Description copied from interface: ScriptOnResourceOp

Run the specified script on the target resource that this connector manages.

Specified by:

runScriptOnResource in interface ScriptOnResourceOp

Parameters:

request - The script and arguments to run.

options - Additional options that control how the script is run.

Returns:

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

executeRunScriptOnResource

protected Object executeRunScriptOnResource(String scriptName,
                                            ScriptContext request,
                                            OperationOptions options)

createFilterTranslator

public FilterTranslator<Filter> createFilterTranslator(ObjectClass objectClass,
                                                       OperationOptions options)

Description copied from interface: SearchOp

Creates a filter translator that will translate a specified filter into one or more native queries. Each of these native queries will be passed subsequently into executeQuery().

Specified by:

createFilterTranslator in interface SearchOp<Filter>

Parameters:

objectClass - The object class for the search. Will never be null.

options - additional options that impact the way this operation is run. If the caller passes null, the framework will convert this into an empty set of options, so SPI need not worry about this ever being null.

Returns:

A filter translator. This must not be null. A null return value will cause the API ( SearchApiOp) to throw NullPointerException.

executeQuery

public void executeQuery(ObjectClass objectClass,
                         Filter query,
                         ResultsHandler handler,
                         OperationOptions options)

Description copied from interface: SearchOp

ConnectorFacade calls this method once for each native query that the FilterTranslator produces in response to the Filter passed into SearchApiOp. If the FilterTranslator produces more than one native query, then ConnectorFacade will automatically merge the results from each query and eliminate any duplicates. NOTE that this implies an in-memory data structure that holds a set of Uid values, so memory usage in the event of multiple queries will be O(N) where N is the number of results. This is why it is important that the FilterTranslator for each Connector implement OR if possible.

Specified by:

executeQuery in interface SearchOp<Filter>

Parameters:

objectClass - The object class for the search. Will never be null.

query - The native query to run. A value of null means "return every instance of the given object class".

handler - Results should be returned to this handler

options - Additional options that impact the way this operation is run. If the caller passes null, the framework will convert this into an empty set of options, so SPI need not guard against options being null.

executeQuery

protected Object executeQuery(String scriptName,
                              ObjectClass objectClass,
                              Filter query,
                              groovy.lang.Closure<Boolean> handler,
                              OperationOptions options)

sync

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

Description copied from interface: SyncOp

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 SyncOp.getLatestSyncToken(org.identityconnectors.framework.common.objects.ObjectClass) and then pass that token into this sync() method.

Specified by:

sync in interface SyncOp

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. If the caller passes null, the framework will convert this into an empty set of options, so an implementation need not guard against this being null.

executeSync

protected Object executeSync(String scriptName,
                             ObjectClass objectClass,
                             SyncToken token,
                             groovy.lang.Closure<Boolean> handler,
                             OperationOptions options)

getLatestSyncToken

public SyncToken getLatestSyncToken(ObjectClass objectClass)

Description copied from interface: SyncOp

Returns the token corresponding to the most recent synchronization event.

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 SyncOp

Parameters:

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

Returns:

A token if synchronization events exist; otherwise null.

executeGetLatestSyncToken

protected Object executeGetLatestSyncToken(String scriptName,
                                           ObjectClass objectClass)

test

public void test()

Description copied from interface: TestOp

Tests the Configuration with the connector.

Specified by:

test in interface TestOp

executeTest

protected void executeTest(String scriptName)

update

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

Description copied from interface: UpdateOp

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 UpdateOp

Parameters:

objectClass - the type of object to modify. Will never be null.

uid - the uid of the object to modify. Will never be null.

replaceAttributes - 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. Will never be null.

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

Returns:

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

executeUpdate

protected Object executeUpdate(String scriptName,
                               ObjectClass objectClass,
                               Uid uid,
                               Set<Attribute> replaceAttributes,
                               OperationOptions options)

addAttributeValues

public Uid addAttributeValues(ObjectClass objectClass,
                              Uid uid,
                              Set<Attribute> valuesToAdd,
                              OperationOptions options)

executeAddAttributeValues

protected Object executeAddAttributeValues(String scriptName,
                                           ObjectClass objectClass,
                                           Uid uid,
                                           Set<Attribute> valuesToAdd,
                                           OperationOptions options)

removeAttributeValues

public Uid removeAttributeValues(ObjectClass objectClass,
                                 Uid uid,
                                 Set<Attribute> valuesToRemove,
                                 OperationOptions options)

executeRemoveAttributeValues

protected Object executeRemoveAttributeValues(String scriptName,
                                              ObjectClass objectClass,
                                              Uid uid,
                                              Set<Attribute> valuesToRemove,
                                              OperationOptions options)

getScriptEvaluator

protected groovy.lang.Closure<Object> getScriptEvaluator()

evaluateScript

protected Object evaluateScript(String scriptName,
                                groovy.lang.Binding arguments,
                                groovy.lang.Closure<Object> scriptEvaluator)
                         throws Exception

Throws:

Exception

createBinding

protected groovy.lang.Binding createBinding(groovy.lang.Binding arguments,
                                            OperationType action,
                                            ObjectClass objectClass,
                                            Uid uid,
                                            Set<Attribute> attributes,
                                            OperationOptions options)

returnUid

protected Uid returnUid(OperationType action,
                        ObjectClass objectClass,
                        Object uidAfter)

genericUpdate

protected Object genericUpdate(String scriptName,
                               OperationType method,
                               ObjectClass objectClass,
                               Uid uid,
                               Set<Attribute> attributes,
                               OperationOptions options)