001/*
002 * Copyright 2015-2024 Ping Identity Corporation
003 *
004 * This program is free software; you can redistribute it and/or modify
005 * it under the terms of the GNU General Public License (GPLv2 only)
006 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
007 * as published by the Free Software Foundation.
008 *
009 * This program is distributed in the hope that it will be useful,
010 * but WITHOUT ANY WARRANTY; without even the implied warranty of
011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
012 * GNU General Public License for more details.
013 *
014 * You should have received a copy of the GNU General Public License
015 * along with this program; if not, see <http://www.gnu.org/licenses>.
016 */
017
018package com.unboundid.scim2.client;
019
020import com.unboundid.scim2.common.ScimResource;
021import com.unboundid.scim2.common.annotations.NotNull;
022import com.unboundid.scim2.common.annotations.Nullable;
023import com.unboundid.scim2.common.exceptions.ScimException;
024import com.unboundid.scim2.common.messages.ListResponse;
025import com.unboundid.scim2.common.messages.PatchRequest;
026import com.unboundid.scim2.common.types.ResourceTypeResource;
027import com.unboundid.scim2.common.types.SchemaResource;
028import com.unboundid.scim2.common.types.ServiceProviderConfigResource;
029
030/**
031 * Interface providing a way to create, retrieve, update and delete
032 * SCIM resources.
033 */
034public interface ScimInterface
035{
036  /**
037   * Retrieve the service provider configuration.
038   *
039   * @return the service provider configuration.
040   * @throws ScimException if an error occurs.
041   */
042  @NotNull
043  ServiceProviderConfigResource getServiceProviderConfig()
044      throws ScimException;
045
046  /**
047   * Retrieve the resource types supported by the service provider.
048   *
049   * @return The list of resource types supported by the service provider.
050   * @throws ScimException if an error occurs.
051   */
052  @NotNull
053  ListResponse<ResourceTypeResource> getResourceTypes()
054      throws ScimException;
055
056  /**
057   * Retrieve a known resource type supported by the service provider.
058   *
059   * @param name The name of the resource type.
060   * @return The resource type with the provided name.
061   * @throws ScimException if an error occurs.
062   */
063  @NotNull
064  ResourceTypeResource getResourceType(@NotNull String name)
065      throws ScimException;
066
067  /**
068   * Retrieve the schemas supported by the service provider.
069   *
070   * @return The list of schemas supported by the service provider.
071   * @throws ScimException if an error occurs.
072   */
073  @NotNull
074  ListResponse<SchemaResource> getSchemas()
075      throws ScimException;
076
077  /**
078   * Retrieve a known schema supported by the service provider.
079   *
080   * @param id The schema URN.
081   * @return The resource type with the provided URN.
082   * @throws ScimException if an error occurs.
083   */
084  @NotNull
085  SchemaResource getSchema(@NotNull String id)
086      throws ScimException;
087
088  /**
089   * Create the provided new SCIM resource at the service provider.
090   *
091   * @param endpoint The resource endpoint such as: "{@code Users}" or
092   *                 "{@code Groups}" as defined by the associated resource
093   *                 type.
094   * @param resource The new resource to create.
095   * @param <T> The Java type of the resource.
096   * @return The successfully create SCIM resource.
097   * @throws ScimException if an error occurs.
098   */
099  @NotNull
100  <T extends ScimResource> T create(@NotNull String endpoint,
101                                    @NotNull T resource)
102      throws ScimException;
103
104  /**
105   * Retrieve a known SCIM resource from the service provider.
106   *
107   * @param endpoint The resource endpoint such as: "{@code Users}" or
108   *                 "{@code Groups}" as defined by the associated resource
109   *                 type.
110   * @param id The resource identifier (for example the value of the "{@code id}"
111   *           attribute).
112   * @param cls The Java class object used to determine the type to return.
113   * @param <T> The Java type of the resource.
114   * @return The successfully retrieved SCIM resource.
115   * @throws ScimException if an error occurs.
116   */
117  @NotNull
118  <T extends ScimResource> T retrieve(@NotNull String endpoint,
119                                      @NotNull String id,
120                                      @NotNull Class<T> cls)
121      throws ScimException;
122
123  /**
124   * Retrieve a known SCIM resource from the service provider. If the
125   * service provider supports resource versioning and the resource has not been
126   * modified, the provided resource will be returned.
127   *
128   * @param resource The resource to retrieve.
129   * @param <T> The Java type of the resource.
130   * @return The successfully retrieved SCIM resource.
131   * @throws ScimException if an error occurs.
132   */
133  @NotNull
134  <T extends ScimResource> T retrieve(@NotNull T resource)
135      throws ScimException;
136
137  /**
138   * Modify a SCIM resource by replacing the resource's attributes at the
139   * service provider. If the service provider supports resource versioning,
140   * the resource will only be modified if it has not been modified since it
141   * was retrieved.
142   *
143   * @param resource The previously retrieved and revised resource.
144   * @param <T> The Java type of the resource.
145   * @return The successfully replaced SCIM resource.
146   * @throws ScimException if an error occurs.
147   */
148  @NotNull
149  <T extends ScimResource> T replace(@NotNull T resource)
150      throws ScimException;
151
152  /**
153   * Modify a SCIM resource by updating one or more attributes using a sequence
154   * of operations to "{@code add}", "{@code remove}", or "{@code replace}"
155   * values. The service provider configuration may be used to discover service
156   * provider support for PATCH.
157   *
158   * @param endpoint The resource endpoint such as: "{@code Users}" or
159   *                 "{@code Groups}" as defined by the associated resource
160   *                 type.
161   * @param id The resource identifier (for example the value of the "{@code id}"
162   *           attribute).
163   * @param patchRequest The patch request to use for the update.
164   * @param clazz The class of the SCIM resource.
165   * @param <T> The Java type of the resource.
166   *
167   * @return The modified resource.
168   * @throws ScimException if an error occurs.
169   */
170  @NotNull
171  <T extends ScimResource> T modify(@NotNull String endpoint,
172                                    @NotNull String id,
173                                    @NotNull PatchRequest patchRequest,
174                                    @NotNull Class<T> clazz)
175      throws ScimException;
176
177  /**
178   * Modify a SCIM resource by updating one or more attributes using a sequence
179   * of operations to "{@code add}", "{@code remove}", or "{@code replace}"
180   * values. The service provider configuration may be used to discover service
181   * provider support for PATCH.
182   *
183   * @param resource The resource to modify.
184   * @param patchRequest the patch request to use for the update.
185   * @param <T> The Java type of the resource.
186   * @return The modified resource.
187   * @throws ScimException if an error occurs.
188   */
189  @NotNull
190  <T extends ScimResource> T modify(@NotNull T resource,
191                                    @NotNull PatchRequest patchRequest)
192      throws ScimException;
193
194  /**
195   * Delete a SCIM resource at the service provider.
196   *
197   * @param endpoint The resource endpoint such as: "{@code Users}" or
198   *                 "{@code Groups}" as defined by the associated resource
199   *                 type.
200   * @param id The resource identifier (for example the value of the "{@code id}"
201   *           attribute).
202   * @throws ScimException if an error occurs.
203   */
204  void delete(@NotNull String endpoint, @NotNull String id)
205      throws ScimException;
206
207  /**
208   * Delete a SCIM resource at the service provider.
209   *
210   * @param resource The resource to delete.
211   * @param <T> The Java type of the resource.
212   * @throws ScimException if an error occurs.
213   */
214  <T extends ScimResource> void delete(@NotNull T resource)
215      throws ScimException;
216
217  /**
218   * Search for SCIM resources matching the SCIM filter provided.
219   *
220   * @param endpoint a SCIM resource type endpoint.
221   * @param filter a SCIM filter string.
222   * @param clazz the class representing the type of the SCIM resource.
223   * @param <T> The SCIM resource type to return a list of.
224   * @return a List of ScimResource objects matching the provided filter.
225   * @throws ScimException if an error occurs.
226   */
227  @NotNull
228  <T extends ScimResource> ListResponse<T> search(@NotNull String endpoint,
229                                                  @Nullable String filter,
230                                                  @NotNull Class<T> clazz)
231      throws ScimException;
232}