001/*
002 * CDDL HEADER START
003 *
004 * The contents of this file are subject to the terms of the
005 * Common Development and Distribution License, Version 1.0 only
006 * (the "License").  You may not use this file except in compliance
007 * with the License.
008 *
009 * You can obtain a copy of the license at
010 * docs/licenses/cddl.txt
011 * or http://www.opensource.org/licenses/cddl1.php.
012 * See the License for the specific language governing permissions
013 * and limitations under the License.
014 *
015 * When distributing Covered Code, include this CDDL HEADER in each
016 * file and include the License file at
017 * docs/licenses/cddl.txt.  If applicable,
018 * add the following below this CDDL HEADER, with the fields enclosed
019 * by brackets "[]" replaced with your own identifying information:
020 *      Portions Copyright [yyyy] [name of copyright owner]
021 *
022 * CDDL HEADER END
023 *
024 *
025 *      Copyright 2021 Ping Identity Corporation
026 */
027package com.unboundid.directory.sdk.scim2.types;
028
029import com.fasterxml.jackson.databind.ObjectMapper;
030import com.unboundid.directory.sdk.http.types.HTTPServerContext;
031import com.unboundid.ldap.sdk.schema.Schema;
032import com.unboundid.scim2.common.exceptions.ScimException;
033import com.unboundid.scim2.common.types.SchemaResource;
034import com.unboundid.util.NotExtensible;
035import com.unboundid.util.ThreadSafety;
036import com.unboundid.util.ThreadSafetyLevel;
037
038import java.util.Collection;
039
040/**
041 * This interface may be used to obtain information about the SCIM 2-enabled
042 * HTTP Server in which an extension is running.
043 */
044@NotExtensible()
045@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
046public interface SCIMServerContext extends HTTPServerContext
047{
048  /**
049   * Retrieves all SCIM 2 schemas.
050   *
051   * @return  All SCIM 2 schemas.
052   */
053  Collection<SchemaResource> getSCIMSchemas();
054
055  /**
056   * Registers a SCIM schema with the server, making it available via the
057   * SCIM 2 schemas endpoint.
058   * <p>
059   * Note that this method need only be called by an extension that builds its
060   * schema programmatically; any SCIM schema that was declared in the server
061   * configuration will already be available via the SCIM 2 schemas endpoint.
062   *
063   * @param schema  The schema to register.
064   */
065  void registerSCIMSchema(final SchemaResource schema);
066
067  /**
068   * Deregisters a SCIM schema with the server.
069   *
070   * @param schema  The SCIM schema to deregister.
071   */
072  void deregisterSCIMSchema(final SchemaResource schema);
073
074  /**
075   * Gets the SCIM ID attribute value for a SCIM Resource Type.
076   * <p>
077   * A SCIM ID acts as the unique identifier for a SCIM resource, and is used
078   * for retrieve, update, and delete operations for that resource. The SCIM ID
079   * <em>attribute</em> is the native data store attribute that stores a SCIM
080   * resource's ID. For Ping Identity Directory Server
081   * and Directory Proxy Server, this attribute is always "entryUUID". For
082   * PingAuthorize Server, this attribute is defined in the SCIM Resource Type
083   * configuration and may vary by deployment.
084   *
085   * @param scimResourceType  The name of a SCIM Resource Type.
086   *
087   * @return                  The resource type's ID attribute value.
088   *                          For example, "entryUUID".
089   * @throws ScimException    If the specified SCIM Resource Type does not
090   *                          exist.
091   */
092  String getIDAttribute(final String scimResourceType) throws ScimException;
093
094  /**
095   * Creates a {@link SCIMLDAPInterface} instance, which provides a set of
096   * helper methods for SCIM 2 extensions to interact with a Ping LDAP server,
097   * using the same privileges as the server itself.
098   *
099   * @param scimResourceType  The name of a SCIM Resource Type, such as
100   *                          "Users". If the server is PingAuthorize Server,
101   *                          then this SCIM Resource Type's primary store
102   *                          adapter must be an LDAP store adapter, and the
103   *                          backing LDAP servers must be Ping LDAP servers.
104   *
105   * @return                  A SCIMLDAPRequestHelper instance.
106   * @throws ScimException    If the SCIMLDAPRequestHelper cannot be created.
107   */
108  SCIMLDAPInterface getSCIMLDAPInterface(final String scimResourceType)
109      throws ScimException;
110
111  /**
112   * Creates a {@link SCIMLDAPAttributeMapper} instance, which provides a set
113   * of methods for converting to and from SCIM and LDAP attribute values.
114   *
115   * @param ldapSchema    The LDAP server's schema. This may be obtained by
116   *                      calling {@link SCIMLDAPInterface#getSchema()}.
117   * @param objectMapper  A Jackson {@link ObjectMapper} instance. Extensions
118   *                      can create a new instance by calling the SCIM 2 SDK
119   *                      method JsonUtils#createObjectMapper().
120   *
121   * @return              A SCIMLDAPAttributeMapper instance.
122   */
123  SCIMLDAPAttributeMapper getLDAPAttributeMapper(
124      final Schema ldapSchema,
125      final ObjectMapper objectMapper);
126}