Package org.forgerock.opendj.rest2ldap

Class Rest2Ldap

java.lang.Object
org.forgerock.opendj.rest2ldap.Rest2Ldap
public final class Rest2Ldap extends Object
Provides methods for constructing Rest2Ldap protocol gateways. Applications construct a new Rest2Ldap instance by calling rest2Ldap(org.forgerock.util.Options, java.util.Collection<org.forgerock.opendj.rest2ldap.Resource>) passing in a list of resources which together define the data model being exposed by the gateway. Call newRequestHandlerFor(String) in order to obtain a request handler for a specific resource. The methods in this class can be categorized as follows:

Creating Rest2Ldap gateways:

Defining resource types, e.g. users, groups, devices, etc:

  • resource(java.lang.String) - creates a resource having a fluent API for defining additional characteristics such as the resource's inheritance, sub-resources, and properties

Defining a resource's sub-resources. A sub-resource is a resource which is subordinate to another resource. Or, to put it another way, sub-resources define parent child relationships where the life-cycle of a child resource is constrained by the life-cycle of the parent: deleting the parent implies that all children are deleted as well. An example of a sub-resource is a subscriber having one or more devices:

  • collectionOf(java.lang.String) - creates a one-to-many relationship. Collections support creation, deletion, and querying of child resources
  • singletonOf(java.lang.String) - creates a one-to-one relationship. Singletons cannot be created or destroyed, although they may be modified if they have properties which are modifiable. Singletons are usually only used as top-level entry points into REST APIs.

