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;
020
021import org.forgerock.json.JsonPointer;
022import org.forgerock.json.JsonValue;
023import org.forgerock.util.promise.Promise;
024
025/**
026 * A resource, comprising of a resource ID, a revision (etag), and its JSON
027 * content.
028 */
029public interface ResourceResponse extends Response {
030
031    /**
032     * The name of the field which contains the resource ID in the JSON
033     * representation.
034     * <p>
035     * <b>Note:</b> when encoding the resource ID as part of a resource's
036     * content the field name {@link #FIELD_CONTENT_ID} should be used.
037     */
038    String FIELD_ID = "id";
039
040    /**
041     * The name of the field which contains the resource version in the JSON
042     * representation.
043     * <p>
044     * <b>Note:</b> when encoding the resource revision as part of a resource's
045     * content the field name {@link #FIELD_CONTENT_REVISION} should be used.
046     */
047    String FIELD_REVISION = "revision";
048
049    /**
050     * The name of the field in the resource content which contains the resource
051     * ID. This field is semantically equivalent to {@link #FIELD_ID} and is
052     * intended for use in cases where a commons REST API wishes to expose the
053     * resource ID as part of the resource content.
054     */
055    String FIELD_CONTENT_ID = "_id";
056
057    /**
058     * The name of the field in the resource content which contains the resource
059     * revision. This field is semantically equivalent to
060     * {@link #FIELD_REVISION} and is intended for use in cases where a commons
061     * REST API wishes to expose the resource revision as part of the resource
062     * content.
063     */
064    String FIELD_CONTENT_REVISION = "_rev";
065
066    /**
067     * The name of the field which contains the resource content in the JSON
068     * representation.
069     */
070    String FIELD_CONTENT = "content";
071
072    /**
073     * Returns the JSON content of this resource.
074     *
075     * @return The JSON content of this resource.
076     */
077    JsonValue getContent();
078
079    /**
080     * Returns the ID of this resource, if applicable.
081     *
082     * @return The ID of this resource, or {@code null} if this resource does
083     *         not have an ID.
084     */
085    String getId();
086
087    /**
088     * Returns the revision of this resource, if known.
089     *
090     * @return The revision of this resource, or {@code null} if the version is
091     *         not known.
092     */
093    String getRevision();
094
095    /**
096     * Returns the list of fields which should be included in this JSON resource
097     * after field filtering has occurred. This list will override the list of
098     * fields that is included in the request. An empty list indicates that the
099     * original list of fields in the request should be used for filtering the
100     * response.
101     *
102     * @return The list of fields which should be included in this JSON resource
103     *         after field filtering has occurred.
104     */
105    List<JsonPointer> getFields();
106
107    /**
108     * Returns true if any fields have been added, indicating that the list of
109     * fields in this response should be included in this JSON resource after
110     * field filtering has occurred, otherwise returns false indicating that the
111     * original list of fields in the request should be used for filtering the
112     * response.
113     *
114     * @return true if any fields have been added, false otherwise.
115     */
116    boolean hasFields();
117
118    /**
119     * Adds a field to the list of fields which should be included in this JSON
120     * resource after field filtering has occurred. This list will override the
121     * list of fields that is included in the request.
122     *
123     * @param fields a {@link JsonPointer} representing the field to add.
124     */
125    void addField(JsonPointer... fields);
126
127    /**
128     * Return this response as a result Promise.
129     *
130     * @return A Promise whose result is this ResourceResponse object.
131     */
132    Promise<ResourceResponse, ResourceException> asPromise();
133
134    /**
135     * Returns {@code true} if the provided object is a resource having the same
136     * resource ID and revision as this resource.
137     * <p>
138     * {@inheritDoc}
139     */
140    @Override
141    boolean equals(final Object obj);
142
143    /**
144     * Returns the hash code for this resource. Two resources are guaranteed to
145     * have the same hash code if they share the same resource ID and revision.
146     * <p>
147     * {@inheritDoc}
148     */
149    @Override
150    int hashCode();
151}