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

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

// found in the LICENSE file.

package org.chromium.sdk.internal.protocolparser;

import java.lang.annotation.ElementType;

import java.lang.annotation.Retention;

import java.lang.annotation.RetentionPolicy;

import java.lang.annotation.Target;

import org.json.simple.JSONArray;

import org.json.simple.JSONObject;

/**

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

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

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

 * <p>

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

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

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

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

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

 * <ul>

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

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

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

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

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

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

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

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

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

 * </ul>

 * <p>

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

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

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

 */

@Target({ElementType.TYPE})

@Retention(RetentionPolicy.RUNTIME)

public @interface JsonType {

  boolean subtypesChosenManually() default false;

}