/**

  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

  *

  * Copyright 2013-2014 Oracle and/or its affiliates. All rights reserved.

  *

  * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

  * Other names may be trademarks of their respective owners.

  *

  * The contents of this file are subject to the terms of either the GNU

  * General Public License Version 2 only ("GPL") or the Common

  * Development and Distribution License("CDDL") (collectively, the

  * "License"). You may not use this file except in compliance with the

  * License. You can obtain a copy of the License at

  * http://www.netbeans.org/cddl-gplv2.html

  * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the

  * specific language governing permissions and limitations under the

  * License.  When distributing the software, include this License Header

  * Notice in each file and include the License file at

  * nbbuild/licenses/CDDL-GPL-2-CP.  Oracle designates this

  * particular file as subject to the "Classpath" exception as provided

  * by Oracle in the GPL Version 2 section of the License file that

  * accompanied this code. If applicable, add the following below the

  * License Header, with the fields enclosed by brackets [] replaced by

  * your own identifying information:

  * "Portions Copyrighted [year] [name of copyright owner]"

  *

  * Contributor(s):

  *

  * The Original Software is NetBeans. The Initial Developer of the Original

  * Software is Oracle. Portions Copyright 2013-2014 Oracle. All Rights Reserved.

  *

  * If you wish your version of this file to be governed by only the CDDL

  * or only the GPL Version 2, indicate your decision by adding

  * "[Contributor] elects to include this software in this distribution

  * under the [CDDL or GPL Version 2] license." If you do not indicate a

  * single choice of license, a recipient has the option to distribute

  * your version of this file under either the CDDL, the GPL Version 2 or

  * to extend the choice of license to its licensees as provided above.

  * However, if you add GPL Version 2 code and therefore, elected the GPL

  * Version 2 license, then the option applies only if the new code is

  * made subject to such option by the copyright holder.

  */

 package net.java.html.json;

 import java.lang.annotation.ElementType;

 import java.lang.annotation.Retention;

 import java.lang.annotation.RetentionPolicy;

 import java.lang.annotation.Target;

 import java.net.URL;

 import java.util.List;

 /** Defines a model class that represents a single 

  * <a target="_blank" href="http://en.wikipedia.org/wiki/JSON">JSON</a>-like object

  * named {@link #className()}. The generated class contains

  * getters and setters for properties defined via {@link #properties()} and

  * getters for other, derived properties defined by annotating methods

  * of this class by {@link ComputedProperty}. Each property

  * can be of primitive type, an {@link Enum enum type} or (in order to create 

  * nested <a target="_blank" href="http://en.wikipedia.org/wiki/JSON">JSON</a> structure)

  * of another {@link Model class generated by @Model} annotation. Each property

  * can either represent a single value or be an array of its values.

  * <p>

  * The {@link #className() generated class}'s <code>toString</code> method

  * converts the state of the object into 

  * <a target="_blank" href="http://en.wikipedia.org/wiki/JSON">JSON</a> format. One can

  * use {@link Models#parse(net.java.html.BrwsrCtx, java.lang.Class, java.io.InputStream)}

  * method to read the JSON text stored in a file or other stream back into the Java model. 

  * One can also use {@link OnReceive @OnReceive} annotation to read the model

  * asynchronously from a {@link URL}.

  * <p>

  * An example where one defines class <code>Person</code> with four

  * properties (<code>firstName</code>, <code>lastName</code>, array of <code>addresses</code> and

  * <code>fullName</code>) follows:

  * <pre>

  * {@link Model @Model}(className="Person", properties={

  *   {@link Property @Property}(name = "firstName", type=String.<b>class</b>),

  *   {@link Property @Property}(name = "lastName", type=String.<b>class</b>)

  *   {@link Property @Property}(name = "addresses", type=Address.<b>class</b>, array = <b>true</b>)

  * })

  * <b>static class</b> PersonModel {

  *   {@link ComputedProperty @ComputedProperty}

  *   <b>static</b> String fullName(String firstName, String lastName) {

  *     <b>return</b> firstName + " " + lastName;

  *   }

  * 

  *   {@link ComputedProperty @ComputedProperty}

  *   <b>static</b> String mainAddress({@link List List&lt;Address&gt;} addresses) {

  *     <b>for</b> (Address a : addresses) {

  *       <b>return</b> a.getStreet() + " " + a.getTown();

  *     }

  *     <b>return</b> "No address";

  *   }

  * 

  *   {@link Model @Model}(className="Address", properties={

  *     {@link Property @Property}(name = "street", type=String.<b>class</b>),

  *     {@link Property @Property}(name = "town", type=String.<b>class</b>)

  *   })

  *   <b>static class</b> AddressModel {

  *   }

  * }

  * </pre>

  * The generated model class has a default constructor, and also <em>quick

  * instantiation</em> constructor that accepts all non-array properties 

  * (in the order used in the {@link #properties()} attribute) and vararg list

  * for the first array property (if any). One can thus use following code

  * to create an instance of the Person and Address classes:

  * <pre>

  * Person p = <b>new</b> Person("Jaroslav", "Tulach",

  *   <b>new</b> Address("Markoušovice", "Úpice"),

  *   <b>new</b> Address("V Parku", "Praha")

  * );

  * // p.toString() then returns equivalent of following <a target="_blank" href="http://en.wikipedia.org/wiki/JSON">JSON</a> object

  * {

  *   "firstName" : "Jaroslav",

  *   "lastName" : "Tulach",

  *   "addresses" : [

  *     { "street" : "Markoušovice", "town" : "Úpice" },

  *     { "street" : "V Parku", "town" : "Praha" },

  *   ]

  * }

  * </pre>

  * <p>

  * In case you are using <a target="_blank" href="http://knockoutjs.com/">Knockout technology</a>

  * for Java then you can associate such model object with surrounding HTML page by

  * calling: <code>p.applyBindings();</code>. The page can then use regular

  * <a target="_blank" href="http://knockoutjs.com/">Knockout</a> bindings to reference your

  * model and create dynamic connection between your model in Java and 

  * live DOM structure in the browser:

  * </p>

  * <pre>

  * Name: <span data-bind="text: fullName">

  * <div data-bind="foreach: addresses">

  *   Lives in <span data-bind="text: town"/>

  * </div>

  * </pre>

  * 

  * <h3>Access Raw <a target="_blank" href="http://knockoutjs.com/">Knockout</a> Observables</h3>

  * 

  * One can obtain <em>raw</em> JavaScript object representing the 

  * instance of {@link Model model class} (with appropriate

  * <a target="_blank" href="http://knockoutjs.com/">Knockout</a> <b>observable</b> properties)

  * by calling {@link Models#toRaw(java.lang.Object) Models.toRaw(p)}. For 

  * example here is a way to obtain the value of <code>fullName</code> property

  * (inefficient as it switches between Java and JavaScript back and forth, 

  * but functional and instructive) via a JavaScript call:

  * <pre>

  * {@link net.java.html.js.JavaScriptBody @JavaScriptBody}(args = "raw", javacall = true, body =

  *   "return raw.fullName();" // yes, the <a target="_blank" href="http://knockoutjs.com/">Knockout</a> property is a function

  * )

  * static native String jsFullName(Object raw);

  * // and later

  * Person p = ...;

  * String fullName = jsFullName({@link Models#toRaw(java.lang.Object) Models.toRaw(p)});

  * </pre>

  * The above shows how to read a value from <a target="_blank" href="http://knockoutjs.com/">Knockout</a>

  * observable. There is a way to change the value too:

  * One can pass a parameter to the property-function and then

  * it acts like a setter (of course not in the case of read only <code>fullName</code> property,

  * but for <code>firstName</code> or <code>lastName</code> the setter is

  * available). Everything mentioned in this paragraph applies only when 

  * <a target="_blank" href="http://knockoutjs.com/">Knockout</a> technology is active

  * other technologies may behave differently.

  * 

  * <h4>Copy to Plain JSON</h4>

  * There is a way to pass a value of a Java {@link Model model class} instance 

  * by copy and convert 

  * the {@link Model the whole object} into plain 

  * <a target="_blank" href="http://en.wikipedia.org/wiki/JSON">JSON</a>. Just

  * print it as a string and parse it in JavaScript:

  * <pre>

  * {@link net.java.html.js.JavaScriptBody @JavaScriptBody}(args = { "txt" }, body =

  *   "return JSON.parse(txt);"

  * )

  * private static native Object parseJSON(String txt);

  * 

  * public static Object toPlainJSON(Object model) {

  *   return parseJSON(model.toString());

  * }

  * </pre>

  * The newly returned instance is a one time copy of the original model and is no longer

  * connected to it. The copy based behavior is independent on any 

  * particular technology and should work

  * in <a target="_blank" href="http://knockoutjs.com/">Knockout</a> as well as other

  * technology implementations.

  * 

  * <h4>References</h4>

  * 

  * Visit an <a target="_blank" href="http://dew.apidesign.org/dew/#7510833">on-line demo</a>

  * to see a histogram driven by the {@link Model} annotation or try 

  * a little <a target="_blank" href="http://dew.apidesign.org/dew/#7263102">math test</a>.

  *

  * @author Jaroslav Tulach

  */

 @Retention(RetentionPolicy.SOURCE)

 @Target(ElementType.TYPE)

 public @interface Model {

     /** Name of the model class.

      * @return valid Java identifier to use as a name of the model class

      */

     String className();

     /** List of properties in the model.

      * @return array of property definitions

      */

     Property[] properties();

 }