1 // Copyright (c) 2009 The Chromium Authors. All rights reserved.

     2 // Use of this source code is governed by a BSD-style license that can be

     3 // found in the LICENSE file.

     4 

     5 package org.chromium.sdk.internal.protocolparser;

     6 

     7 import java.lang.annotation.ElementType;

     8 import java.lang.annotation.Retention;

     9 import java.lang.annotation.RetentionPolicy;

    10 import java.lang.annotation.Target;

    11 

    12 import org.json.simple.JSONArray;

    13 import org.json.simple.JSONObject;

    14 

    15 /**

    16  * Marks an interface as interface to json type object. This way user may hold JSON object in

    17  * form of statically typed Java interface. The interface provides methods for reading properties

    18  * (here called fields, because we imply there are "types" in JSON) and for accessing subtypes.

    19  * <p>

    20  * In this design casting to subtypes means getting a different object of the subtype interface.

    21  * For a type interface, a set of subtypes is defined by its methods

    22  * with {@link JsonSubtypeCasting} annotation. These methods provide access to subtype objects.

    23  * From the parsing point of view, subtypes are supported in 2 different ways, as controlled

    24  * by {@link #subtypesChosenManually()} flag:

    25  * <ul>

    26  * <li>{@link #subtypesChosenManually()} is false; when parsing, a particular subtype is selected

    27  * automatically from set of all possible subtypes. JsonSubtypeCondition* annotations in subtypes

    28  * define conditions for selection. Subtype object (together with sub-subtype object, etc) is

    29  * created at the time of parsing. An empty subtype, which is selected if nothing else matches,

    30  * may be declared with void-returning {@link JsonSubtypeCasting}-marked method.

    31  * <li>{@link #subtypesChosenManually()} is true; subtype is not determined automatically. Instead,

    32  * clients may choose a casting method themselves and invoke parsing and object creation at runtime.

    33  * JsonType objects with {@link #subtypesChosenManually()}=true may be built not only on

    34  * {@link JSONObject}, but also on {@link JSONArray} etc.

    35  * </ul>

    36  * <p>

    37  * To provide access to underlying {@link JSONObject} the type interface may extend

    38  * {@link JsonObjectBased} interface. To provide access to underlying object

    39  * (not necessarily JSONObject) type interface may extend {@link AnyObjectBased} interface.

    40  */

    41 @Target({ElementType.TYPE})

    42 @Retention(RetentionPolicy.RUNTIME)

    43 public @interface JsonType {

    44   boolean subtypesChosenManually() default false;

    45 }