IDM

ConnectorFacade interface

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the OpenICF documentation.

An application interacts with a connector through an instance of the ConnectorFacade class. The following diagram shows the creation and configuration of the connector facade. The components shown here are described in more detail in the sections that follow.

connector-info

The connector facade is instantiated and configured in the following steps:

  1. The application creates a LocalConnectorInfoManager instance (or instances) and adds the individual connector bundles (or assemblies).

    The LocalConnectorInfoManager processes these bundles or assemblies to instantiate a ConnectorInfo object.

    To be processed by the connector info manager, the connector bundle or assembly must have the following characteristics:

    Java Connector Bundle

    The META-INF/MANIFEST.MF file must include the following entries:

    • ConnectorBundle-FrameworkVersion - Minimum required OpenICF Framework version (either 1.1, 1.4, or 1.5)

    • ConnectorBundle-Name - Unique name of the connector bundle

    • ConnectorBundle-Version - Version of the connector bundle

    The combination of the ConnectorBundle-Name and the ConnectorBundle-Version must be unique.

    The connector bundle JAR must contain at least one class, that has the ConnectorClass annotation and implements the Connector interface.

    .NET Connector Assembly

    The AssemblyInfo.cs is used to determine the bundle version, from the AssemblyVersion property.

    The bundle name is derived from the Name property of the assembly. For more information, refer to the corresponding Microsoft documentation.

    If you change the name of your assembly, you must adjust the bundleName property in your connector configuration file, accordingly.

    The connector assembly DLL must contain at least one class, that has the ConnectorClassAttribute attribute and implements the Connector interface.

  2. For each connector, the LocalConnectorInfoManager processes the MessageCatalog, which contains the localized help and description messages for the configuration, and any log or error messages for the connector.

    Your application can use this information to provide additional help during the connector configuration process.

  3. For each connector, the LocalConnectorInfoManager then processes the ConfigurationClass, to build the configuration properties for the connector.

  4. Your application finds the connector info by its connector key. When the application has the connector info, it creates an API Configuration object that customizes the following components:

    • Object pool configuration

    • Result handler configuration

    • Configuration properties

    • Timeout configuration

    The API Configuration object is described in more detail in The API Configuration Object.

  5. The ConnectorFacade takes this customized API configuration object, determines which connector to use and how to configure it, and implements all of the OpenICF API operations.

Creating a ConnectorFacade

Applications access the connector API through a ConnectorFacade class, and interact with the connector through a ConnectorFacade instance.

The following steps describe how to create a ConnectorFacade in your application.

  1. Create a ConnectorInfoManager and acquire the ConnectorInfo object for your connector, as described in the previous section.

  2. From the ConnectorInfo object, create the default APIConfiguration.

    APIConfiguration apiConfig = info.createDefaultAPIConfiguration();

  3. Use the default APIConfiguration to set the ObjectPoolConfiguration, ResultsHandlerConfiguration, ConfigurationProperties, and TimeoutConfiguration.

    ConfigurationProperties properties = apiConfig.getConfigurationProperties();

  4. Set all of the ConfigurationProperties that you need for the connector, using setPropertyValue().

    properties.setPropertyValue("host", SAMPLE_HOST);
properties.setPropertyValue("adminName", SAMPLE_ADMIN);
properties.setPropertyValue("adminPassword", SAMPLE_PASSWORD);
properties.setPropertyValue("useSSL", false);

  5. Use the newInstance() method of the ConnectorFacadeFactory to create a new instance of the connector.

    ConnectorFacade conn = ConnectorFacadeFactory.getInstance()
        .newInstance(apiConfig);

  6. Validate that you have set up the connector configuration correctly.

    conn.validate();

  7. Use the new connector with the supported operations (described in the following sections).

    conn.[authenticate|create|update|delete|search|...]