/*
 * The contents of this file are subject to the terms of the Common Development and
 * Distribution License (the License). You may not use this file except in compliance with the
 * License.
 *
 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
 * specific language governing permission and limitations under the License.
 *
 * When distributing Covered Software, include this CDDL Header Notice in each file and include
 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
 * Header, with the fields enclosed by brackets [] replaced by your own identifying
 * information: "Portions Copyright [year] [name of copyright owner]".
 *
 * Copyright 2012-2016 ForgeRock AS.
 */

package org.forgerock.json.resource;

import static org.forgerock.util.Utils.*;

import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.LinkedHashMap;
import java.util.LinkedList;
import java.util.List;
import java.util.Map;

import org.forgerock.http.routing.Version;
import org.forgerock.json.JsonException;
import org.forgerock.json.JsonPointer;
import org.forgerock.json.JsonValue;
import org.forgerock.util.i18n.PreferredLocales;

/**
 * A utility class containing various factory methods for creating and
 * manipulating requests.
 */
public final class Requests {
    private static abstract class AbstractRequestImpl<T extends Request> implements Request {
        private final List<JsonPointer> fields = new LinkedList<>();
        private ResourcePath resourcePath;
        private final Map<String, String> parameters = new LinkedHashMap<>(2);
        private Version resourceVersion;
        private PreferredLocales preferredLocales;

        protected AbstractRequestImpl() {
            // Default constructor.
        }

        protected AbstractRequestImpl(final Request request) {
            this.resourcePath = request.getResourcePathObject();
            this.fields.addAll(request.getFields());
            this.parameters.putAll(request.getAdditionalParameters());
            this.resourceVersion = request.getResourceVersion();
            this.preferredLocales = request.getPreferredLocales();
        }

        @Override
        public final T addField(final JsonPointer... fields) {
            for (final JsonPointer field : fields) {
                this.fields.add(notNull(field));
            }
            return getThis();
        }

        @Override
        public final T addField(final String... fields) {
            try {
                for (final String field : fields) {
                    this.fields.add(new JsonPointer(field));
                }
            } catch (final JsonException e) {
                throw new IllegalArgumentException(e.getMessage());
            }
            return getThis();
        }

        @Override
        public final List<JsonPointer> getFields() {
            return fields;
        }

        @Override
        public final String getResourcePath() {
            return resourcePath.toString();
        }

        @Override
        public final ResourcePath getResourcePathObject() {
            return resourcePath;
        }

        @Override
        public Map<String, String> getAdditionalParameters() {
            return parameters;
        }

        @Override
        public String getAdditionalParameter(final String name) {
            return parameters.get(name);
        }

        @Override
        public Version getResourceVersion() {
            return resourceVersion;
        }

        @Override
        public final T setResourcePath(final String path) {
            resourcePath = ResourcePath.valueOf(path);
            return getThis();
        }

        @Override
        public final T setResourcePath(final ResourcePath path) {
            resourcePath = notNull(path);
            return getThis();
        }

        @Override
        public T setAdditionalParameter(final String name, final String value) throws BadRequestException {
            if (isReservedParameter(name)) {
                throw new BadRequestException("Unrecognized request parameter '" + name + "'");
            }
            parameters.put(notNull(name), value);
            return getThis();
        }

        @Override
        public T setResourceVersion(Version resourceVersion) {
            this.resourceVersion = resourceVersion;
            return getThis();
        }

        boolean isReservedParameter(String name) {
            return name.startsWith("_");
        }

        protected abstract T getThis();

        @Override
        public JsonValue toJsonValue() {
            return new JsonValue(new HashMap<>())
                    .put("method", getRequestType().name().toLowerCase())
                    .put(FIELD_RESOURCE_PATH, getResourcePath())
                    .put(FIELD_FIELDS, getFields());
        }

        @Override
        public String toString() {
            return toJsonValue().toString();
        }

        @Override
        public PreferredLocales getPreferredLocales() {
            return preferredLocales;
        }

        @Override
        public T setPreferredLocales(PreferredLocales preferredLocales) {
            this.preferredLocales = preferredLocales;
            return getThis();
        }
    }

