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 * Portions Copyright 2021-2023 Ping Identity Corporation 026 */ 027package com.unboundid.directory.sdk.scim2.types; 028 029import com.unboundid.ldap.sdk.AddRequest; 030import com.unboundid.ldap.sdk.CompareRequest; 031import com.unboundid.ldap.sdk.CompareResult; 032import com.unboundid.ldap.sdk.DeleteRequest; 033import com.unboundid.ldap.sdk.ExtendedRequest; 034import com.unboundid.ldap.sdk.ExtendedResult; 035import com.unboundid.ldap.sdk.LDAPResult; 036import com.unboundid.ldap.sdk.ModifyDNRequest; 037import com.unboundid.ldap.sdk.ModifyRequest; 038import com.unboundid.ldap.sdk.RootDSE; 039import com.unboundid.ldap.sdk.SearchRequest; 040import com.unboundid.ldap.sdk.SearchResult; 041import com.unboundid.ldap.sdk.SearchResultEntry; 042import com.unboundid.ldap.sdk.schema.Schema; 043import com.unboundid.scim2.common.exceptions.ScimException; 044import com.unboundid.util.NotExtensible; 045import com.unboundid.util.NotNull; 046import com.unboundid.util.Nullable; 047 048import javax.servlet.http.HttpServletRequest; 049import java.util.Set; 050 051/** 052 * This interface defines a set of helper methods for SCIM 2-related extensions 053 * that interact with SCIM resources and sub-resources backed by an LDAP 054 * server. Concrete instances of this interface may be obtained via 055 * {@link SCIMServerContext}, and are always associated with a particular 056 * SCIM resource type. 057 * <p> 058 * For PingAuthorize Server, the associated SCIM resource type must use an 059 * LDAP store adapter as its primary store adapter, and the LDAP store adapter 060 * must be backed by a Ping Identity Directory Server 061 * or Directory Proxy Server. 062 */ 063@NotExtensible 064public interface SCIMLDAPInterface 065{ 066 /** 067 * Gets the LDAP base DN associated with the SCIM service. If the product is 068 * PingAuthorize Server, this will be the base DN for the SCIM resource type's 069 * primary store adapter. 070 * 071 * @return The base DN. 072 */ 073 String getBaseDN(); 074 075 /** 076 * Gets the LDAP server's schema. 077 * 078 * @return The LDAP schema. 079 * @throws ScimException If the schema cannot be obtained. 080 */ 081 @Nullable() 082 Schema getSchema() 083 throws ScimException; 084 085 /** 086 * Gets the controls supported by the LDAP server. 087 * 088 * @return The controls supported by the LDAP server as a set of OID values. 089 * @throws ScimException 090 * If the supported LDAP controls cannot be obtained. 091 */ 092 Set<String> getSupportedControls() 093 throws ScimException; 094 095 /** 096 * Retrieves the LDAP server's root DSE. 097 * 098 * @param httpServletRequest The HTTP servlet request associated with the 099 * current operation. 100 * 101 * @return The LDAP server's root DSE, or {@code null} if it is not 102 * available. 103 * @throws ScimException If a problem occurs while attempting to retrieve 104 * the server root DSE. 105 */ 106 @Nullable() 107 RootDSE getRootDSE(@NotNull final HttpServletRequest httpServletRequest) 108 throws ScimException; 109 110 /** 111 * Processes the provided LDAP add request. 112 * 113 * @param httpServletRequest The HTTP servlet request associated with the 114 * current operation. 115 * @param addRequest The add request to be processed. It must not be 116 * {@code null}. 117 * 118 * @return The result of processing the add operation. 119 * @throws ScimException If a connection cannot be obtained, if the server 120 * rejects the add request, or if a problem is 121 * encountered while sending the request or reading 122 * the response. 123 */ 124 @NotNull() 125 LDAPResult add(@NotNull final HttpServletRequest httpServletRequest, 126 @NotNull AddRequest addRequest) 127 throws ScimException; 128 129 /** 130 * Processes the provided LDAP compare request. 131 * 132 * @param httpServletRequest The HTTP servlet request associated with the 133 * current operation. 134 * @param compareRequest The compare request to be processed. It must 135 * not be {@code null}. 136 * 137 * @return The result of processing the compare operation. 138 * @throws ScimException If a connection cannot be obtained, if the server 139 * rejects the compare request, or if a problem is 140 * encountered while sending the request or reading 141 * the response. 142 */ 143 @NotNull() 144 CompareResult compare(@NotNull final HttpServletRequest httpServletRequest, 145 @NotNull CompareRequest compareRequest) 146 throws ScimException; 147 148 /** 149 * Processes the provided LDAP delete request. 150 * 151 * @param httpServletRequest The HTTP servlet request associated with the 152 * current operation. 153 * @param deleteRequest The delete request to be processed. It must not 154 * be {@code null}. 155 * 156 * @return The result of processing the delete operation. 157 * @throws ScimException If a connection cannot be obtained, if the server 158 * rejects the delete request, or if a problem is 159 * encountered while sending the request or reading 160 * the response. 161 */ 162 @NotNull() 163 LDAPResult delete(@NotNull final HttpServletRequest httpServletRequest, 164 @NotNull DeleteRequest deleteRequest) 165 throws ScimException; 166 167 /** 168 * Processes the provided LDAP modify request. 169 * 170 * @param httpServletRequest The HTTP servlet request associated with the 171 * current operation. 172 * @param modifyRequest The modify request to be processed. It must not 173 * be {@code null}. 174 * @return The result of processing the modify operation. 175 * 176 * @throws ScimException If a connection cannot be obtained, if the server 177 * rejects the modify request, or if a problem is 178 * encountered while sending the request or reading 179 * the response. 180 */ 181 @NotNull() 182 LDAPResult modify(@NotNull final HttpServletRequest httpServletRequest, 183 @NotNull ModifyRequest modifyRequest) 184 throws ScimException; 185 186 /** 187 * Processes the provided LDAP modify DN request. 188 * 189 * @param httpServletRequest The HTTP servlet request associated with the 190 * current operation. 191 * @param modifyDNRequest The modify DN request to be processed. It must 192 * not be {@code null}. 193 * 194 * @return The result of processing the modify DN operation. 195 * @throws ScimException If a connection cannot be obtained, if the server 196 * rejects the modify DN request, or if a problem is 197 * encountered while sending the request or reading 198 * the response. 199 */ 200 @NotNull() 201 LDAPResult modifyDN(@NotNull final HttpServletRequest httpServletRequest, 202 @NotNull ModifyDNRequest modifyDNRequest) 203 throws ScimException; 204 205 /** 206 * Processes the provided LDAP search request. 207 * <p> 208 * Note that if the search does not complete successfully, an 209 * {@code LDAPSearchException} wrapped by a {@code ScimException} will be 210 * thrown. In some cases, one or more search result entries or references may 211 * have been returned before the failure response is received. In this case, 212 * the {@code LDAPSearchException} methods like {@code getEntryCount}, 213 * {@code getSearchEntries}, {@code getReferenceCount}, and 214 * {@code getSearchReferences} may be used to obtain information about those 215 * entries and references (although if a search result listener was provided, 216 * then it will have been used to make any entries and references available, 217 * and they will not be available through the {@code getSearchEntries} and 218 * {@code getSearchReferences} methods). 219 * 220 * @param httpServletRequest The HTTP servlet request associated with the 221 * current operation. 222 * @param searchRequest The search request to be processed. It must not 223 * be {@code null}. 224 * 225 * @return A search result object that provides information about the 226 * processing of the search, potentially including the set of 227 * matching entries and search references returned by the server. 228 * @throws ScimException If a connection cannot be obtained, if the search 229 * does not complete successfully, or if a problem is 230 * encountered while sending the request or reading 231 * the response. If one or more entries or references 232 * were returned before the failure was encountered, 233 * then the wrapped {@code LDAPSearchException} 234 * object may be examined to obtain information about 235 * those entries and/or references. 236 */ 237 @NotNull() 238 SearchResult search(@NotNull final HttpServletRequest httpServletRequest, 239 @NotNull SearchRequest searchRequest) 240 throws ScimException; 241 242 /** 243 * Processes the provided LDAP search request. It is expected that at most one 244 * entry will be returned from the search, and that no additional content from 245 * the successful search result (e.g., diagnostic message or response 246 * controls) are needed. 247 * <p> 248 * Note that if the search does not complete successfully, an 249 * {@code LDAPSearchException} wrapped by a {@code ScimException} will be 250 * thrown. In some cases, one or more search result entries or references may 251 * have been returned before the failure response is received. In this case, 252 * the {@code LDAPSearchException} methods like {@code getEntryCount}, 253 * {@code getSearchEntries}, {@code getReferenceCount}, and 254 * {@code getSearchReferences} may be used to obtain information about those 255 * entries and references. 256 * 257 * @param httpServletRequest The HTTP servlet request associated with the 258 * current operation. 259 * @param searchRequest The search request to be processed. If it is 260 * configured with a search result listener or a 261 * size limit other than one, then the provided 262 * request will be duplicated with the appropriate 263 * settings. 264 * 265 * @return The entry that was returned from the search, or {@code null} if no 266 * entry was returned or the base entry does not exist. 267 * @throws ScimException If a connection cannot be obtained, if the search 268 * does not complete successfully, if more than a 269 * single entry is returned, or if a problem is 270 * encountered while parsing the provided filter 271 * string, sending the request, or reading the 272 * response. If one or more entries or references 273 * were returned before the failure was encountered, 274 * then the wrapped {@code LDAPSearchException} 275 * object may be examined to obtain information about 276 * those entries and/or references. 277 */ 278 @Nullable() 279 SearchResultEntry searchForEntry( 280 @NotNull final HttpServletRequest httpServletRequest, 281 @NotNull SearchRequest searchRequest) 282 throws ScimException; 283 284 /** 285 * Processes the provided extended request. Note that when processing an 286 * extended operation, the server will never throw an exception for a failed 287 * response -- only when there is a problem sending the request or reading the 288 * response. It is the responsibility of the caller to determine whether the 289 * operation was successful. 290 * <p> 291 * Note that some extended request types, such as the StartTLS extended 292 * request, may change the state of the underlying connection and should not 293 * be invoked through this interface. 294 * 295 * @param httpServletRequest The HTTP servlet request associated with the 296 * current operation. 297 * @param extendedRequest The extended request to be processed. It must 298 * not be {@code null}. 299 * 300 * @return The extended result object that provides information about the 301 * result of the request processing. It may or may not indicate that 302 * the operation was successful. 303 * @throws ScimException If a problem occurs while sending the request or 304 * reading the response. 305 */ 306 @NotNull 307 ExtendedResult processExtendedRequest( 308 @NotNull final HttpServletRequest httpServletRequest, 309 @NotNull final ExtendedRequest extendedRequest) 310 throws ScimException; 311}