ICF 1.5.20.21

Configuration interface

The ICF connector framework uses the configuration interface implementation to build the configuration properties inside the API configuration.

The configuration interface implementation includes the required information to enable the connector to connect to the target system, and to perform its operations. The configuration interface implements getters and setters for each of its defined properties. It also provides a validate method that your application can use to check whether all the required properties are available, and valid, before passing them to the connector.

The configuration interface has three methods:

  • setConnectorMessages(ConnectorMessages messages) sets the message catalog instance, and lets the connector provide localized messages.

    The message catalog is defined in the file Messages.properties, and can be localized as required by appending the locale to the file name, for example, Messages_fr.properties. For more information on the message catalog, refer to Connector messages object.

  • getConnectorMessages() returns the message catalog that is set by setConnectorMessages(ConnectorMessages).

  • validate() checks that all the required properties have been set and that their values are valid.

    The purpose of this method is to test that the configuration that the application provides to your connector is valid.

Each property that is declared is not necessarily required. If a property is required, it must be included in the ConfigurationProperty annotation.

The ConfigurationProperty annotation (Java) or attribute (.NET) lets you add custom meta information to properties. The ICF framework scans the meta information and collects this information to build the ConfigurationProperties object inside the APIConfiguration. The following meta information can be provided:

Element Description Implementation in Java Implementation in C#

order

The order in which this property is displayed

helpMessageKey

Lets you change the default help message key

propertyName.help

help_propertyName

displayMessageKey

Lets you change the default display message key

propertyName.display

display_propertyName

groupMessageKey

Lets you change the default group message key

propertyName.group

group_propertyName

confidential

Indicates that this is a confidential property and that its value should be encrypted by the application when persisted

required

Boolean, indicates whether the property is required

operations

The array of operations that require this property

The following examples show how the meta information is provided, in both Java and C#.

  • Java

  • C#

Stateless Configuration Implementation (Java)
public class SampleConfiguration extends AbstractConfiguration  {

    /**
     * {@inheritDoc}
     */
    public void validate() {
    }

    @ConfigurationProperty(
        order = 1,
        helpMessageKey = "passwordFieldName.help",
        displayMessageKey = "passwordFieldName.display",
        groupMessageKey = "authenticateOp.group",
        confidential = false,
        required = false,
        operations = {AuthenticateOp.class,CreateOp.class}
    )
    public String getPasswordFieldName() {
        return passwordFieldName;
    }

    public void setPasswordFieldName(String value) {
        passwordFieldName = value;
    }
}
Stateless Configuration Implementation (C#)
public class ActiveDirectoryConfiguration : AbstractConfiguration
    {

        [ConfigurationProperty(
            Order = 1,
            HelpMessageKey = "help_PasswordFieldName",
            DisplayMessageKey = "display_PasswordFieldName",
            GroupMessageKey = "group_PasswordFieldName",
            Confidential = false,
            Required = false,
            OperationTypes = new[] { typeof(AuthenticateOp) })
        ]
        public String PasswordFieldName
        { get; set; }

        public override void Validate()
        {
            throw new NotImplementedException();
        }
    }

  • Java

  • C#

Stateful Configuration Implementation (Java)
public class SampleConfiguration extends AbstractConfiguration
    implements StatefulConfiguration {

    /**
     * {@inheritDoc}
     */
    public void release() {
    }

    /**
     * {@inheritDoc}
     */
    public void validate() {
    }
}
Stateful Configuration Implementation (C#)
public class ActiveDirectoryConfiguration : AbstractConfiguration,
    StatefulConfiguration
    {

        public override void Validate()
        {
            throw new NotImplementedException();
        }

        public void Release()
        {
            throw new NotImplementedException();
        }
    }

Validate operation

The validate operation validates the connector configuration. A valid configuration is one that is ready to be used by the connector.

A configuration that is ready, has the following characteristics:

  • It is complete, that is, all required properties are present and have values.

  • All property values are well-formed, that is, they are in the expected range and have the expected format.

ValidateApiOp

The validate operation returns a ConfigurationException in the following situations:

  • The Framework version is not compatible with the connector.

  • The connector does not have the required attributes in MANIFEST.MF.

  • The ConfigurationProperties cannot be merged into the configuration.

Implementation of the valid operation, at the API Level
@Test
public void ValidateTest() {
    logger.info("Running Validate Test");
    final ConnectorFacade facade = createConnectorFacade(BasicConnector.class, null);
    facade.validate();
}

Validate SPI implementation

The validate() method of the configuration operation must return one of the following:

  • RuntimeException if the configuration is not valid.

  • NullPointerException if a required configuration property is null.

  • IllegalArgumentException if a required configuration property is blank.

Implementation of the validate method
public void validate() {
    if (StringUtil.isBlank(host)) {
        throw new IllegalArgumentException("Host User cannot be null or empty.");
    }

    Assertions.blankCheck(remoteUser, "remoteUser");

    Assertions.nullCheck(password, "password");
}

Supported configuration types

The ICF framework supports a limited number of configuration property types. This limitation is necessary, because ICF must serialise and deserialize the configuration property values when sending them over the network.

You can use any of the following types, or an array of these types. Lists of types are not supported.

String.class
long.class
Long.class
char.class
Character.class
double.class
Double.class
float.class
Float.class
int.class
Integer.class
boolean.class
Boolean.class
URI.class
File.class
GuardedByteArray.class
GuardedString.class
Script.class
typeof(string),
typeof(long),
typeof(long?),
typeof(char),
typeof(char?),
typeof(double),
typeof(double?),
typeof(float),
typeof(float?),
typeof(int),
typeof(int?),
typeof(bool),
typeof(bool?),
typeof(Uri),
typeof(FileName),
typeof(GuardedByteArray),
typeof(GuardedString),
typeof(Script)

The framework introspects the implemented configuration class and adds all properties that have a set/get method to the ConfigurationProperties object.

The ConfigurationClass annotation (Java) or attribute (.NET) provides additional information to the ICF framework about the configuration class. The following information is provided:

Element Description

privateProperty

If this is set, the property is hidden from the application, and the application cannot set the property through the APIConfiguration.

skipUnsupported

If the type of an added property is not supported, the framework throws an exception. To avoid the exception, set the value of skipUnsupported to true.

  • Java

  • C#

ConfigurationClass Annotation (Java)
@ConfigurationClass(ignore = { "privateProperty", "internalProperty" }, skipUnsupported = true)
ConfigurationClass Attribute (C#)
[ConfigurationClass(Ignore = { "privateProperty", "internalProperty" }, SkipUnsupported = true)]
Copyright © 2010-2024 ForgeRock, all rights reserved.