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 Summary

    Fields
    Modifier and Type
    Field
    Description
    static final org.forgerock.util.Option<org.forgerock.opendj.ldap.DecodeOptions>
    DECODE_OPTIONS
    Specifies the LDAP decoding options which should be used when decoding LDAP DNs, attribute types, and controls.
    static final org.forgerock.util.Option<String>
    MVCC_ATTRIBUTE
    Specifies the name of the LDAP attribute which should be used for multi-version concurrency control (MVCC) if enabled.
    static final org.forgerock.util.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.
    static final org.forgerock.util.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".
    static final org.forgerock.util.Option<Boolean>
    USE_PERMISSIVE_MODIFY
    Specifies whether Rest2Ldap should perform LDAP modify operations using the LDAP permissive modify control.
    static final org.forgerock.util.Option<Boolean>
    USE_SUBTREE_DELETE
    Specifies whether Rest2Ldap should perform LDAP delete operations using the LDAP subtree delete control.

  • Method Summary

    Modifier and Type
    Method
    Description
    static org.forgerock.json.resource.ResourceException
    asResourceException(Throwable t)
    Adapts a Throwable to a ResourceException.
    static SubResourceCollection
    collectionOf(String resourceId)
    Creates a new collection sub-resource definition whose members will be resources having the provided resource ID or its sub-types.
    static PropertyMapper
    constant(Object value)
    Returns a property mapper which maps a single JSON attribute to a JSON constant.
    static JsonPropertyMapper
    json(String attribute)
    Returns a property mapper which provides a mapping from a JSON value to a LDAP attribute having the JSON syntax.
    static JsonPropertyMapper
    json(org.forgerock.opendj.ldap.AttributeDescription attribute)
    Returns a property mapper which provides a mapping from a JSON value to a LDAP attribute having the JSON syntax.
    org.forgerock.json.resource.RequestHandler
    newRequestHandlerFor(String resourceId)
    Returns a RequestHandler which will handle requests to the named resource and any of its sub-resources.
    static ObjectPropertyMapper
    object()
    Returns a property mapper which maps JSON objects to LDAP attributes.
    static ReferencePropertyMapper
    reference(String attribute, String baseDnTemplate, String primaryKey, PropertyMapper mapper)
    Returns a property mapper which provides a mapping from a JSON value to a single DN valued LDAP attribute.
    static ReferencePropertyMapper
    reference(org.forgerock.opendj.ldap.AttributeDescription attribute, String baseDnTemplate, org.forgerock.opendj.ldap.AttributeDescription primaryKey, PropertyMapper mapper)
    Returns a property mapper which provides a mapping from a JSON value to a single DN valued LDAP attribute.
    static Resource
    resource(String resourceId)
    Creates a new resource definition with the provided resource ID.
    static PropertyMapper
    resourceType()
    Returns a property mapper which maps a JSON property containing the resource type to its associated LDAP object classes.
    static Rest2Ldap
    rest2Ldap(org.forgerock.util.Options options, Collection<Resource> resources)
    Creates a new Rest2Ldap instance using the provided options and resources.
    static Rest2Ldap
    rest2Ldap(org.forgerock.util.Options options, Resource... resources)
    Creates a new Rest2Ldap instance using the provided options and resources.
    static SimplePropertyMapper
    simple(String attribute)
    Returns a property mapper which provides a simple mapping from a JSON value to a single LDAP attribute.
    static SimplePropertyMapper
    simple(org.forgerock.opendj.ldap.AttributeDescription attribute)
    Returns a property mapper which provides a simple mapping from a JSON value to a single LDAP attribute.
    static SubResourceSingleton
    singletonOf(String resourceId)
    Creates a new singleton sub-resource definition which will reference a single resource having the specified resource ID.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • DECODE_OPTIONS

      public static final org.forgerock.util.Option<org.forgerock.opendj.ldap.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 org.forgerock.util.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 org.forgerock.util.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 org.forgerock.util.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 org.forgerock.util.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 org.forgerock.util.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.

  • Method Details

    • rest2Ldap

      public static Rest2Ldap rest2Ldap(org.forgerock.util.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(org.forgerock.util.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 SubResourceCollection 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 SubResourceSingleton 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.

    • 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 ReferencePropertyMapper reference(org.forgerock.opendj.ldap.AttributeDescription attribute, String baseDnTemplate, org.forgerock.opendj.ldap.AttributeDescription primaryKey, PropertyMapper mapper)
      Returns a property mapper which provides a mapping from a JSON value to a single DN valued LDAP attribute.
      Parameters:
      attribute - 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 property mapper which will be used to map LDAP attributes in the referenced entry.
      Returns:
      The property mapper.

    • reference

      public static ReferencePropertyMapper reference(String attribute, String baseDnTemplate, String primaryKey, PropertyMapper mapper)
      Returns a property mapper which provides a mapping from a JSON value to a single DN valued LDAP attribute.
      Parameters:
      attribute - 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 property mapper which will be used to map LDAP attributes in the referenced entry.
      Returns:
      The property mapper.

    • simple

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

    • simple

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

    • json

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

    • json

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

    • asResourceException

      public static org.forgerock.json.resource.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 org.forgerock.json.resource.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.