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 ForgeRock AS.
015 */
016
017package org.forgerock.api.annotations;
018
019/**
020 * Details of a handler.
021 */
022public @interface Handler {
023    /**
024     * The service identifier.
025     * <br>
026     * If a value is provided this indicates to the API Descriptor framework that you intend to reuse
027     * the same service definition multiple times, and that it should define the service globally
028     * and bind it to paths by reference instead of by value.
029     * <br>
030     * Example:
031     *
032     * <code>
033     *   <pre>
034     * "services": {
035     *   "users:1.0": {
036     *     "type": "collection",
037     *     "resourceSchema": {
038     *       "$ref": "#/definitions/user"
039     *     },
040     *     ...
041     *   }
042     * }
043     * "paths": {
044     *   "/users": {
045     *     "1.0": {
046     *       "$ref": "#/services/users:1.0"
047     *     },
048     *   }
049     * }
050     *   </pre>
051     * </code>
052     */
053    String id() default "";
054
055    /**
056     * The schema for all the standard resource operations (CRUDPQ) on this endpoint. Only required if one or more
057     * of those operations are supported.
058     */
059    Schema resourceSchema() default @Schema;
060
061    /** Whether MVCC style requests are supported. */
062    boolean mvccSupported();
063
064    /** Service title, for documentation purposes. */
065    String title() default "";
066
067    /** Service description, for documentation purposes. */
068    String description() default "";
069
070    /** Parameters on service paths and/or endpoints. */
071    Parameter[] parameters() default {};
072}