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:
- rest2Ldap(org.forgerock.util.Options, java.util.Collection<org.forgerock.opendj.rest2ldap.Resource>) - creates a gateway for a given set of resources
- newRequestHandlerFor(java.lang.String) - obtains a request handler for the specified endpoint resource.
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:
- resourceType() - defines a property whose JSON value will be the name of the resource, e.g. "user"
- simple(org.forgerock.opendj.ldap.AttributeDescription) - defines a property which maps a JSON value to a single LDAP attribute
- object() - defines a property which is a JSON object having zero or more nested properties
- reference(org.forgerock.opendj.ldap.AttributeDescription, java.lang.String) - defines a property whose JSON value is a reference to another resource. Use these for mapping LDAP attributes which contain the DN of another LDAP entry exposed by Rest2Ldap. For example, a user's "manager" attribute or the members of a group.

Field Summary

Fields
Modifier and Type	Field	Description
`static Option<DecodeOptions>`	`DECODE_OPTIONS`	Specifies the LDAP decoding options which should be used when decoding LDAP DNs, attribute types, and controls.
`static Option<Boolean>`	`IN_INVOKER_THREAD`	Specifies whether the Rest2Ldap transformations should be performed in the invoker thread rather than I/O thread.
`static Option<Boolean>`	`LOAD_SCHEMA`	Specifies whether the LDAP schema should be loaded from the LDAP server before being able to serve requests.
`static Option<Integer>`	`LOCAL_SORT_MAX_ENTRIES`	Specifies the maximum number of entries supported by the local sort mechanism.
`static Option<String>`	`MVCC_ATTRIBUTE`	Specifies the name of the LDAP attribute which should be used for multi-version concurrency control (MVCC) if `enabled`.
`static 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 Option<Boolean>`	`RETURN_NULL_FOR_MISSING_PROPERTIES`	Specifies whether Rest2Ldap should represent missing JSON property values using `null`.
`static Option<ScheduledExecutorService>`	`SCHEDULER`	Specifies the scheduler which will be used for periodically detecting changes to LDAP schema.
`static Option<Duration>`	`SCHEMA_RELOAD_INTERVAL`	Specifies the interval between successive attempts to detect changes in LDAP schema.
`static Option<Duration>`	`SCHEMA_RETRY_INTERVAL`	Specifies the interval between failed attempts to load the remote schema.
`static 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 Option<Boolean>`	`USE_PERMISSIVE_MODIFY`	Specifies whether Rest2Ldap should perform LDAP modify operations using the LDAP permissive modify control.
`static Option<Boolean>`	`USE_SERVER_SIDE_SORT_FOR_JSON`	Specifies whether Rest2Ldap should use server side sort control for LDAP attribute containing JSON.
`static Option<Boolean>`	`USE_SUBTREE_DELETE`	Specifies whether Rest2Ldap should perform LDAP delete operations using the LDAP subtree delete control.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`static ResourceException`	`asResourceException(Throwable t)`	Adapts a `Throwable` to a `ResourceException`.
`static PropertyMapper`	`auxiliaryResourceTypes()`	Returns a property mapper which maps a JSON property containing the auxiliary resource types to its associated LDAP object classes.
`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.
`static PropertyMapper`	`constant(Object value)`	Returns a property mapper which maps a single JSON attribute to a JSON constant.
`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.
`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.
`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 AbstractResourceReferencePropertyMapper<?>`	`reference(String mappedLdapAttribute, String resourcePath)`	Returns a property mapper which provides a mapping from a JSON value to a DN valued LDAP attribute.
`static AbstractResourceReferencePropertyMapper<?>`	`reference(String mappedLdapAttribute, String resourcePath, String jsonPropertyName)`	Returns a property mapper which provides a mapping from a JSON value to a "Name and JSON" valued LDAP attribute.
`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.
`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.
`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.
`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(Options options, Collection<Resource> resources)`	Creates a new `Rest2Ldap` instance using the provided options and `resources`.
`static Rest2Ldap`	`rest2Ldap(Options options, Resource... resources)`	Creates a new `Rest2Ldap` instance using the provided options and `resources`.
`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.
`static SimplePropertyMapper`	`simple(String mappedLdapAttribute)`	Returns a property mapper which provides a simple mapping from a JSON value to a single LDAP attribute.
`static SimplePropertyMapper`	`simple(AttributeDescription mappedLdapAttribute)`	Returns a property mapper which provides a simple mapping from a JSON value to a single LDAP attribute.
`static SingletonSubResource`	`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 Detail
  - 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 Detail
  - 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)
```
    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.
    
    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.

Class Rest2Ldap

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

LOAD_SCHEMA

SCHEMA_RETRY_INTERVAL

SCHEMA_RELOAD_INTERVAL

SCHEDULER

DECODE_OPTIONS

USE_MVCC

MVCC_ATTRIBUTE

READ_ON_UPDATE_POLICY

USE_PERMISSIVE_MODIFY

USE_SUBTREE_DELETE

USE_SERVER_SIDE_SORT_FOR_JSON

LOCAL_SORT_MAX_ENTRIES

RETURN_NULL_FOR_MISSING_PROPERTIES

IN_INVOKER_THREAD

Method Detail

rest2Ldap

rest2Ldap

resource

collectionOf

singletonOf

resourceType

auxiliaryResourceTypes

constant

object

reference

reference

reference

reference

reference

reverseReference

simple

simple

json

json

asResourceException

newRequestHandlerFor