| /* |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| */ |
| |
| package org.apache.directory.scim.server.provider; |
| |
| import java.util.List; |
| |
| import jakarta.ws.rs.WebApplicationException; |
| import jakarta.ws.rs.core.Response; |
| import jakarta.ws.rs.core.Response.Status; |
| |
| import org.apache.directory.scim.server.exception.UnableToCreateResourceException; |
| import org.apache.directory.scim.server.exception.UnableToDeleteResourceException; |
| import org.apache.directory.scim.server.exception.UnableToRetrieveExtensionsResourceException; |
| import org.apache.directory.scim.server.exception.UnableToRetrieveResourceException; |
| import org.apache.directory.scim.server.exception.UnableToUpdateResourceException; |
| import org.apache.directory.scim.server.rest.BaseResourceTypeResourceImpl; |
| import org.apache.directory.scim.spec.protocol.filter.FilterResponse; |
| import org.apache.directory.scim.spec.protocol.search.Filter; |
| import org.apache.directory.scim.spec.protocol.search.PageRequest; |
| import org.apache.directory.scim.spec.protocol.search.SortRequest; |
| import org.apache.directory.scim.spec.resources.ScimExtension; |
| import org.apache.directory.scim.spec.resources.ScimResource; |
| |
| /** |
| * Defines the interface between the SCIM protocol implementation and the |
| * Provider implementation for type T. |
| * |
| * @author Chris Harm <crh5255@psu.edu> |
| * |
| * @param <T> a SCIM ResourceType that extends ScimResource |
| */ |
| public interface Provider<T extends ScimResource> { |
| |
| /** |
| * Returns the type of ScimResource this provider manages. |
| * @return The type of resource this provider manages. |
| */ |
| Class<T> getResourceClass(); |
| |
| /** |
| * Allows the SCIM server's REST implementation to create a resource via |
| * a POST to a valid end-point. |
| * |
| * @param resource The ScimResource to create and persist. |
| * @return The newly created ScimResource. |
| * @throws UnableToCreateResourceException When the ScimResource cannot be |
| * created. |
| */ |
| T create(T resource) throws UnableToCreateResourceException; |
| |
| /** |
| * Allows the SCIM server's REST implementation to update and existing |
| * resource via a PUT to a valid end-point. |
| * |
| * @param updateRequest The ScimResource to update and persist. |
| * @return The newly updated ScimResource. |
| * @throws UnableToUpdateResourceException When the ScimResource cannot be |
| * updated. |
| */ |
| T update(UpdateRequest<T> updateRequest) throws UnableToUpdateResourceException; |
| |
| /** |
| * Retrieves the ScimResource associated with the provided identifier. |
| * @param id The identifier of the target ScimResource. |
| * @return The requested ScimResource. |
| * @throws UnableToRetrieveResourceException When the ScimResource cannot be |
| * retrieved. |
| */ |
| T get(String id) throws UnableToRetrieveResourceException; |
| |
| /** |
| * Finds and retrieves all ScimResource objects known to the persistence |
| * layer that match the criteria specified by the passed Filter. The results |
| * may be truncated by the scope specified by the passed PageRequest and |
| * the order of the returned resources may be controlled by the passed |
| * SortRequest. |
| * |
| * @param filter The filter that determines the ScimResources that will be |
| * part of the ResultList |
| * @param pageRequest For paged requests, this object specifies the start |
| * index and number of ScimResources that should be returned. |
| * @param sortRequest Specifies which fields the returned ScimResources |
| * should be sorted by and whether the sort order is ascending or |
| * descending. |
| * @return A list of the ScimResources that pass the filter criteria, |
| * truncated to match the requested "page" and sorted according |
| * to the provided requirements. |
| * @throws UnableToRetrieveResourceException If one or more ScimResouces |
| * cannot be retrieved. |
| */ |
| FilterResponse<T> find(Filter filter, PageRequest pageRequest, SortRequest sortRequest) throws UnableToRetrieveResourceException; |
| |
| /** |
| * Deletes the ScimResource with the provided identifier (if it exists). |
| * This interface makes no distinction between hard and soft deletes but |
| * rather leaves that to the designer of the persistence layer. |
| * |
| * @param id The ScimResource's identifier. |
| * @throws UnableToDeleteResourceException When the specified ScimResource |
| * cannot be deleted. |
| */ |
| void delete(String id) throws UnableToDeleteResourceException; |
| |
| /** |
| * Returns a list of the SCIM Extensions that this provider considers to be |
| * associated with the ScimResource of type T. |
| * |
| * @return A list of ScimExtension classes. |
| * @throws UnableToRetrieveExtensionsResourceException If the provider cannot return |
| * the appropriate list. |
| */ |
| List<Class<? extends ScimExtension>> getExtensionList() throws UnableToRetrieveExtensionsResourceException; |
| |
| /** |
| * <p>In the case where the provider throws an unhandled exception, this |
| * method will be passed that exception in order for the provider to convert |
| * it into the desired response.</p> |
| * <p>The returned response SHOULD fulfill the requirements for SCIM error |
| * responses as defined in <a |
| * href="https://tools.ietf.org/html/rfc7644#section-3.12">3.12. HTTP Status |
| * and Error Response Handling</a> of the SCIM specification.</p> |
| * <p>By default, exceptions are converted into a <code>500 Internal Server |
| * Error</code>.</p> |
| * @param unhandled |
| * @return |
| */ |
| default Response handleException(Throwable unhandled) { |
| // Allow for ErrorMessageViolationExceptionMapper to handle JAX-RS exceptions by default |
| if (unhandled instanceof WebApplicationException) { |
| throw (WebApplicationException) unhandled; |
| } |
| return BaseResourceTypeResourceImpl.createGenericExceptionResponse(unhandled, Status.INTERNAL_SERVER_ERROR); |
| } |
| } |