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 first argument should be the associated Model class. The second argument can be another class generated by Model annotation, or array of such classes or (since 0.8.1 version) a List of such classes. The associated model class then gets new method to invoke a network connection asynchronously. 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) {
     System.out.println("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 system will print a message Adding John Smith!. It is not necessary to fully describe the server message - enumerate only the fields in the response you are interested in. The others will be discarded. So, if the server { "firstName" : "John", "lastName" : "Smith", "age" : 33 } the above code will behave the same (e.g. ignore the age value).

One can use this method to communicate with the server via WebSocket protocol since version 0.6. Read the tutorial to see how. The method shall be non-private and unless instance mode is on also static.

Visit an on-line demo to see REST access via OnReceive annotation.

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[]	headers Specifies HTTP request headers.
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 names will then become parameters of the associated method.

Returns:

the (possibly parametrized) url to connect to

headers

public abstract String[] headers

Specifies HTTP request headers. Array of header lines can contain variable names surrounded by '{' and '}'. Those names will then become parameters of the associated method (in addition to those added by url() specification) and can only be used with plain JSON(P) requests. Headers are currently not supported by the WebSockets protocol. A sample follows. If you want to transmit X-Birthday header, you can do it like this:

 @OnReceive(url="http://your.server.org", headers = {
   "X-Birthday: {dayOfBirth}"
 })
 static void knowingTheBirth(YourModel model) {
   // handle the reply
 }

a method knowingTheBirth is generated in YourModel class with the dayOfBirth argument which can be called like this:

 yourModel.knowingTheBirth("10. 12. 1973");
 

Returns:

array of header lines - each line should be plain text with a header name, followed by ":" and value usually specified as '{' and '}' surrounded variable. The line shouldn't contain newline or other control characters

Since:

1.2

Default:

{}

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:

""