    private static final class ActionRequestImpl extends AbstractRequestImpl<ActionRequest>
            implements ActionRequest {
        private String actionId;
        private JsonValue content;

        private ActionRequestImpl() {
            // Default constructor.
            content = new JsonValue(null);
        }

        private ActionRequestImpl(final ActionRequest request) {
            super(request);
            this.actionId = request.getAction();
            this.content = copyJsonValue(request.getContent());
        }

        @Override
        public <R, P> R accept(final RequestVisitor<R, P> v, final P p) {
            return v.visitActionRequest(p, this);
        }

        @Override
        public String getAction() {
            return actionId;
        }

        @Override
        public <T extends Enum<T>> T getActionAsEnum(final Class<T> type) {
            return asEnum(getAction(), type);
        }

        @Override
        public JsonValue getContent() {
            return content;
        }

        @Override
        public ActionRequest setAction(final String id) {
            this.actionId = notNull(id);
            return this;
        }

        @Override
        public ActionRequest setContent(final JsonValue content) {
            this.content = content != null ? content : new JsonValue(null);
            return this;
        }

        @Override
        protected ActionRequest getThis() {
            return this;
        }

        @Override
        public RequestType getRequestType() {
            return RequestType.ACTION;
        }

        @Override
        public JsonValue toJsonValue() {
            return super.toJsonValue()
                    .put(FIELD_ACTION, String.valueOf(getAction()))
                    .put(FIELD_CONTENT, getContent().getObject())
                    .put(FIELD_ADDITIONAL_PARAMETERS, getAdditionalParameters());
        }

        @Override
        boolean isReservedParameter(String name) {
            // no reserved parameters for ActionRequests in order to support current patch-by-query usage *except*
            // mimeType which only applies to true read requests.
            return name.equals("_mimeType");
        }
    }

    private static final class CreateRequestImpl extends AbstractRequestImpl<CreateRequest>
            implements CreateRequest {
        private JsonValue content;
        private String newResourceId;

        private CreateRequestImpl() {
            // Default constructor.
        }

        private CreateRequestImpl(final CreateRequest request) {
            super(request);
            this.content = copyJsonValue(request.getContent());
            this.newResourceId = request.getNewResourceId();
        }

        @Override
        public <R, P> R accept(final RequestVisitor<R, P> v, final P p) {
            return v.visitCreateRequest(p, this);
        }

        @Override
        public JsonValue getContent() {
            return content;
        }

        @Override
        public String getNewResourceId() {
            return newResourceId;
        }

        @Override
        public CreateRequest setContent(final JsonValue content) {
            this.content = notNull(content);
            return this;
        }

        @Override
        public CreateRequest setNewResourceId(final String id) {
            this.newResourceId = id;
            return this;
        }

        @Override
        protected CreateRequest getThis() {
            return this;
        }

        @Override
        public RequestType getRequestType() {
            return RequestType.CREATE;
        }

        @Override
        public JsonValue toJsonValue() {
            return super.toJsonValue()
                    .put(FIELD_NEW_RESOURCE_ID, getNewResourceId())
                    .put(FIELD_CONTENT, getContent().getObject());
        }

    }

    private static final class DeleteRequestImpl extends AbstractRequestImpl<DeleteRequest>
            implements DeleteRequest {
        private String version;

        private DeleteRequestImpl() {
            // Default constructor.
        }

        private DeleteRequestImpl(final DeleteRequest request) {
            super(request);
            this.version = request.getRevision();
        }

        @Override
        public <R, P> R accept(final RequestVisitor<R, P> v, final P p) {
            return v.visitDeleteRequest(p, this);
        }

        @Override
        public String getRevision() {
            return version;
        }

        @Override
        public DeleteRequest setRevision(final String version) {
            this.version = version;
            return this;
        }

        @Override
        protected DeleteRequest getThis() {
            return this;
        }

        @Override
        public RequestType getRequestType() {
            return RequestType.DELETE;
        }

        @Override
        public JsonValue toJsonValue() {
            return super.toJsonValue()
                    .put(FIELD_REVISION, String.valueOf(getRevision()));
        }

    }

