1.1 --- a/javaquery/api/src/main/java/org/apidesign/bck2brwsr/htmlpage/api/OnReceive.java	Mon Apr 08 16:51:30 2013 +0200
     1.2 +++ b/javaquery/api/src/main/java/org/apidesign/bck2brwsr/htmlpage/api/OnReceive.java	Wed Apr 10 12:19:32 2013 +0200
     1.3 @@ -22,12 +22,51 @@
     1.4  import java.lang.annotation.RetentionPolicy;
     1.5  import java.lang.annotation.Target;
     1.6  
     1.7 -/** Static methods in classes annotated by {@link Model} or {@link Page}
     1.8 - * can be marked by this annotation establish a JSON communication point.
     1.9 +/** Static methods in classes annotated by {@link Page}
    1.10 + * can be marked by this annotation to establish a 
    1.11 + * <a href="http://en.wikipedia.org/wiki/JSON">JSON</a>
    1.12 + * communication point.
    1.13   * The associated model page then gets new method to invoke a network
    1.14 - * connection 
    1.15 + * connection. Example follows:
    1.16 + * 
    1.17 + * <pre>
    1.18 + * {@link Page @Page}(className="MyModel", xhtml="page.html", properties={
    1.19 + *   {@link Property @Property}(name = "people", type=Person.class, array=true)
    1.20 + * })
    1.21 + * class MyModelImpl {
    1.22 + *   {@link Model @Model}(className="Person", properties={
    1.23 + *     {@link Property @Property}(name = "firstName", type=String.class),
    1.24 + *     {@link Property @Property}(name = "lastName", type=String.class)
    1.25 + *   })
    1.26 + *   static class PersonImpl {
    1.27 + *     {@link ComputedProperty @ComputedProperty}
    1.28 + *     static String fullName(String firstName, String lastName) {
    1.29 + *       return firstName + " " + lastName;
    1.30 + *     }
    1.31 + *   }
    1.32 + * 
    1.33 + *   {@link OnReceive @OnReceive}(url = "{protocol}://your.server.com/person/{name}")
    1.34 + *   static void getANewPerson(MyModel m, Person p) {
    1.35 + *     {@link Element#alert Element.alert}("Adding " + p.getFullName() + '!');
    1.36 + *     m.getPeople().add(p);
    1.37 + *   }
    1.38 + * 
    1.39 + *   // the above will generate method <code>getANewPerson</code> in class <code>MyModel</code>.
    1.40 + *   // with <code>protocol</code> and <code>name</code> arguments
    1.41 + *   // which asynchronously contacts the server and in case of success calls
    1.42 + *   // your {@link OnReceive @OnReceive} with parsed in data
    1.43 + * 
    1.44 + *   {@link On @On}(event={@link OnEvent#CLICK OnEvent.CLICK}, id="rqst")
    1.45 + *   static void requestSmith(MyModel m) {
    1.46 + *     m.getANewPerson("http", "Smith");
    1.47 + *   }
    1.48 + * }
    1.49 + * </pre>
    1.50 + * When the server returns <code>{ "firstName" : "John", "lastName" : "Smith" }</code>
    1.51 + * the browser will show alert message <em>Adding John Smith!</em>.
    1.52   * 
    1.53   * @author Jaroslav Tulach <jtulach@netbeans.org>
    1.54 + * @since 0.6
    1.55   */
    1.56  @Retention(RetentionPolicy.SOURCE)
    1.57  @Target(ElementType.METHOD)