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 Copyright [year] [name of copyright owner]".
013 *
014 * Copyright 2012-2015 ForgeRock AS.
015 */
016
017package org.forgerock.json.resource;
018
019import java.util.List;
020import java.util.Map;
021
022import org.forgerock.http.routing.Version;
023import org.forgerock.json.JsonPointer;
024import org.forgerock.json.JsonValue;
025import org.forgerock.util.i18n.PreferredLocales;
026
027/**
028 * A request to update a JSON resource by replacing its existing content with new content.
029 */
030public interface UpdateRequest extends Request {
031
032    /**
033     * The name of the field which contains the resource content in the JSON representation.
034     */
035    String FIELD_CONTENT = "content";
036
037    /**
038     * The name of the field which contains the resource version in the JSON representation.
039     */
040    String FIELD_REVISION = "revision";
041
042
043    @Override
044    <R, P> R accept(final RequestVisitor<R, P> v, final P p);
045
046
047    @Override
048    UpdateRequest addField(JsonPointer... fields);
049
050
051    @Override
052    UpdateRequest addField(String... fields);
053
054
055    @Override
056    String getAdditionalParameter(String name);
057
058
059    @Override
060    Map<String, String> getAdditionalParameters();
061
062    /**
063     * Returns the content of the JSON resource to be replaced.
064     *
065     * @return The content of the JSON resource to be replaced.
066     */
067    JsonValue getContent();
068
069
070    @Override
071    List<JsonPointer> getFields();
072
073
074    @Override
075    PreferredLocales getPreferredLocales();
076
077
078    @Override
079    RequestType getRequestType();
080
081    @Override
082    String getResourcePath();
083
084    @Override
085    ResourcePath getResourcePathObject();
086
087    @Override
088    Version getResourceVersion();
089
090    /**
091     * Returns the expected version information associated with the JSON resource to be updated. Version information can
092     * be used in order to implement multi-version concurrency control (MVCC).
093     * <p>
094     * The returned version information may be {@code null} indicating that the client does not care if the resource has
095     * been modified concurrently. If the version information is non-{@code null}, and it does not match the current
096     * version of the targeted JSON resource, then the update request will be rejected by the provider.
097     *
098     * @return The expected version information associated with the JSON resource to be updated.
099     */
100    String getRevision();
101
102    @Override
103    UpdateRequest setAdditionalParameter(String name, String value) throws BadRequestException;
104
105    /**
106     * Sets the content of the JSON resource to be replaced.
107     *
108     * @param content
109     *         The content of the JSON resource to be replaced.
110     * @return This update request.
111     * @throws UnsupportedOperationException
112     *         If this update request does not permit changes to the content.
113     */
114    UpdateRequest setContent(JsonValue content);
115
116
117    @Override
118    UpdateRequest setPreferredLocales(PreferredLocales preferredLocales);
119
120
121    @Override
122    UpdateRequest setResourcePath(String path);
123
124
125    @Override
126    UpdateRequest setResourcePath(ResourcePath path);
127
128
129    @Override
130    UpdateRequest setResourceVersion(Version resourceVersion);
131
132    /**
133     * Sets the expected version information associated with the JSON resource to be updated. Version information can be
134     * used in order to implement multi-version concurrency control (MVCC).
135     * <p>
136     * The provided version information may be {@code null} indicating that the client does not care if the resource has
137     * been modified concurrently. If the version information is non-{@code null}, and it does not match the current
138     * version of the targeted JSON resource, then the update request will be rejected by the provider.
139     *
140     * @param version
141     *         The expected version information associated with the JSON resource to be updated.
142     * @return This patch request.
143     * @throws UnsupportedOperationException
144     *         If this update request does not permit changes to the version information.
145     */
146    UpdateRequest setRevision(String version);
147
148
149    @Override
150    JsonValue toJsonValue();
151}