    private static final class PatchRequestImpl extends AbstractRequestImpl<PatchRequest> implements
            PatchRequest {
        private List<PatchOperation> operations;
        private String version;

        private PatchRequestImpl() {
            operations = new LinkedList<>();
        }

        private PatchRequestImpl(final PatchRequest request) {
            super(request);
            this.operations = new LinkedList<>(request.getPatchOperations());
            this.version = request.getRevision();
        }

        @Override
        public <R, P> R accept(final RequestVisitor<R, P> v, final P p) {
            return v.visitPatchRequest(p, this);
        }

        @Override
        public String getRevision() {
            return version;
        }

        @Override
        public PatchRequest addPatchOperation(PatchOperation... operations) {
            Collections.addAll(this.operations, operations);
            return this;
        }

        @Override
        public List<PatchOperation> getPatchOperations() {
            return operations;
        }

        @Override
        public PatchRequest addPatchOperation(String operation, String field, JsonValue value) {
            operations.add(PatchOperation.operation(operation, field, value));
            return this;
        }

        @Override
        public PatchRequest setRevision(final String version) {
            this.version = version;
            return this;
        }

        @Override
        protected PatchRequest getThis() {
            return this;
        }

        @Override
        public RequestType getRequestType() {
            return RequestType.PATCH;
        }

        @Override
        public JsonValue toJsonValue() {
            final List<Object> operations = new ArrayList<>();
            for (PatchOperation operation : getPatchOperations()) {
                operations.add(operation.toJsonValue().getObject());
            }
            return super.toJsonValue()
                    .put(FIELD_REVISION, String.valueOf(getRevision()))
                    .put(FIELD_PATCH_OPERATIONS, operations);
        }
    }

    private static final class QueryRequestImpl extends AbstractRequestImpl<QueryRequest> implements
            QueryRequest {
        private org.forgerock.util.query.QueryFilter<JsonPointer> filter;
        private final List<SortKey> keys = new LinkedList<>();
        private String pagedResultsCookie;
        private CountPolicy totalPagedResultsPolicy = CountPolicy.NONE;
        private int pagedResultsOffset = 0;
        private int pageSize = 0;
        private String queryId;
        private String queryExpression;

        private QueryRequestImpl() {
            // Default constructor.
        }

        private QueryRequestImpl(final QueryRequest request) {
            super(request);
            this.filter = request.getQueryFilter();
            this.queryId = request.getQueryId();
            this.queryExpression = request.getQueryExpression();
            this.keys.addAll(request.getSortKeys());
            this.pageSize = request.getPageSize();
            this.pagedResultsCookie = request.getPagedResultsCookie();
            this.pagedResultsOffset = request.getPagedResultsOffset();
            this.totalPagedResultsPolicy = request.getTotalPagedResultsPolicy();
        }

        @Override
        public <R, P> R accept(final RequestVisitor<R, P> v, final P p) {
            return v.visitQueryRequest(p, this);
        }

        @Override
        public QueryRequest addSortKey(final SortKey... keys) {
            for (final SortKey key : keys) {
                this.keys.add(notNull(key));
            }
            return this;
        }

        @Override
        public final QueryRequest addSortKey(final String... keys) {
            for (final String key : keys) {
                this.keys.add(SortKey.valueOf(key));
            }
            return this;
        }

        @Override
        public String getPagedResultsCookie() {
            return pagedResultsCookie;
        }

        @Override
        public CountPolicy getTotalPagedResultsPolicy() {
            return totalPagedResultsPolicy;
        }

        @Override
        public int getPagedResultsOffset() {
            return pagedResultsOffset;
        }

        @Override
        public int getPageSize() {
            return pageSize;
        }

        @Override
        public org.forgerock.util.query.QueryFilter<JsonPointer> getQueryFilter() {
            return filter;
        }

        @Override
        public String getQueryId() {
            return queryId;
        }

        @Override
        public String getQueryExpression() {
            return queryExpression;
        }

        @Override
        public List<SortKey> getSortKeys() {
            return keys;
        }

        @Override
        public QueryRequest setPagedResultsCookie(final String cookie) {
            this.pagedResultsCookie = cookie;
            return this;
        }

        @Override
        public QueryRequest setTotalPagedResultsPolicy(final CountPolicy totalPagedResultsPolicy) {
            this.totalPagedResultsPolicy = notNull(totalPagedResultsPolicy);
            return this;
        }

        @Override
        public QueryRequest setPagedResultsOffset(int offset) {
            this.pagedResultsOffset = offset;
            return this;
        }

        @Override
        public QueryRequest setPageSize(final int size) {
            this.pageSize = size;
            return this;
        }

        @Override
        public QueryRequest setQueryExpression(final String expression) {
            this.queryExpression = expression;
            return this;
        }

        @Override
        public QueryRequest setQueryFilter(final org.forgerock.util.query.QueryFilter<JsonPointer> filter) {
            this.filter = filter;
            return this;
        }

        @Override
        public QueryRequest setQueryId(final String id) {
            this.queryId = id;
            return this;
        }

        @Override
        protected QueryRequest getThis() {
            return this;
        }

        @Override
        public RequestType getRequestType() {
            return RequestType.QUERY;
        }

        @Override
        public JsonValue toJsonValue() {
            final List<String> sortKeys =  new ArrayList<>();
            for (SortKey key : getSortKeys()) {
                sortKeys.add(String.valueOf(key));
            }
            return super.toJsonValue()
                    .put(FIELD_QUERY_ID, String.valueOf(getQueryId()))
                    .put(FIELD_QUERY_EXPRESSION, String.valueOf(getQueryExpression()))
                    .put(FIELD_QUERY_FILTER, String.valueOf(getQueryFilter()))
                    .put(FIELD_SORT_KEYS, sortKeys)
                    .put(FIELD_PAGE_SIZE, String.valueOf(getPageSize()))
                    .put(FIELD_PAGED_RESULTS_OFFSET, String.valueOf(getPagedResultsOffset()))
                    .put(FIELD_PAGED_RESULTS_COOKIE, String.valueOf(getPagedResultsCookie()))
                    .put(FIELD_TOTAL_PAGED_RESULTS_POLICY, String.valueOf(getTotalPagedResultsPolicy()))
                    .put(FIELD_ADDITIONAL_PARAMETERS, getAdditionalParameters());
        }
    }

