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 2016-2017 ForgeRock AS.
015 */
016package org.forgerock.api.commons;
017
018import org.forgerock.api.models.ApiDescription;
019import org.forgerock.api.models.ApiError;
020import org.forgerock.api.models.Errors.Builder;
021import org.forgerock.util.i18n.LocalizableString;
022
023/** Commons ForgeRock API description. */
024public final class CommonsApi {
025    /** The api description of "frapi:common" which only contains errors so far. */
026    public static final ApiDescription COMMONS_API_DESCRIPTION = buildCommonsApi();
027
028    /** Base-prefix for common API error definition JSON references. */
029    private static final String BASE_ERRORS_REF = "frapi:common#/errors/";
030
031    /** JSON Reference to {@link Errors#BAD_REQUEST} in an API Description. */
032    public static final String BAD_REQUEST_REF = BASE_ERRORS_REF + "badRequest";
033
034    /** JSON Reference to {@link Errors#UNAUTHORIZED} in an API Description. */
035    public static final String UNAUTHORIZED_REF = BASE_ERRORS_REF + "unauthorized";
036
037    /** JSON Reference to {@link Errors#PAYMENT_REQUIRED} in an API Description. */
038    public static final String PAYMENT_REQUIRED_REF = BASE_ERRORS_REF + "paymentRequired";
039
040    /** JSON Reference to {@link Errors#FORBIDDEN} in an API Description. */
041    public static final String FORBIDDEN_REF = BASE_ERRORS_REF + "forbidden";
042
043    /** JSON Reference to {@link Errors#NOT_FOUND} in an API Description. */
044    public static final String NOT_FOUND_REF = BASE_ERRORS_REF + "notFound";
045
046    /** JSON Reference to {@link Errors#METHOD_NOT_ALLOWED} in an API Description. */
047    public static final String METHOD_NOT_ALLOWED_REF = BASE_ERRORS_REF + "methodNotAllowed";
048
049    /** JSON Reference to {@link Errors#NOT_ACCEPTABLE} in an API Description. */
050    public static final String NOT_ACCEPTABLE_REF = BASE_ERRORS_REF + "notAcceptable";
051
052    /** JSON Reference to {@link Errors#PROXY_AUTH_REQUIRED} in an API Description. */
053    public static final String PROXY_AUTH_REQUIRED_REF = BASE_ERRORS_REF + "proxyAuthRequired";
054
055    /** JSON Reference to {@link Errors#REQUEST_TIMEOUT} in an API Description. */
056    public static final String REQUEST_TIMEOUT_REF = BASE_ERRORS_REF + "requestTimeout";
057
058    /** JSON Reference to {@link Errors#CONFLICT} in an API Description. */
059    public static final String CONFLICT_REF = BASE_ERRORS_REF + "conflict";
060
061    /** JSON Reference to {@link Errors#GONE} in an API Description. */
062    public static final String GONE_REF = BASE_ERRORS_REF + "gone";
063
064    /** JSON Reference to {@link Errors#LENGTH_REQUIRED} in an API Description. */
065    public static final String LENGTH_REQUIRED_REF = BASE_ERRORS_REF + "lengthRequired";
066
067    /** JSON Reference to {@link Errors#VERSION_MISMATCH} in an API Description. */
068    public static final String VERSION_MISMATCH_REF = BASE_ERRORS_REF + "versionMismatch";
069
070    /** JSON Reference to {@link Errors#PRECONDITION_FAILED} in an API Description. */
071    public static final String PRECONDITION_FAILED_REF = BASE_ERRORS_REF + "preconditionFailed";
072
073    /** JSON Reference to {@link Errors#REQUEST_ENTITY_TOO_LARGE} in an API Description. */
074    public static final String REQUEST_ENTITY_TOO_LARGE_REF = BASE_ERRORS_REF + "requestEntityTooLarge";
075
076    /** JSON Reference to {@link Errors#REQUEST_URI_TOO_LARGE} in an API Description. */
077    public static final String REQUEST_URI_TOO_LARGE_REF = BASE_ERRORS_REF + "requestUriTooLarge";
078
079    /** JSON Reference to {@link Errors#UNSUPPORTED_MEDIA_TYPE} in an API Description. */
080    public static final String UNSUPPORTED_MEDIA_TYPE_REF = BASE_ERRORS_REF + "unsupportedMediaType";
081
082    /** JSON Reference to {@link Errors#RANGE_NOT_SATISFIABLE} in an API Description. */
083    public static final String RANGE_NOT_SATISFIABLE_REF = BASE_ERRORS_REF + "rangeNotSatisfiable";
084
085    /** JSON Reference to {@link Errors#EXPECTATION_FAILED} in an API Description. */
086    public static final String EXPECTATION_FAILED_REF = BASE_ERRORS_REF + "expectationFailed";
087
088    /** JSON Reference to {@link Errors#VERSION_REQUIRED} in an API Description. */
089    public static final String VERSION_REQUIRED_REF = BASE_ERRORS_REF + "versionRequired";
090
091    /** JSON Reference to {@link Errors#PRECONDITION_REQUIRED} in an API Description. */
092    public static final String PRECONDITION_REQUIRED_REF = BASE_ERRORS_REF + "preconditionRequired";
093
094    /** JSON Reference to {@link Errors#INTERNAL_SERVER_ERROR} in an API Description. */
095    public static final String INTERNAL_SERVER_ERROR_REF = BASE_ERRORS_REF + "internalServerError";
096
097    /** JSON Reference to {@link Errors#NOT_SUPPORTED} in an API Description. */
098    public static final String NOT_SUPPORTED_REF = BASE_ERRORS_REF + "notSupported";
099
100    /** JSON Reference to {@link Errors#BAD_GATEWAY} in an API Description. */
101    public static final String BAD_GATEWAY_REF = BASE_ERRORS_REF + "badGateway";
102
103    /** JSON Reference to {@link Errors#UNAVAILABLE} in an API Description. */
104    public static final String UNAVAILABLE_REF = BASE_ERRORS_REF + "unavailable";
105
106    /** JSON Reference to {@link Errors#GATEWAY_TIMEOUT} in an API Description. */
107    public static final String GATEWAY_TIMEOUT_REF = BASE_ERRORS_REF + "gatewayTimeout";
108
109    /** JSON Reference to {@link Errors#HTTP_VERSION_NOT_SUPPORTED} in an API Description. */
110    public static final String HTTP_VERSION_NOT_SUPPORTED_REF = BASE_ERRORS_REF + "httpVersionNotSupported";
111
112    /** Common api errors. */
113    public enum Errors {
114        // NOTE: if you add to this enum, please also define a corresponding _REF above
115
116        /** The "bad request" error. */
117        BAD_REQUEST                (400, "badRequest"),
118        /** The "unauthorized" error. */
119        UNAUTHORIZED               (401, "unauthorized"),
120        /** The "payment required" error. */
121        PAYMENT_REQUIRED           (402, "paymentRequired"),
122        /** The "forbidden" error. */
123        FORBIDDEN                  (403, "forbidden"),
124        /** The "not found" error. */
125        NOT_FOUND                  (404, "notFound"),
126        /** The "method not allowed" error. */
127        METHOD_NOT_ALLOWED         (405, "methodNotAllowed"),
128        /** The "not acceptable" error. */
129        NOT_ACCEPTABLE             (406, "notAcceptable"),
130        /** The "proxy auth required" error. */
131        PROXY_AUTH_REQUIRED        (407, "proxyAuthRequired"),
132        /** The "request timeout" error. */
133        REQUEST_TIMEOUT            (408, "requestTimeout"),
134        /** The "conflict" error. */
135        CONFLICT                   (409, "conflict"),
136        /** The "gone" error. */
137        GONE                       (410, "gone"),
138        /** The "length required" error. */
139        LENGTH_REQUIRED            (411, "lengthRequired"),
140        /** The "version mismatch" error. */
141        VERSION_MISMATCH           (412, "versionMismatch"),
142        /** The "precondition failed" error. */
143        PRECONDITION_FAILED        (412, "preconditionFailed"),
144        /** The "request entity too large" error. */
145        REQUEST_ENTITY_TOO_LARGE   (413, "requestEntityTooLarge"),
146        /** The "request uri too large" error. */
147        REQUEST_URI_TOO_LARGE      (414, "requestUriTooLarge"),
148        /** The "unsupported media type" error. */
149        UNSUPPORTED_MEDIA_TYPE     (415, "unsupportedMediaType"),
150        /** The "range not satisfiable" error. */
151        RANGE_NOT_SATISFIABLE      (416, "rangeNotSatisfiable"),
152        /** The "expectation failed" error. */
153        EXPECTATION_FAILED         (417, "expectationFailed"),
154        /** The "version required " error. */
155        VERSION_REQUIRED           (428, "versionRequired"),
156        /** The "precondition required" error. */
157        PRECONDITION_REQUIRED      (428, "preconditionRequired"),
158        /** The "internal server error" error. */
159        INTERNAL_SERVER_ERROR      (500, "internalServerError"),
160        /** The "not supported" error. */
161        NOT_SUPPORTED              (501, "notSupported"),
162        /** The "bad gateway" error. */
163        BAD_GATEWAY                (502, "badGateway"),
164        /** The "unavailable" error. */
165        UNAVAILABLE                (503, "unavailable"),
166        /** The "gateway timeout" error. */
167        GATEWAY_TIMEOUT            (504, "gatewayTimeout"),
168        /** The "http version not supported" error. */
169        HTTP_VERSION_NOT_SUPPORTED (505, "httpVersionNotSupported");
170
171        private String camelCaseName;
172        private String reference;
173        private int code;
174        private String translationKey;
175
176        private Errors(int errorCode, String camelCaseName) {
177            this.code = errorCode;
178            this.camelCaseName = camelCaseName;
179            this.reference = BASE_ERRORS_REF + camelCaseName;
180            this.translationKey = "error." + camelCaseName + ".description";
181        }
182
183        /**
184         * The reference to use in an API description.
185         *
186         * @return the reference of this error
187         */
188        public String getReference() {
189            return reference;
190        }
191
192        private ApiError toApiError() {
193            return ApiError.apiError().code(code).description(i18n(translationKey)).build();
194        }
195    }
196
197    private static ApiDescription buildCommonsApi() {
198        final Builder commonErrors = org.forgerock.api.models.Errors.errors();
199        for (Errors error : Errors.values()) {
200            commonErrors.put(error.camelCaseName, error.toApiError());
201        }
202
203        return ApiDescription
204            .apiDescription()
205            .id("frapi:common")
206            .description(i18n("commonApi.description"))
207            .version("1.0.0")
208            .errors(commonErrors.build())
209            .build();
210    }
211
212    private static LocalizableString i18n(String translationKey) {
213        String value = "i18n:org/forgerock/api/commons/frapiCommons#" + translationKey;
214        return new LocalizableString(value, CommonsApi.class.getClassLoader());
215    }
216
217    private CommonsApi() {
218        // private for utility classes
219    }
220}