Deep checking of @ComputedProperties is now default if one depends on another model class
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
4 * Copyright 2013-2014 Oracle and/or its affiliates. All rights reserved.
6 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.
7 * Other names may be trademarks of their respective owners.
9 * The contents of this file are subject to the terms of either the GNU
10 * General Public License Version 2 only ("GPL") or the Common
11 * Development and Distribution License("CDDL") (collectively, the
12 * "License"). You may not use this file except in compliance with the
13 * License. You can obtain a copy of the License at
14 * http://www.netbeans.org/cddl-gplv2.html
15 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
16 * specific language governing permissions and limitations under the
17 * License. When distributing the software, include this License Header
18 * Notice in each file and include the License file at
19 * nbbuild/licenses/CDDL-GPL-2-CP. Oracle designates this
20 * particular file as subject to the "Classpath" exception as provided
21 * by Oracle in the GPL Version 2 section of the License file that
22 * accompanied this code. If applicable, add the following below the
23 * License Header, with the fields enclosed by brackets [] replaced by
24 * your own identifying information:
25 * "Portions Copyrighted [year] [name of copyright owner]"
29 * The Original Software is NetBeans. The Initial Developer of the Original
30 * Software is Oracle. Portions Copyright 2013-2014 Oracle. All Rights Reserved.
32 * If you wish your version of this file to be governed by only the CDDL
33 * or only the GPL Version 2, indicate your decision by adding
34 * "[Contributor] elects to include this software in this distribution
35 * under the [CDDL or GPL Version 2] license." If you do not indicate a
36 * single choice of license, a recipient has the option to distribute
37 * your version of this file under either the CDDL, the GPL Version 2 or
38 * to extend the choice of license to its licensees as provided above.
39 * However, if you add GPL Version 2 code and therefore, elected the GPL
40 * Version 2 license, then the option applies only if the new code is
41 * made subject to such option by the copyright holder.
43 package net.java.html.json;
45 import java.lang.annotation.ElementType;
46 import java.lang.annotation.Retention;
47 import java.lang.annotation.RetentionPolicy;
48 import java.lang.annotation.Target;
50 import java.util.List;
52 /** Defines a model class that represents a single
53 * <a href="http://en.wikipedia.org/wiki/JSON">JSON</a>-like object
54 * named {@link #className()}. The generated class contains
55 * getters and setters for properties defined via {@link #properties()} and
56 * getters for other, derived properties defined by annotating methods
57 * of this class by {@link ComputedProperty}. Each property
58 * can be of primitive type, an {@link Enum enum type} or (in order to create
59 * nested <a href="http://en.wikipedia.org/wiki/JSON">JSON</a> structure)
60 * of another {@link Model class generated by @Model} annotation. Each property
61 * can either represent a single value or be an array of its values.
63 * The {@link #className() generated class}'s <code>toString</code> method
64 * converts the state of the object into
65 * <a href="http://en.wikipedia.org/wiki/JSON">JSON</a> format. One can
66 * use {@link Models#parse(net.java.html.BrwsrCtx, java.lang.Class, java.io.InputStream)}
67 * method to read the JSON text stored in a file or other stream back into the Java model.
68 * One can also use {@link OnReceive @OnReceive} annotation to read the model
69 * asynchronously from a {@link URL}.
71 * An example where one defines class <code>Person</code> with four
72 * properties (<code>firstName</code>, <code>lastName</code>, array of <code>addresses</code> and
73 * <code>fullName</code>) follows:
75 * {@link Model @Model}(className="Person", properties={
76 * {@link Property @Property}(name = "firstName", type=String.class),
77 * {@link Property @Property}(name = "lastName", type=String.class)
78 * {@link Property @Property}(name = "addresses", type=Address.class, array = true)
80 * static class PersonModel {
81 * {@link ComputedProperty @ComputedProperty}
82 * static String fullName(String firstName, String lastName) {
83 * return firstName + " " + lastName;
86 * {@link ComputedProperty @ComputedProperty}
87 * static String mainAddress({@link List List<Address>} addresses) {
88 * for (Address a : addresses) {
89 * return a.getStreet() + " " + a.getTown();
91 * return "No address";
94 * {@link Model @Model}(className="Address", properties={
95 * {@link Property @Property}(name = "street", type=String.class),
96 * {@link Property @Property}(name = "town", type=String.class)
98 * static class AddressModel {
102 * The generated model class has a default constructor, and also <em>quick
103 * instantiation</em> constructor that accepts all non-array properties
104 * (in the order used in the {@link #properties()} attribute) and vararg list
105 * for the first array property (if any). One can thus use following code
106 * to create an instance of the Person and Address classes:
109 * Person p = new Person("Jaroslav", "Tulach",
110 * new Address("Markoušovice", "Úpice"),
111 * new Address("V Parku", "Praha")
113 * // p.toString() then returns equivalent of following <a href="http://en.wikipedia.org/wiki/JSON">JSON</a> object
115 * "firstName" : "Jaroslav",
116 * "lastName" : "Tulach",
118 * { "street" : "Markoušovice", "town" : "Úpice" },
119 * { "street" : "V Parku", "town" : "Praha" },
124 * In case you are using <a href="http://knockoutjs.com/">Knockout technology</a>
125 * for Java then you can associate such model object with surrounding HTML page by
126 * calling: <code>p.applyBindings();</code>. The page can then use regular
127 * <a href="http://knockoutjs.com/">Knockout</a> bindings to reference your
128 * model and create dynamic connection between your model in Java and
129 * live DOM structure in the browser:
131 * Name: <span data-bind="text: fullName">
132 * <div data-bind="foreach: addresses">
133 * Lives in <span data-bind="text: town"/>
137 * Visit an <a target="_blank" href="http://dew.apidesign.org/dew/#7510833">on-line demo</a>
138 * to see a histogram driven by the {@link Model} annotation or try
139 * a little <a target="_blank" href="http://dew.apidesign.org/dew/#7263102">math test</a>.
141 * @author Jaroslav Tulach
143 @Retention(RetentionPolicy.SOURCE)
144 @Target(ElementType.TYPE)
145 public @interface Model {
146 /** Name of the model class */
148 /** List of properties in the model.
150 Property[] properties();