    private static final class ReadRequestImpl extends AbstractRequestImpl<ReadRequest> implements
            ReadRequest {

        private ReadRequestImpl() {
            // Default constructor.
        }

        private ReadRequestImpl(final ReadRequest request) {
            super(request);
        }

        @Override
        public <R, P> R accept(final RequestVisitor<R, P> v, final P p) {
            return v.visitReadRequest(p, this);
        }

        @Override
        protected ReadRequest getThis() {
            return this;
        }

        @Override
        public RequestType getRequestType() {
            return RequestType.READ;
        }
    }

    private static final class UpdateRequestImpl extends AbstractRequestImpl<UpdateRequest>
            implements UpdateRequest {
        private JsonValue content;
        private String version;

        private UpdateRequestImpl() {
            // Default constructor.
        }

        private UpdateRequestImpl(final UpdateRequest request) {
            super(request);
            this.version = request.getRevision();
            this.content = copyJsonValue(request.getContent());
        }

        @Override
        public <R, P> R accept(final RequestVisitor<R, P> v, final P p) {
            return v.visitUpdateRequest(p, this);
        }

        @Override
        public JsonValue getContent() {
            return content;
        }

        @Override
        public String getRevision() {
            return version;
        }

        @Override
        public UpdateRequest setContent(final JsonValue content) {
            this.content = notNull(content);
            return this;
        }

        @Override
        public UpdateRequest setRevision(final String version) {
            this.version = version;
            return this;
        }

        @Override
        protected UpdateRequest getThis() {
            return this;
        }

        @Override
        public RequestType getRequestType() {
            return RequestType.UPDATE;
        }

        @Override
        public JsonValue toJsonValue() {
            return super.toJsonValue()
                    .put(FIELD_REVISION, String.valueOf(getRevision()))
                    .put(FIELD_CONTENT, getContent().getObject());
        }
    }

    private static final class ApiRequestImpl extends AbstractRequestImpl<Request> {
        private ApiRequestImpl() {
           // nothing to do
        }

        private ApiRequestImpl(ApiRequestImpl request) {
            super(request);
        }

        @Override
        protected Request getThis() {
            return this;
        }

        @Override
        public <R, P> R accept(RequestVisitor<R, P> v, P p) {
            throw new UnsupportedOperationException();
        }

        @Override
        public RequestType getRequestType() {
            return RequestType.API;
        }
    }

    /**
     * Returns a copy of the provided action request.
     *
     * @param request
     *            The action request to be copied.
     * @return The action request copy.
     */
    public static ActionRequest copyOfActionRequest(final ActionRequest request) {
        return new ActionRequestImpl(request);
    }

    /**
     * Returns a copy of the provided create request.
     *
     * @param request
     *            The create request to be copied.
     * @return The create request copy.
     */
    public static CreateRequest copyOfCreateRequest(final CreateRequest request) {
        return new CreateRequestImpl(request);
    }

    /**
     * Returns a copy of the provided delete request.
     *
     * @param request
     *            The delete request to be copied.
     * @return The delete request copy.
     */
    public static DeleteRequest copyOfDeleteRequest(final DeleteRequest request) {
        return new DeleteRequestImpl(request);
    }

    /**
     * Returns a copy of the provided patch request.
     *
     * @param request
     *            The patch request to be copied.
     * @return The patch request copy.
     */
    public static PatchRequest copyOfPatchRequest(final PatchRequest request) {
        return new PatchRequestImpl(request);
    }

