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 org.forgerock.services.context.Context;
020import org.forgerock.util.promise.Promise;
021
022/**
023 * An implementation interface for resource providers which exposes a single
024 * permanent resource instance. A singleton resource may support the following
025 * operations:
026 * <ul>
027 * <li>action
028 * <li>patch
029 * <li>read
030 * <li>update
031 * </ul>
032 * More specifically, a singleton resource cannot be created, deleted, or
033 * queried and may only support a limited sub-set of actions.
034 * <p>
035 * <b>NOTE:</b> field filtering alters the structure of a JSON resource and MUST
036 * only be performed once while processing a request. It is therefore the
037 * responsibility of front-end implementations (e.g. HTTP listeners, Servlets,
038 * etc) to perform field filtering. Request handler and resource provider
039 * implementations SHOULD NOT filter fields, but MAY choose to optimise their
040 * processing in order to return a resource containing only the fields targeted
041 * by the field filters.
042 */
043public interface SingletonResourceProvider {
044
045    /**
046     * Performs the provided
047     * {@link RequestHandler#handleAction(Context, ActionRequest)
048     * action} against the single resource instance.
049     *
050     * @param context
051     *            The request server context.
052     * @param request
053     *            The action request.
054     * @return A {@code Promise} containing the result of the operation.
055     * @see RequestHandler#handleAction(Context, ActionRequest)
056     */
057    Promise<ActionResponse, ResourceException> actionInstance(Context context, ActionRequest request);
058
059    /**
060     * {@link RequestHandler#handlePatch(Context, PatchRequest)
061     * Patches} the single resource instance.
062     *
063     * @param context
064     *            The request server context.
065     * @param request
066     *            The patch request.
067     * @return A {@code Promise} containing the result of the operation.
068     * @see RequestHandler#handlePatch(Context, PatchRequest)
069     */
070    Promise<ResourceResponse, ResourceException> patchInstance(Context context, PatchRequest request);
071
072    /**
073     * {@link RequestHandler#handleRead(Context, ReadRequest)
074     * Reads} the single resource instance.
075     *
076     * @param context
077     *            The request server context.
078     * @param request
079     *            The read request.
080     * @return A {@code Promise} containing the result of the operation.
081     * @see RequestHandler#handleRead(Context, ReadRequest)
082     */
083    Promise<ResourceResponse, ResourceException> readInstance(Context context, ReadRequest request);
084
085    /**
086     * {@link RequestHandler#handleUpdate(Context, UpdateRequest)
087     * Updates} the single resource instance.
088     *
089     * @param context
090     *            The request server context.
091     * @param request
092     *            The update request.
093     * @return A {@code Promise} containing the result of the operation.
094     * @see RequestHandler#handleUpdate(Context, UpdateRequest)
095     */
096    Promise<ResourceResponse, ResourceException> updateInstance(Context context, UpdateRequest request);
097}