2 * Back 2 Browser Bytecode Translator
3 * Copyright (C) 2012 Jaroslav Tulach <jaroslav.tulach@apidesign.org>
5 * This program is free software: you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation, version 2 of the License.
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
14 * You should have received a copy of the GNU General Public License
15 * along with this program. Look for COPYING file in the top folder.
16 * If not, see http://opensource.org/licenses/GPL-2.0.
18 package org.apidesign.bck2brwsr.htmlpage.api;
20 import java.lang.annotation.ElementType;
21 import java.lang.annotation.Retention;
22 import java.lang.annotation.RetentionPolicy;
23 import java.lang.annotation.Target;
25 /** Static methods in classes annotated by {@link Page}
26 * can be marked by this annotation to establish a
27 * <a href="http://en.wikipedia.org/wiki/JSON">JSON</a>
28 * communication point.
29 * The associated model page then gets new method to invoke a network
30 * connection. Example follows:
33 * {@link Page @Page}(className="MyModel", xhtml="page.html", properties={
34 * {@link Property @Property}(name = "people", type=Person.class, array=true)
37 * {@link Model @Model}(className="Person", properties={
38 * {@link Property @Property}(name = "firstName", type=String.class),
39 * {@link Property @Property}(name = "lastName", type=String.class)
41 * static class PersonImpl {
42 * {@link ComputedProperty @ComputedProperty}
43 * static String fullName(String firstName, String lastName) {
44 * return firstName + " " + lastName;
48 * {@link OnReceive @OnReceive}(url = "{protocol}://your.server.com/person/{name}")
49 * static void getANewPerson(MyModel m, Person p) {
50 * {@link Element#alert Element.alert}("Adding " + p.getFullName() + '!');
51 * m.getPeople().add(p);
54 * // the above will generate method <code>getANewPerson</code> in class <code>MyModel</code>.
55 * // with <code>protocol</code> and <code>name</code> arguments
56 * // which asynchronously contacts the server and in case of success calls
57 * // your {@link OnReceive @OnReceive} with parsed in data
59 * {@link On @On}(event={@link OnEvent#CLICK OnEvent.CLICK}, id="rqst")
60 * static void requestSmith(MyModel m) {
61 * m.getANewPerson("http", "Smith");
65 * When the server returns <code>{ "firstName" : "John", "lastName" : "Smith" }</code>
66 * the browser will show alert message <em>Adding John Smith!</em>.
68 * @author Jaroslav Tulach <jtulach@netbeans.org>
71 @Retention(RetentionPolicy.SOURCE)
72 @Target(ElementType.METHOD)
73 public @interface OnReceive {
74 /** The URL to connect to. Can contain variable names surrounded by '{' and '}'.
75 * Those parameters will then become variables of the associated method.
77 * @return the (possibly parametrized) url to connect to
81 /** Support for <a href="http://en.wikipedia.org/wiki/JSONP">JSONP</a> requires
82 * a callback from the server generated page to a function defined in the
83 * system. The name of such function is usually specified as a property
84 * (of possibly different names). By defining the <code>jsonp</code> attribute
85 * one turns on the <a href="http://en.wikipedia.org/wiki/JSONP">JSONP</a>
86 * transmission and specifies the name of the property. The property should
87 * also be used in the {@link #url()} attribute on appropriate place.
89 * @return name of a property to carry the name of <a href="http://en.wikipedia.org/wiki/JSONP">JSONP</a>
92 String jsonp() default "";