    /**
     * Returns a copy of the provided query request.
     *
     * @param request
     *            The query request to be copied.
     * @return The query request copy.
     */
    public static QueryRequest copyOfQueryRequest(final QueryRequest request) {
        return new QueryRequestImpl(request);
    }

    /**
     * Returns a copy of the provided read request.
     *
     * @param request
     *            The read request to be copied.
     * @return The read request copy.
     */
    public static ReadRequest copyOfReadRequest(final ReadRequest request) {
        return new ReadRequestImpl(request);
    }

    /**
     * Returns a copy of the provided update request.
     *
     * @param request
     *            The update request to be copied.
     * @return The update request copy.
     */
    public static UpdateRequest copyOfUpdateRequest(final UpdateRequest request) {
        return new UpdateRequestImpl(request);
    }

    /**
     * Returns a copy of the provided api request.
     *
     * @param request
     *            The api request to be copied.
     * @return The api request copy.
     */
    public static Request copyOfApiRequest(final Request request) {
        return new ApiRequestImpl((ApiRequestImpl) request);
    }

    /**
     * Returns a new action request with the provided resource path and action
     * ID. Invoking this method as follows:
     *
     * <pre>
     * newActionRequest(&quot;users/1&quot;, actionId);
     * </pre>
     *
     * Is equivalent to:
     *
     * <pre>
     * newActionRequest(&quot;users&quot;, &quot;1&quot;, actionId);
     * </pre>
     *
     * Except that the resource ID is already URL encoded in the first form.
     *
     * @param resourcePath
     *            The URL-encoded resource path.
     * @param actionId
     *            The action ID.
     * @return The new action request.
     */
    public static ActionRequest newActionRequest(final String resourcePath, final String actionId) {
        return new ActionRequestImpl().setResourcePath(resourcePath).setAction(actionId);
    }

    /**
     * Returns a new action request with the provided resource path and action
     * ID.
     *
     * @param resourcePath
     *            The parsed resource path.
     * @param actionId
     *            The action ID.
     * @return The new action request.
     */
    public static ActionRequest newActionRequest(final ResourcePath resourcePath,
            final String actionId) {
        return new ActionRequestImpl().setResourcePath(resourcePath).setAction(actionId);
    }

    /**
     * Returns a new action request with the provided resource container path,
     * resource ID, and action ID. Invoking this method as follows:
     *
     * <pre>
     * newActionRequest(&quot;users&quot;, &quot;1&quot;, &quot;someAction&quot;);
     * </pre>
     *
     * Is equivalent to:
     *
     * <pre>
     * newActionRequest(&quot;users/1&quot;, &quot;someAction&quot;);
     * </pre>
     *
     * Except that the resource ID is already URL encoded in the second form.
     *
     * @param resourceContainer
     *            The URL-encoded path of the resource container.
     * @param resourceId
     *            The URL decoded ID of the resource.
     * @param actionId
     *            The action ID.
     * @return The new action request.
     */
    public static ActionRequest newActionRequest(final String resourceContainer,
            final String resourceId, final String actionId) {
        return newActionRequest(ResourcePath.valueOf(resourceContainer), resourceId, actionId);
    }

    /**
     * Returns a new action request with the provided resource container path,
     * resource ID, and action ID.
     *
     * @param resourceContainer
     *            The parsed path of the resource container.
     * @param resourceId
     *            The URL decoded ID of the resource.
     * @param actionId
     *            The action ID.
     * @return The new action request.
     */
    public static ActionRequest newActionRequest(final ResourcePath resourceContainer,
            final String resourceId, final String actionId) {
        return newActionRequest(resourceContainer.child(resourceId), actionId);
    }

    /**
     * Returns a new create request with the provided resource path, and JSON
     * content. The create request will have a {@code null} new resource ID,
     * indicating that the server will be responsible for generating the ID of
     * the new resource. Invoking this method as follows:
     *
     * <pre>
     * newCreateRequest(&quot;users/1&quot;, content);
     * </pre>
     *
     * Is equivalent to:
     *
     * <pre>
     * newCreateRequest(&quot;users&quot;, "1", content);
     * </pre>
     *
     * Except that the resource ID is already URL encoded in the first form.
     *
     * @param resourceContainer
     *            The URL-encoded path of the resource container beneath which the new
     *            resource should be created.
     * @param content
     *            The JSON content.
     * @return The new create request.
     */
    public static CreateRequest newCreateRequest(final String resourceContainer,
            final JsonValue content) {
        return new CreateRequestImpl().setResourcePath(resourceContainer).setContent(content);
    }

