001/*
002 * The contents of this file are subject to the terms of the Common Development and
003 * Distribution License (the License). You may not use this file except in compliance with the
004 * License.
005 *
006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007 * specific language governing permission and limitations under the License.
008 *
009 * When distributing Covered Software, include this CDDL Header Notice in each file and include
010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011 * Header, with the fields enclosed by brackets [] replaced by your own identifying
012 * information: "Portions Copyrighted [year] [name of copyright owner]".
013 *
014 * Copyright 2012-2015 ForgeRock AS.
015 */
016
017package org.forgerock.json.resource;
018
019import java.util.Collection;
020
021import org.forgerock.services.context.Context;
022
023/**
024 * An interface for implementing synchronous {@link RequestHandler}s. A
025 * synchronous request handler will block the caller until an operation has
026 * completed which may impact scalability in many environments, such as
027 * application servers. Therefore it is recommended that request handlers which
028 * are intended for use in production environments implement the asynchronous
029 * {@link RequestHandler} interface. This interface can be easily "mocked" and
030 * is therefore suitable for use in unit tests.
031 * <p>
032 * A synchronous request handler can be adapted as a {@link RequestHandler}
033 * using the {@link Resources#asRequestHandler(SynchronousRequestHandler)}
034 * method.
035 * <p>
036 * For more documentation about the individual operations see
037 * {@link RequestHandler}.
038 *
039 * @see RequestHandler
040 * @see Resources#asRequestHandler(SynchronousRequestHandler)
041 */
042public interface SynchronousRequestHandler {
043
044    /**
045     * Handles performing an action on a resource, and optionally returns an
046     * associated result. The execution of an action is allowed to incur side
047     * effects.
048     *
049     * @param context
050     *            The request server context, such as associated principal.
051     * @param request
052     *            The action request.
053     * @return The possibly {@code null} result of the action.
054     * @throws ResourceException
055     *             If the request failed for some reason.
056     * @see RequestHandler#handleAction(Context, ActionRequest)
057     */
058    ActionResponse handleAction(Context context, ActionRequest request) throws ResourceException;
059
060    /**
061     * Adds a new JSON resource.
062     *
063     * @param context
064     *            The request server context, such as associated principal.
065     * @param request
066     *            The create request.
067     * @return The new resource.
068     * @throws ResourceException
069     *             If the request failed for some reason.
070     * @see RequestHandler#handleCreate(Context, CreateRequest)
071     */
072    ResourceResponse handleCreate(Context context, CreateRequest request) throws ResourceException;
073
074    /**
075     * Deletes a JSON resource.
076     *
077     * @param context
078     *            The request server context, such as associated principal.
079     * @param request
080     *            The delete request.
081     * @return The deleted resource.
082     * @throws ResourceException
083     *             If the request failed for some reason.
084     * @see RequestHandler#handleDelete(Context, DeleteRequest)
085     */
086    ResourceResponse handleDelete(Context context, DeleteRequest request) throws ResourceException;
087
088    /**
089     * Updates a JSON resource by applying a set of changes to its existing
090     * content.
091     *
092     * @param context
093     *            The request server context, such as associated principal.
094     * @param request
095     *            The patch request.
096     * @return The patched resource.
097     * @throws ResourceException
098     *             If the request failed for some reason.
099     * @see RequestHandler#handlePatch(Context, PatchRequest)
100     */
101    ResourceResponse handlePatch(Context context, PatchRequest request) throws ResourceException;
102
103    /**
104     * Searches for all JSON resources matching a user specified set of
105     * criteria.
106     *
107     * @param context
108     *            The request server context, such as associated principal.
109     * @param request
110     *            The query request.
111     * @param resources
112     *            A non-{@code null} collection into which matching resources
113     *            should be put.
114     * @return The query result.
115     * @throws ResourceException
116     *             If the request failed for some reason.
117     * @see RequestHandler#handleQuery(Context, QueryRequest, QueryResourceHandler)
118     */
119    QueryResponse handleQuery(Context context, QueryRequest request,
120            Collection<ResourceResponse> resources) throws ResourceException;
121
122    /**
123     * Reads a JSON resource.
124     *
125     * @param context
126     *            The request server context, such as associated principal.
127     * @param request
128     *            The read request.
129     * @return The resource.
130     * @throws ResourceException
131     *             If the request failed for some reason.
132     * @see RequestHandler#handleRead(Context, ReadRequest)
133     */
134    ResourceResponse handleRead(Context context, ReadRequest request) throws ResourceException;
135
136    /**
137     * Updates a JSON resource by replacing its existing content with new
138     * content.
139     *
140     * @param context
141     *            The request server context, such as associated principal.
142     * @param request
143     *            The update request.
144     * @return The updated resource.
145     * @throws ResourceException
146     *             If the request failed for some reason.
147     * @see RequestHandler#handleUpdate(Context, UpdateRequest)
148     */
149    ResourceResponse handleUpdate(Context context, UpdateRequest request) throws ResourceException;
150}