Defining a resource's properties:

  • Field Details

    • LOAD_SCHEMA

      public static final Option<Boolean> LOAD_SCHEMA
      Specifies whether the LDAP schema should be loaded from the LDAP server before being able to serve requests.

    • SCHEMA_RETRY_INTERVAL

      public static final Option<Duration> SCHEMA_RETRY_INTERVAL
      Specifies the interval between failed attempts to load the remote schema. The default configuration is to retry every 2 seconds.

    • SCHEMA_RELOAD_INTERVAL

      public static final Option<Duration> SCHEMA_RELOAD_INTERVAL
      Specifies the interval between successive attempts to detect changes in LDAP schema. The default configuration is to attempt to detect changes every 30 seconds.

    • SCHEDULER

      public static final Option<ScheduledExecutorService> SCHEDULER
      Specifies the scheduler which will be used for periodically detecting changes to LDAP schema. A system-wide scheduler will be used by default.

    • DECODE_OPTIONS

      public static final Option<DecodeOptions> DECODE_OPTIONS
      Specifies the LDAP decoding options which should be used when decoding LDAP DNs, attribute types, and controls. By default Rest2Ldap will use a set of options of will always use the default schema.

    • USE_MVCC

      public static final Option<Boolean> USE_MVCC
      Specifies whether Rest2Ldap should support multi-version concurrency control (MVCC) through the use of an MVCC LDAP attribute such as "etag". By default Rest2Ldap will use MVCC.

    • MVCC_ATTRIBUTE

      public static final Option<String> MVCC_ATTRIBUTE
      Specifies the name of the LDAP attribute which should be used for multi-version concurrency control (MVCC) if enabled. By default Rest2Ldap will use the "etag" operational attribute.

    • READ_ON_UPDATE_POLICY

      public static final Option<ReadOnUpdatePolicy> READ_ON_UPDATE_POLICY
      Specifies the policy which should be used in order to read an entry before it is deleted, or after it is added or modified. By default Rest2Ldap will use the controls read on update policy.

    • USE_PERMISSIVE_MODIFY

      public static final Option<Boolean> USE_PERMISSIVE_MODIFY
      Specifies whether Rest2Ldap should perform LDAP modify operations using the LDAP permissive modify control. By default Rest2Ldap will use the permissive modify control and use of the control is strongly recommended.

    • USE_SUBTREE_DELETE

      public static final Option<Boolean> USE_SUBTREE_DELETE
      Specifies whether Rest2Ldap should perform LDAP delete operations using the LDAP subtree delete control. By default Rest2Ldap will use the subtree delete control and use of the control is strongly recommended.

    • USE_SERVER_SIDE_SORT_FOR_JSON

      public static final Option<Boolean> USE_SERVER_SIDE_SORT_FOR_JSON
      Specifies whether Rest2Ldap should use server side sort control for LDAP attribute containing JSON. Otherwise, the sort will be performed locally by Rest2Ldap. By default Rest2Ldap will use the server side sort control.

    • LOCAL_SORT_MAX_ENTRIES

      public static final Option<Integer> LOCAL_SORT_MAX_ENTRIES
      Specifies the maximum number of entries supported by the local sort mechanism. The local sort mechanism is used when sort keys are referencing JSON attributes. A value of 0 will delegate the sorting to the server by adding a server side sort control to the LDAP request.

    • RETURN_NULL_FOR_MISSING_PROPERTIES

      public static final Option<Boolean> RETURN_NULL_FOR_MISSING_PROPERTIES
      Specifies whether Rest2Ldap should represent missing JSON property values using null. By default missing JSON property values will not be included in any returned JSON resources.

    • IN_INVOKER_THREAD

      public static final Option<Boolean> IN_INVOKER_THREAD
      Specifies whether the Rest2Ldap transformations should be performed in the invoker thread rather than I/O thread. This option is useful when Rest2Ldap is embedded in application having a significant number of threads, to ensure that I/O threads are doing the minimum amount of work and remains available for critical task like availability checks. When true (default), a filter will be added in front of the RequestHandler returned by newRequestHandlerFor(String). This filter will queue LDAP responses coming from I/O thread so that they can be processed in the thread which performed the CREST request.

  • Method Details

    • rest2Ldap

      public static Rest2Ldap rest2Ldap(Options options, Collection<Resource> resources)
      Creates a new Rest2Ldap instance using the provided options and resources. Applications should call newRequestHandlerFor(String) to obtain a request handler for a specific resource.

      The supported options are defined in this class.

      Parameters:
      options - The configuration options for interactions with the backend LDAP server. The set of available options are provided in this class.
      resources - The list of resources.
      Returns:
      A new Rest2Ldap instance from which REST request handlers can be obtained.

    • rest2Ldap

      public static Rest2Ldap rest2Ldap(Options options, Resource... resources)
      Creates a new Rest2Ldap instance using the provided options and resources. Applications should call newRequestHandlerFor(String) to obtain a request handler for a specific resource.

      The supported options are defined in this class.

      Parameters:
      options - The configuration options for interactions with the backend LDAP server. The set of available options are provided in this class.
      resources - The list of resources.
      Returns:
      A new Rest2Ldap instance from which REST request handlers can be obtained.

    • resource

      public static Resource resource(String resourceId)
      Creates a new resource definition with the provided resource ID.
      Parameters:
      resourceId - The resource ID.
      Returns:
      A new resource definition with the provided resource ID.

    • collectionOf

      public static CollectionSubResource collectionOf(String resourceId)
      Creates a new collection sub-resource definition whose members will be resources having the provided resource ID or its sub-types.
      Parameters:
      resourceId - The type of resource contained in the sub-resource collection.
      Returns:
      A new sub-resource definition with the provided resource ID.

    • singletonOf

      public static SingletonSubResource singletonOf(String resourceId)
      Creates a new singleton sub-resource definition which will reference a single resource having the specified resource ID.
      Parameters:
      resourceId - The type of resource referenced by the sub-resource singleton.
      Returns:
      A new sub-resource definition with the provided resource ID.

    • resourceType

      public static PropertyMapper resourceType()
      Returns a property mapper which maps a JSON property containing the resource type to its associated LDAP object classes.
      Returns:
      The property mapper.

    • auxiliaryResourceTypes

      public static PropertyMapper auxiliaryResourceTypes()
      Returns a property mapper which maps a JSON property containing the auxiliary resource types to its associated LDAP object classes.
      Returns:
      The property mapper.

    • constant

      public static PropertyMapper constant(Object value)
      Returns a property mapper which maps a single JSON attribute to a JSON constant.
      Parameters:
      value - The constant JSON value (a Boolean, Number, String, Map, or List).
      Returns:
      The property mapper.

    • object

      public static ObjectPropertyMapper object()
      Returns a property mapper which maps JSON objects to LDAP attributes.
      Returns:
      The property mapper.

    • reference

      public static AbstractResourceReferencePropertyMapper<?> reference(AttributeDescription mappedLdapAttribute, String resourcePath)
      Returns a property mapper which provides a mapping from a JSON value to a DN valued LDAP attribute.
      Parameters:
      mappedLdapAttribute - The DN valued LDAP attribute to be mapped.
      resourcePath - The path to the resource collection containing the referenced resources.
      Returns:
      The property mapper.

    • reference

      public static AbstractResourceReferencePropertyMapper<?> reference(String mappedLdapAttribute, String resourcePath)
      Returns a property mapper which provides a mapping from a JSON value to a DN valued LDAP attribute.
      Parameters:
      mappedLdapAttribute - The DN valued LDAP attribute to be mapped.
      resourcePath - The path to the resource collection containing the referenced resources.
      Returns:
      The property mapper.

    • reference

      public static AbstractResourceReferencePropertyMapper<?> reference(String mappedLdapAttribute, String resourcePath, String jsonPropertyName, String nameAndJsonQueryFilterMatchingRuleName)
      Returns a property mapper which provides a mapping from a JSON value to a "Name and JSON" valued LDAP attribute.
      Parameters:
      mappedLdapAttribute - The "Name and JSON" valued LDAP attribute to be mapped.
      resourcePath - The path to the resource collection containing the referenced resources.
      jsonPropertyName - The JSON property name which will be used to render the JSON part of the attribute. May be null. Note that not specifying the jsonPropertyName will systematically clear the JSON part of the attribute during patch and update operations.
      nameAndJsonQueryFilterMatchingRuleName - The name of the NameAndJson query filter matching rule to use by the reverse-reference to match references of this type of resource. If null, then the default value will be JsonSchema.getNameAndJsonCaseIgnoreJsonQueryFilterMatchingRule().
      Returns:
      The property mapper.

    • reference

      public static InlineResourcePropertyMapper reference(AttributeDescription mappedLdapAttribute, String baseDnTemplate, AttributeDescription primaryKey, ObjectPropertyMapper mapper, String jsonPropertyName)
      Returns a property mapper which provides a mapping from a JSON value to a single DN valued LDAP attribute.
      Parameters:
      mappedLdapAttribute - The DN valued LDAP attribute to be mapped.
      baseDnTemplate - The DN template which will be used as the search base when performing reverse lookups. The DN template may include template parameters and also parent RDNs using ".." notation. For example, the DN template "ou=groups,..,.." specifies that the search base DN should be computed by appending the RDN "ou=groups" to the grand-parent of the current resource's LDAP entry.
      primaryKey - The search primary key LDAP attribute to use for performing reverse lookups.
      mapper - An object property mapper which will be used to map LDAP attributes in the referenced entry.
      jsonPropertyName - The JSON property name which will be used to render the JSON part of the attribute. May be null. Note that not specifying the jsonPropertyName will systematically clear the JSON part of the attribute during patch and update operations.
      Returns:
      The property mapper.

    • reference

      public static InlineResourcePropertyMapper reference(String mappedLdapAttribute, String baseDnTemplate, String primaryKey, ObjectPropertyMapper mapper, String jsonPropertyName)
      Returns a property mapper which provides a mapping from a JSON value to a single DN valued LDAP attribute.
      Parameters:
      mappedLdapAttribute - The DN valued LDAP attribute to be mapped.
      baseDnTemplate - The DN template which will be used as the search base when performing reverse lookups. The DN template may include template parameters and also parent RDNs using ".." notation. For example, the DN template "ou=groups,..,.." specifies that the search base DN should be computed by appending the RDN "ou=groups" to the grand-parent of the current resource's LDAP entry.
      primaryKey - The search primary key LDAP attribute to use for performing reverse lookups.
      mapper - An object property mapper which will be used to map LDAP attributes in the referenced entry.
      jsonPropertyName - The JSON property name which will be used to render the JSON part of the attribute. May be null. Note that not specifying the jsonPropertyName will systematically clear the JSON part of the attribute during patch and update operations.
      Returns:
      The property mapper.

    • reverseReference

      public static AbstractReverseResourceReferencePropertyMapper<?> reverseReference(String resourcePath, String referencePropertyName)
      Returns a property mapper which provides a reverse mapping from a JSON value to a DN valued LDAP attribute.
      Parameters:
      resourcePath - The path to the resource collection containing the referenced resources.
      referencePropertyName - Name of the "reference" property in the resource pointed by resourcePath
      Returns:
      The property mapper.

    • simple

      public static SimplePropertyMapper simple(AttributeDescription mappedLdapAttribute)
      Returns a property mapper which provides a simple mapping from a JSON value to a single LDAP attribute.
      Parameters:
      mappedLdapAttribute - The LDAP attribute to be mapped.
      Returns:
      The property mapper.

    • simple

      public static SimplePropertyMapper simple(String mappedLdapAttribute)
      Returns a property mapper which provides a simple mapping from a JSON value to a single LDAP attribute.
      Parameters:
      mappedLdapAttribute - The LDAP attribute to be mapped.
      Returns:
      The property mapper.

    • json

      public static JsonPropertyMapper json(AttributeDescription mappedLdapAttribute)
      Returns a property mapper which provides a mapping from a JSON value to a LDAP attribute having the JSON syntax.
      Parameters:
      mappedLdapAttribute - The LDAP attribute to be mapped.
      Returns:
      The property mapper.

    • json

      public static JsonPropertyMapper json(String mappedLdapAttribute)
      Returns a property mapper which provides a mapping from a JSON value to a LDAP attribute having the JSON syntax.
      Parameters:
      mappedLdapAttribute - The LDAP attribute to be mapped.
      Returns:
      The property mapper.

    • asResourceException

      public static ResourceException asResourceException(Throwable t)
      Adapts a Throwable to a ResourceException. If the Throwable is an LDAP LdapException then an appropriate ResourceException is returned, otherwise an InternalServerErrorException is returned.
      Parameters:
      t - The Throwable to be converted.
      Returns:
      The equivalent resource exception.

    • newRequestHandlerFor

      public RequestHandler newRequestHandlerFor(String resourceId)
      Returns a RequestHandler which will handle requests to the named resource and any of its sub-resources.
      Parameters:
      resourceId - The resource ID.
      Returns:
      A RequestHandler which will handle requests to the named resource.