    /**
     * Returns a new create request with the provided resource path, and JSON
     * content. The create request will have a {@code null} new resource ID,
     * indicating that the server will be responsible for generating the ID of
     * the new resource.
     *
     * @param resourceContainer
     *            The parsed path of the resource container beneath which the
     *            new resource should be created.
     * @param content
     *            The JSON content.
     * @return The new create request.
     */
    public static CreateRequest newCreateRequest(final ResourcePath resourceContainer,
            final JsonValue content) {
        return new CreateRequestImpl().setResourcePath(resourceContainer).setContent(content);
    }

    /**
     * Returns a new create request with the provided resource path, new
     * resource ID, and JSON content. Invoking this method as follows:
     *
     * <pre>
     * newCreateRequest(&quot;users&quot;, &quot;1&quot;, content);
     * </pre>
     *
     * Is equivalent to:
     *
     * <pre>
     * newCreateRequest(&quot;users&quot;, content).setNewResourceId(&quot;1&quot;);
     * </pre>
     *
     * Except that the resource ID is already URL encoded in the second form.
     *
     * @param resourceContainer
     *            The URL-encoded path of the resource container beneath which
     *            the new resource should be created.
     * @param newResourceId
     *            The URL decoded client provided ID of the resource to be
     *            created, or {@code null} if the server should be responsible
     *            for generating the resource ID.
     * @param content
     *            The JSON content.
     * @return The new create request.
     */
    public static CreateRequest newCreateRequest(final String resourceContainer,
            final String newResourceId, final JsonValue content) {
        return newCreateRequest(resourceContainer, content).setNewResourceId(newResourceId);
    }

    /**
     * Returns a new create request with the provided resource path, new
     * resource ID, and JSON content.
     *
     * @param resourceContainer
     *            The parsed path of the resource container beneath which the
     *            new resource should be created.
     * @param newResourceId
     *            The URL decoded client provided ID of the resource to be
     *            created, or {@code null} if the server should be responsible
     *            for generating the resource ID.
     * @param content
     *            The JSON content.
     * @return The new create request.
     */
    public static CreateRequest newCreateRequest(final ResourcePath resourceContainer,
            final String newResourceId, final JsonValue content) {
        return newCreateRequest(resourceContainer, content).setNewResourceId(newResourceId);
    }

    /**
     * Returns a new delete request with the provided resource path. Invoking
     * this method as follows:
     *
     * <pre>
     * newDeleteRequest(&quot;users/1&quot;);
     * </pre>
     *
     * Is equivalent to:
     *
     * <pre>
     * newDeleteRequest(&quot;users&quot;, &quot;1&quot;);
     * </pre>
     *
     * Except that the resource ID is already URL encoded in the first form.
     *
     * @param resourcePath
     *            The URL-encoded resource path.
     * @return The new delete request.
     */
    public static DeleteRequest newDeleteRequest(final String resourcePath) {
        return new DeleteRequestImpl().setResourcePath(resourcePath);
    }

    /**
     * Returns a new delete request with the provided resource path.
     *
     * @param resourcePath
     *            The parsed resource path.
     * @return The new delete request.
     */
    public static DeleteRequest newDeleteRequest(final ResourcePath resourcePath) {
        return new DeleteRequestImpl().setResourcePath(resourcePath);
    }

    /**
     * Returns a new delete request with the provided resource container path,
     * and resource ID. Invoking this method as follows:
     *
     * <pre>
     * newDeleteRequest(&quot;users&quot;, &quot;1&quot;);
     * </pre>
     *
     * Is equivalent to:
     *
     * <pre>
     * newDeleteRequest(&quot;users/1&quot;);
     * </pre>
     *
     * Except that the resource ID is already URL encoded in the second form.
     *
     * @param resourceContainer
     *            The URL-encoded path of the resource container.
     * @param resourceId
     *            The URL decoded ID of the resource.
     * @return The new delete request.
     */
    public static DeleteRequest newDeleteRequest(final String resourceContainer,
            final String resourceId) {
        return newDeleteRequest(ResourcePath.valueOf(resourceContainer), resourceId);
    }

    /**
     * Returns a new delete request with the provided resource container path,
     * and resource ID.
     *
     * @param resourceContainer
     *            The parsed path of the resource container.
     * @param resourceId
     *            The URL decoded ID of the resource.
     * @return The new delete request.
     */
    public static DeleteRequest newDeleteRequest(final ResourcePath resourceContainer,
            final String resourceId) {
        return newDeleteRequest(resourceContainer.child(resourceId));
    }

