org.forgerock.openicf.connectors.xml

Class XMLConnector

java.lang.Object

org.forgerock.openicf.connectors.xml.XMLConnector

All Implemented Interfaces:

Connector, AuthenticateOp, CreateOp, DeleteOp, SchemaOp, SearchOp<Query>, SPIOperation, TestOp, UpdateOp

public class XMLConnector
extends Object
implements Connector, AuthenticateOp, CreateOp, DeleteOp, SearchOp<Query>, SchemaOp, TestOp, UpdateOp

Since:

1.0

Version:

$Revision$ $Date$

Author:

$author$

Constructor Summary

Constructors

Constructor and Description
XMLConnector()

Method Summary

Modifier and Type	Method and Description
Uid	authenticate(ObjectClass objClass, String username, GuardedString password, OperationOptions options) Simple authentication with two parameters presumed to be user name and password.
Uid	create(ObjectClass objClass, Set<Attribute> attributes, OperationOptions options) The Connector developer is responsible for taking the attributes given (which always includes the ObjectClass) and create an object and its Uid.
FilterTranslator<Query>	createFilterTranslator(ObjectClass objClass, OperationOptions options) Creates a filter translator that will translate a specified filter into one or more native queries.
void	delete(ObjectClass objClass, 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() Dispose of any resources the Connector uses.
void	executeQuery(ObjectClass objClass, Query 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.
Configuration	getConfiguration() Return the configuration that was passed to Connector.init(Configuration).
void	init(Configuration configuration) Initialize the connector with its configuration.
Schema	schema() Describes the types of objects this Connector supports.
void	test() Tests the Configuration with the connector.
Uid	update(ObjectClass objClass, 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

Constructor Detail

XMLConnector

public XMLConnector()

Method Detail

getConfiguration

public Configuration getConfiguration()

Description copied from interface: Connector

Return the configuration that was passed to Connector.init(Configuration).

Specified by:

getConfiguration in interface Connector

Returns:

The configuration that was passed to Connector.init(Configuration).

init

public void init(Configuration configuration)

Description copied from interface: Connector

Initialize the connector with its configuration. For instance in a JDBC Connector this would include the database URL, password, and user.

Specified by:

init in interface Connector

Parameters:

configuration - instance of the Configuration object implemented by the Connector developer and populated with information in order to initialize the Connector.

dispose

public void dispose()

Description copied from interface: Connector

Dispose of any resources the Connector uses.

Specified by:

dispose in interface Connector

authenticate

public Uid authenticate(ObjectClass objClass,
                        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:

objClass - 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

create

public Uid create(ObjectClass objClass,
                  Set<Attribute> attributes,
                  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:

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

attributes - 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.

update

public Uid update(ObjectClass objClass,
                  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:

objClass - 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.

delete

public void delete(ObjectClass objClass,
                   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:

objClass - 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.

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.

createFilterTranslator

public FilterTranslator<Query> createFilterTranslator(ObjectClass objClass,
                                                      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<Query>

Parameters:

objClass - 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 objClass,
                         Query 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<Query>

Parameters:

objClass - 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.

test

public void test()

Description copied from interface: TestOp

Tests the Configuration with the connector.

Specified by:

test in interface TestOp