001/*
002 * Copyright 2015-2021 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.exceptions.ScimException;
022import com.unboundid.scim2.common.messages.ListResponse;
023import com.unboundid.scim2.common.messages.PatchRequest;
024import com.unboundid.scim2.common.types.ResourceTypeResource;
025import com.unboundid.scim2.common.types.SchemaResource;
026import com.unboundid.scim2.common.types.ServiceProviderConfigResource;
027
028/**
029 * Interface providing a way to create, retrieve, update and delete
030 * SCIM resources.
031 */
032public interface ScimInterface
033{
034  /**
035   * Retrieve the service provider configuration.
036   *
037   * @return the service provider configuration.
038   * @throws ScimException if an error occurs.
039   */
040  ServiceProviderConfigResource getServiceProviderConfig()
041      throws ScimException;
042
043  /**
044   * Retrieve the resource types supported by the service provider.
045   *
046   * @return The list of resource types supported by the service provider.
047   * @throws ScimException if an error occurs.
048   */
049  ListResponse<ResourceTypeResource> getResourceTypes()
050          throws ScimException;
051
052  /**
053   * Retrieve a known resource type supported by the service provider.
054   *
055   * @param name The name of the resource type.
056   * @return The resource type with the provided name.
057   * @throws ScimException if an error occurs.
058   */
059  ResourceTypeResource getResourceType(String name)
060              throws ScimException;
061
062  /**
063   * Retrieve the schemas supported by the service provider.
064   *
065   * @return The list of schemas supported by the service provider.
066   * @throws ScimException if an error occurs.
067   */
068  ListResponse<SchemaResource> getSchemas()
069                  throws ScimException;
070
071  /**
072   * Retrieve a known schema supported by the service provider.
073   *
074   * @param id The schema URN.
075   * @return The resource type with the provided URN.
076   * @throws ScimException if an error occurs.
077   */
078  SchemaResource getSchema(String id)
079                      throws ScimException;
080
081  /**
082   * Create the provided new SCIM resource at the service provider.
083   *
084   * @param endpoint The resource endpoint such as: "{@code Users}" or "{@code Groups}" as
085   *                 defined by the associated resource type.
086   * @param resource The new resource to create.
087   * @param <T> The Java type of the resource.
088   * @return The successfully create SCIM resource.
089   * @throws ScimException if an error occurs.
090   */
091  <T extends ScimResource> T create(
092      String endpoint, T resource) throws ScimException;
093
094  /**
095   * Retrieve a known SCIM resource from the service provider.
096   *
097   * @param endpoint The resource endpoint such as: "{@code Users}" or "{@code Groups}" as
098   *                 defined by the associated resource type.
099   * @param id The resource identifier (for example the value of the "{@code id}"
100   *           attribute).
101   * @param cls The Java class object used to determine the type to return.
102   * @param <T> The Java type of the resource.
103   * @return The successfully retrieved SCIM resource.
104   * @throws ScimException if an error occurs.
105   */
106  <T extends ScimResource> T retrieve(
107      String endpoint, String id, Class<T> cls)
108                              throws ScimException;
109
110  /**
111   * Retrieve a known SCIM resource from the service provider. If the
112   * service provider supports resource versioning and the resource has not been
113   * modified, the provided resource will be returned.
114   *
115   * @param resource The resource to retrieve.
116   * @param <T> The Java type of the resource.
117   * @return The successfully retrieved SCIM resource.
118   * @throws ScimException if an error occurs.
119   */
120  <T extends ScimResource> T retrieve(T resource)
121                                  throws ScimException;
122
123  /**
124   * Modify a SCIM resource by replacing the resource's attributes at the
125   * service provider. If the service provider supports resource versioning,
126   * the resource will only be modified if it has not been modified since it
127   * was retrieved.
128   *
129   * @param resource The previously retrieved and revised resource.
130   * @param <T> The Java type of the resource.
131   * @return The successfully replaced SCIM resource.
132   * @throws ScimException if an error occurs.
133   */
134  <T extends ScimResource> T replace(
135      T resource) throws ScimException;
136
137  /**
138   * Modify a SCIM resource by updating one or more attributes using a sequence
139   * of operations to "{@code add}", "{@code remove}", or "{@code replace}" values. The service provider
140   * configuration maybe used to discover service provider support for PATCH.
141   *
142   * @param endpoint The resource endpoint such as: "{@code Users}" or "{@code Groups}" as
143   *                 defined by the associated resource type.
144   * @param id The resource identifier (for example the value of the "{@code id}"
145   *           attribute).
146   * @param patchRequest the patch request to use for the update.
147   * @param clazz the class of the SCIM resource.
148   * @param <T> The Java type of the resource.
149   * @return The modified resource.
150   * @throws ScimException if an error occurs.
151   */
152  <T extends ScimResource> T modify(String endpoint,
153      String id, PatchRequest patchRequest, Class<T> clazz)
154      throws ScimException;
155
156  /**
157   * Modify a SCIM resource by updating one or more attributes using a sequence
158   * of operations to "{@code add}", "{@code remove}", or "{@code replace}" values. The service provider
159   * configuration maybe used to discover service provider support for PATCH.
160   *
161   * @param resource The resource to modify.
162   * @param patchRequest the patch request to use for the update.
163   * @param <T> The Java type of the resource.
164   * @return The modified resource.
165   * @throws ScimException if an error occurs.
166   */
167  <T extends ScimResource> T modify(
168      T resource, PatchRequest patchRequest) throws ScimException;
169
170  /**
171   * Delete a SCIM resource at the service provider.
172   *
173   * @param endpoint The resource endpoint such as: "{@code Users}" or "{@code Groups}" as
174   *                 defined by the associated resource type.
175   * @param id The resource identifier (for example the value of the "{@code id}"
176   *           attribute).
177   * @throws ScimException if an error occurs.
178   */
179  void delete(String endpoint, String id)
180                                          throws ScimException;
181
182  /**
183   * Delete a SCIM resource at the service provider.
184   *
185   * @param resource The resource to delete.
186   * @param <T> The Java type of the resource.
187   * @throws ScimException if an error occurs.
188   */
189  <T extends ScimResource> void delete(T resource)
190                                              throws ScimException;
191
192  /**
193   * Search for SCIM resources matching the SCIM filter provided.
194   *
195   * @param endpoint a SCIM resource type endpoint.
196   * @param filter a SCIM filter string.
197   * @param clazz the class representing the type of the SCIM resource.
198   * @param <T> The SCIM resource type to return a list of.
199   * @return a List of ScimResource objects matching the provided filter.
200   * @throws ScimException if an error occurs.
201   */
202  <T extends ScimResource> ListResponse<T> search(
203      String endpoint, String filter, Class<T> clazz) throws ScimException;
204}