    /**
     * Returns a new patch request with the provided resource path and JSON
     * patch operations. Invoking this method as follows:
     *
     * <pre>
     * newPatchRequest(&quot;users/1&quot;, operations);
     * </pre>
     *
     * Is equivalent to:
     *
     * <pre>
     * newPatchRequest(&quot;users&quot;, &quot;1&quot;, operations);
     * </pre>
     *
     * Except that the resource ID is already URL encoded in the first form.
     *
     * @param resourcePath
     *            The URL-encoded resource path.
     * @param operations
     *            The JSON patch operations.
     * @return The new patch request.
     */
    public static PatchRequest newPatchRequest(final String resourcePath,
            final PatchOperation... operations) {
        return new PatchRequestImpl().setResourcePath(resourcePath).addPatchOperation(operations);
    }

    /**
     * Returns a new patch request with the provided resource path and JSON
     * patch operations.
     *
     * @param resourcePath
     *            The parsed resource path.
     * @param operations
     *            The JSON patch operations.
     * @return The new patch request.
     */
    public static PatchRequest newPatchRequest(final ResourcePath resourcePath,
            final PatchOperation... operations) {
        return new PatchRequestImpl().setResourcePath(resourcePath).addPatchOperation(operations);
    }

    /**
     * Returns a new patch request with the provided resource container path,
     * resource ID, and JSON patch operations. Invoking this method as follows:
     *
     * <pre>
     * newPatchRequest(&quot;users&quot;, &quot;1&quot;, operations);
     * </pre>
     *
     * Is equivalent to:
     *
     * <pre>
     * newPatchRequest(&quot;users/1&quot;, operations);
     * </pre>
     *
     * Except that the resource ID is already URL encoded in the second form.
     *
     * @param resourceContainer
     *            The URL-encoded path of the resource container.
     * @param resourceId
     *            The URL decoded ID of the resource.
     * @param operations
     *            The JSON patch operations.
     * @return The new patch request.
     */
    public static PatchRequest newPatchRequest(final String resourceContainer,
            final String resourceId, final PatchOperation... operations) {
        return newPatchRequest(ResourcePath.valueOf(resourceContainer), resourceId, operations);
    }

    /**
     * Returns a new patch request with the provided resource container path,
     * resource ID, and JSON patch operations.
     *
     * @param resourceContainer
     *            The parsed path of the resource container.
     * @param resourceId
     *            The URL decoded ID of the resource.
     * @param operations
     *            The JSON patch operations.
     * @return The new patch request.
     */
    public static PatchRequest newPatchRequest(final ResourcePath resourceContainer,
            final String resourceId, final PatchOperation... operations) {
        return newPatchRequest(resourceContainer.child(resourceId), operations);
    }

    /**
     * Returns a new query request with the provided resource container path.
     * Example:
     *
     * <pre>
     * newQueryRequest(&quot;users&quot;);
     * </pre>
     *
     * @param resourceContainer
     *            The URL-encoded path of the resource container.
     * @return The new query request.
     */
    public static QueryRequest newQueryRequest(final String resourceContainer) {
        return new QueryRequestImpl().setResourcePath(resourceContainer);
    }

    /**
     * Returns a new query request with the provided resource container path.
     * Example:
     *
     * <pre>
     * newQueryRequest(ResourcePath.valueOf(&quot;users&quot;));
     * </pre>
     *
     * @param resourceContainer
     *            The parsed path of the resource container.
     * @return The new query request.
     */
    public static QueryRequest newQueryRequest(final ResourcePath resourceContainer) {
        return new QueryRequestImpl().setResourcePath(resourceContainer);
    }

    /**
     * Returns a new read request with the provided resource path. Invoking this
     * method as follows:
     *
     * <pre>
     * newReadRequest(&quot;users/1&quot;);
     * </pre>
     *
     * Is equivalent to:
     *
     * <pre>
     * newReadRequest(&quot;users&quot;, &quot;1&quot;);
     * </pre>
     *
     * Except that the resource ID is already URL encoded in the first form.
     *
     * @param resourcePath
     *            The URL-encoded resource path.
     * @return The new read request.
     */
    public static ReadRequest newReadRequest(final String resourcePath) {
        return new ReadRequestImpl().setResourcePath(resourcePath);
    }

    /**
     * Returns a new read request with the provided resource path.
     *
     * @param resourcePath
     *            The parsed resource path.
     * @return The new read request.
     */
    public static ReadRequest newReadRequest(final ResourcePath resourcePath) {
        return new ReadRequestImpl().setResourcePath(resourcePath);
    }

