net.java.html.json

Annotation Type OnReceive

@Retention(value=SOURCE)
@Target(value=METHOD)
public @interface OnReceive

Static methods in classes annotated by Model can be marked by this annotation to establish a JSON communication point. The associated model class then gets new method to invoke a network connection. Example follows:

 @Model(className="MyModel", properties={
   @Property(name = "people", type=Person.class, array=true)
 })
 class MyModelImpl {
   @Model(className="Person", properties={
     @Property(name = "firstName", type=String.class),
     @Property(name = "lastName", type=String.class)
   })
   static class PersonImpl {
     @ComputedProperty
     static String fullName(String firstName, String lastName) {
       return firstName + " " + lastName;
     }
   }
 
   @OnReceive(url = "{protocol}://your.server.com/person/{name}")
   static void getANewPerson(MyModel m, Person p) {
     alert("Adding " + p.getFullName() + '!');
     m.getPeople().add(p);
   }
 
   // the above will generate method getANewPerson in class MyModel.
   // with protocol and name arguments
   // which asynchronously contacts the server and in case of success calls
   // your @OnReceive with parsed in data
 
   @Function
   static void requestSmith(MyModel m) {
     m.getANewPerson("http", "Smith");
   }
 }
 

When the server returns { "firstName" : "John", "lastName" : "Smith" } the browser will show alert message Adding John Smith!.

One can use this method to communicate with the server via WebSocket protocol since version 0.6. Read the tutorial to see how.

Since:

0.3

Author:

Jaroslav Tulach

Required Element Summary

Required Elements

Modifier and Type	Required Element and Description
String	url The URL to connect to.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
Class<?>	data The model class to be send to the server as JSON data.
String	jsonp Support for JSONP requires a callback from the server generated page to a function defined in the system.
String	method The HTTP transfer method to use.
String	onError Name of a method in this class which should be called in case of an error.

Element Detail

url

public abstract String url

The URL to connect to. Can contain variable names surrounded by '{' and '}'. Those parameters will then become variables of the associated method.

Returns:

the (possibly parametrized) url to connect to

jsonp

public abstract String jsonp

Support for JSONP requires a callback from the server generated page to a function defined in the system. The name of such function is usually specified as a property (of possibly different names). By defining the jsonp attribute one turns on the JSONP transmission and specifies the name of the property. The property should also be used in the url() attribute on appropriate place.

Returns:

name of a property to carry the name of JSONP callback function.

Default:

""

data

public abstract Class<?> data

The model class to be send to the server as JSON data. By default no data are sent. However certain transport methods (like "PUT" and "POST") require the data to be specified.

Returns:

name of a class generated using @Model annotation

Since:

0.3

Default:

java.lang.Object.class

method

public abstract String method

The HTTP transfer method to use. Defaults to "GET". Other typical methods include "HEAD", "DELETE", "POST", "PUT". The last two mentioned methods require data() to be specified.

When JSONP transport is requested, the method has to be "GET".

Since version 0.5 one can specify "WebSocket" as the communication method.

Returns:

name of the HTTP transfer method

Since:

0.3

Default:

"GET"

onError

public abstract String onError

Name of a method in this class which should be called in case of an error. The method has to be non-private and take one model and one Exception parameter. If this method is not specified, the exception is just printed to console.

Returns:

name of method in this class

Since:

0.5

Default:

""