ICF 1.5.20.25

Connector instance management

The ICF framework supports multiple connector types, based on the implementation of the connector interface, and the configuration interface. These two interfaces determine the following:

  • Whether the connector instance is obtained from a pool or whether a new instance is created for each operation.

  • Whether the connector configuration instance is retained and reused for each operation (stateful configuration), or a new configuration instance is created for each operation (stateless).

Connector developers determine which type of connector to implement, assessing the best match for the resource to which they are connecting. The interaction between the connector and configuration interface implementations is described in detail in Connector types. This section illustrates how the ICF framework manages connector instantiation, depending on the connector type.

Instantiate a stateless, non-poolable connector

The most basic connector has a stateless configuration, and is not pooled. A basic connector is initialized as follows:

  1. The application calls an operation (for example, CREATE) on the connector facade.

  2. The ICF framework creates a new configuration instance, and initializes it with its configuration properties.

  3. When the framework has the configuration instance, with all the attributes in the configuration set, the framework creates a new connector instance, and initializes it, with the configuration that has been set.

  4. The framework executes the operation (for example, CREATE) on the connector instance.

  5. The connector instance executes the operation on the resource.

  6. The framework calls the dispose() method to release all resources that the connector instance was using.

The following illustration shows the initialization process for a basic connector, and references the numbered steps in the preceding list.

connector-init-1

Instantiate a stateless, poolable connector

The second connector type has a stateless configuration, but can be pooled. A stateless, poolable connector is instantiated as follows:

  1. The application calls an operation (for example, CREATE) on the connector facade.

  2. The ICF framework calls on the object pool, to borrow a live connector instance to execute the operation.

    If the object pool has an idle connector instance available, the framework borrows that one instance (step 5a in the illustration that follows).

    The framework calls the checkAlive method on the customized connector instance with its configuration, to check if the instance that was borrowed from the pool is still alive, and ready to execute the operation. If the instance is no longer alive and ready, the framework disposes of the instance and borrows another one.

    The thread that borrows the object has exclusive access to that connector instance; that is, it is thread-safe.

  3. If the object pool has no idle connector instances, the pool creates a new connector instance.

  4. The framework creates a new configuration instance, and initializes it with its configuration properties.

  5. The framework initializes the borrowed connector instance, with the configuration that has been set.

  6. The framework executes the operation (for example, CREATE) on the connector instance.

  7. The connector instance executes the operation on the resource.

  8. When the operation is complete, the framework releases the connector instance back into the pool. No dispose() method is called.

The following illustration shows the initialization process for a stateless, poolable connector, and references the numbered steps in the preceding list.

connector-init-2

Instantiate a stateful, non-poolable connector

The third connector type has a stateful configuration, and cannot be pooled. A stateful, non-poolable connector is instantiated as follows:

  1. The ICF framework creates a new configuration instance, initializes it with its configuration properties, and stores it in the connector facade, before any operations are called.

    This single configuration instance is shared between multiple threads. The framework does not guarantee isolation, so connector developers must ensure that their implementation is thread-safe.

  2. The application calls an operation (for example, CREATE) on the connector facade.

  3. The ICF framework creates a new connector instance, and calls the init() method on that connector instance, with the stored configuration. The framework initializes the connector with the single configuration instance stored within the connector facade.

  4. The framework executes the operation (for example, CREATE) on the connector instance.

  5. The connector instance executes the operation on the resource.

  6. The framework calls the dispose() method to release all resources that the connector instance was using.

    Note that the customized config instance remains in the connector facade, and is reused for the next operation.

The following illustration shows the initialization process for a non-poolable connector, with a stateful configuration. The illustration references the numbered steps in the preceding list.

connector-init-3

Instantiate a stateful, poolable connector

The fourth connector type has a stateful configuration, and can be pooled. A stateful, poolable connector is instantiated as follows:

  1. The ICF framework creates a new configuration instance, initializes it with its configuration properties, and stores it in the connector facade, before any operations are called.

    This single configuration instance is shared between multiple threads. The framework does not guarantee isolation, so connector developers must ensure that their implementation is thread-safe.

  2. The application calls an operation (for example, CREATE) on the connector facade.

  3. The framework calls on the object pool, to borrow a live connector instance to execute the operation.

    If the object pool has an idle connector instance available, the framework borrows that one instance (step 5a in the illustration that follows).

    The framework calls the checkAlive method on the customized connector instance with its configuration, to check if the instance that was borrowed from the pool is still alive, and ready to execute the operation. If the instance is no longer alive and ready, the framework disposes of the instance and borrows another one.

    The thread that borrows the object has exclusive access to that connector instance; that is, it is thread-safe.

  4. If the object pool has no idle connector instances, the pool creates a new connector instance.

  5. The framework initializes the borrowed connector instance, with the stored configuration.

  6. The framework executes the operation (for example, CREATE) on the connector instance.

  7. The connector instance executes the operation on the resource.

  8. When the operation is complete, the framework releases the connector instance back into the pool. No dispose() method is called.

The following illustration shows the initialization process for a stateful, poolable connector, and references the numbered steps in the preceding list.

connector-init-4
Copyright © 2010-2024 ForgeRock, all rights reserved.