    /**
     * Returns a new read request with the provided resource container path, and
     * resource ID. Invoking this method as follows:
     *
     * <pre>
     * newReadRequest(&quot;users&quot;, &quot;1&quot;);
     * </pre>
     *
     * Is equivalent to:
     *
     * <pre>
     * newReadRequest(&quot;users/1&quot;);
     * </pre>
     *
     * Except that the resource ID is already URL encoded in the second form.
     *
     * @param resourceContainer
     *            The URL-encoded path of the resource container.
     * @param resourceId
     *            The URL decoded ID of the resource.
     * @return The new read request.
     */
    public static ReadRequest newReadRequest(final String resourceContainer, final String resourceId) {
        return newReadRequest(ResourcePath.valueOf(resourceContainer), resourceId);
    }

    /**
     * Returns a new read request with the provided resource container path, and
     * resource ID.
     *
     * @param resourceContainer
     *            The parsed path of the resource container.
     * @param resourceId
     *            The URL decoded ID of the resource.
     * @return The new read request.
     */
    public static ReadRequest newReadRequest(final ResourcePath resourceContainer,
            final String resourceId) {
        return newReadRequest(resourceContainer.child(resourceId));
    }

    /**
     * Returns a new update request with the provided resource path and new JSON
     * content. Invoking this method as follows:
     *
     * <pre>
     * newUpdateRequest(&quot;users/1&quot;, newContent);
     * </pre>
     *
     * Is equivalent to:
     *
     * <pre>
     * newUpdateRequest(&quot;users&quot;, &quot;1&quot;, newContent);
     * </pre>
     *
     * Except that the resource ID is already URL encoded in the first form.
     *
     * @param resourcePath
     *            The URL-encoded resource path.
     * @param newContent
     *            The new JSON content.
     * @return The new update request.
     */
    public static UpdateRequest newUpdateRequest(final String resourcePath,
            final JsonValue newContent) {
        return new UpdateRequestImpl().setResourcePath(resourcePath).setContent(newContent);
    }

    /**
     * Returns a new update request with the provided resource path and new JSON
     * content.
     *
     * @param resourcePath
     *            The parsed resource path.
     * @param newContent
     *            The new JSON content.
     * @return The new update request.
     */
    public static UpdateRequest newUpdateRequest(final ResourcePath resourcePath,
            final JsonValue newContent) {
        return new UpdateRequestImpl().setResourcePath(resourcePath).setContent(newContent);
    }

    /**
     * Returns a new update request with the provided resource container path,
     * resource ID, and new JSON content. Invoking this method as follows:
     *
     * <pre>
     * newUpdateRequest(&quot;users&quot;, &quot;1&quot;, newContent);
     * </pre>
     *
     * Is equivalent to:
     *
     * <pre>
     * newUpdateRequest(&quot;users/1&quot;, newContent);
     * </pre>
     *
     * Except that the resource ID is already URL encoded in the second form.
     *
     * @param resourceContainer
     *            The URL-encoded path of the resource container.
     * @param resourceId
     *            The URL decoded ID of the resource.
     * @param newContent
     *            The new JSON content.
     * @return The new update request.
     */
    public static UpdateRequest newUpdateRequest(final String resourceContainer,
            final String resourceId, final JsonValue newContent) {
        return newUpdateRequest(ResourcePath.valueOf(resourceContainer), resourceId, newContent);
    }

    /**
     * Returns a new update request with the provided resource container path,
     * resource ID, and new JSON content.
     *
     * @param resourceContainer
     *            The parsed path of the resource container.
     * @param resourceId
     *            The URL decoded ID of the resource.
     * @param newContent
     *            The new JSON content.
     * @return The new update request.
     */
    public static UpdateRequest newUpdateRequest(final ResourcePath resourceContainer,
            final String resourceId, final JsonValue newContent) {
        return newUpdateRequest(resourceContainer.child(resourceId), newContent);
    }

    /**
     * Returns a new API request with the provided path.
     * @param path The path.
     * @return The request.
     */
    public static Request newApiRequest(final ResourcePath path) {
        return new ApiRequestImpl().setResourcePath(path);
    }

    private static JsonValue copyJsonValue(final JsonValue value) {
        return value != null ? value.copy() : null;
    }

    private static <T> T notNull(final T object) {
        if (object != null) {
            return object;
        } else {
            throw new NullPointerException();
        }
    }

    private Requests() {
        // Prevent instantiation.
    }

    // TODO: unmodifiable
}