org.apidesign.html.json.spi

Class Proto

java.lang.Object

org.apidesign.html.json.spi.Proto

public final class Proto
extends Object

Object associated with one instance of a model generated by the Model annotation. Contains methods the generated class can use to communicate with behind the scene associated Technology. Each Proto object is associated with singletonizer-like interface Proto.Type which provides the associated Technology the necessary information about the generated Model class.

Since:

0.7

Author:

Jaroslav Tulach

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Proto.Type<Model> Functionality used by the code generated by annotation processor for the Model annotation.

Method Summary

Methods

Modifier and Type	Method and Description
void	acquireLock() Before doing modification of the model properties, the generated code enters write lock by calling this method.
void	applyBindings() Initializes the associated model in the current context.
<T> void	cloneList(Collection<T> to, BrwsrCtx ctx, Collection<T> from) Copies content of one collection to another, re-assigning all its elements from their current context to the new ctx.
<T> List<T>	createList(String propName, int onChange, String... dependingProps) Creates new JSON like observable list.
void	extract(Object json, String[] props, Object[] values) Takes an object representing JSON result and extract some of its properties.
BrwsrCtx	getContext() Browser context this proto object and its associated model are operating-in.
void	initTo(Collection<?> to, Object array) Initializes the provided collection with a content of the array.
void	loadJSON(int index, String urlBefore, String urlAfter, String method, Object data) Initializes asynchronous JSON connection to specified URL.
<T> T	read(Class<T> modelClass, Object data) Converts raw JSON data into a Java Model class.
void	releaseLock() When modifications are over, the model is switched into unlocked state by calling this method.
void	runInBrowser(Runnable run) Invokes the provided runnable in the context of the browser.
<T> T	toModel(Class<T> type, Object data) Converts raw JSON data into a Model class representation.
Number	toNumber(Object data, String propName) Converts raw data (one of its properties) to a number representation.
String	toString(Object data, String propName) Converts raw data (one of its properties) to string representation.
void	valueHasMutated(String propName) Whenever model changes a property.
void	verifyUnlocked() Verifies the model is not locked otherwise throws an exception.
Object	wsOpen(int index, String url, Object data) Opens new WebSocket connection to the specified URL.
void	wsSend(Object webSocket, String url, Object data) Sends a message to existing socket.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getContext

public BrwsrCtx getContext()

Browser context this proto object and its associated model are operating-in.

Returns:

the associated context

acquireLock

public void acquireLock()
                 throws IllegalStateException

Before doing modification of the model properties, the generated code enters write lock by calling this method.

Throws:

IllegalStateException - if already locked

verifyUnlocked

public void verifyUnlocked()
                    throws IllegalStateException

Verifies the model is not locked otherwise throws an exception.

Throws:

IllegalStateException - if the model is locked

releaseLock

public void releaseLock()

When modifications are over, the model is switched into unlocked state by calling this method.

valueHasMutated

public void valueHasMutated(String propName)

Whenever model changes a property. It should notify the associated technology by calling this method.

Parameters:

propName - name of the changed property

applyBindings

public void applyBindings()

Initializes the associated model in the current context. In case of knockout.js technology, applies given bindings of the current model to the body element of the page.

runInBrowser

public void runInBrowser(Runnable run)

Invokes the provided runnable in the context of the browser. If the caller is already on the right thread, the run.run() is invoked immediately and synchronously. Otherwise the method returns immediately and the run() method is performed later

Parameters:

run - the action to execute

initTo

public void initTo(Collection<?> to,
          Object array)

Initializes the provided collection with a content of the array. The initialization can only be done soon after the the collection is created, otherwise an exception is throw

Parameters:

to - the collection to initialize (assumed to be empty)

array - the array to add to the collection

Throws:

IllegalStateException - if the system has already been initialized

extract

public void extract(Object json,
           String[] props,
           Object[] values)

Takes an object representing JSON result and extract some of its properties. It is assumed that the props and values arrays have the same length.

Parameters:

json - the JSON object (actual type depends on the associated Technology)

props - list of properties to extract

values - array that will be filled with extracted values

read

public <T> T read(Class<T> modelClass,
         Object data)

Converts raw JSON data into a Java Model class.

Type Parameters:

T - type of the model class

Parameters:

modelClass - the type of the class to create

data - the raw JSON data

Returns:

newly created instance of the model class

loadJSON

public void loadJSON(int index,
            String urlBefore,
            String urlAfter,
            String method,
            Object data)

Initializes asynchronous JSON connection to specified URL. The method returns immediately and later does callback later.

Parameters:

index - the callback index to be used when a reply is received to call Proto.Type.onMessage(java.lang.Object, int, int, java.lang.Object).

urlBefore - the part of the URL before JSON-P callback parameter

urlAfter - the rest of the URL or null if no JSON-P is used

method - method to use for connection to the server

data - string, number or a Model generated class to send to the server when doing a query

wsOpen

public Object wsOpen(int index,
            String url,
            Object data)

Opens new WebSocket connection to the specified URL.

Parameters:

index - the index to use later during callbacks to Proto.Type.onMessage(java.lang.Object, int, int, java.lang.Object)

url - the ws:// or wss:// URL to connect to

data - data to send to server (usually null)

Returns:

returns a non-null object representing the socket which can be used when calling wsSend(java.lang.Object, java.lang.String, java.lang.Object)

wsSend

public void wsSend(Object webSocket,
          String url,
          Object data)

Sends a message to existing socket.

Parameters:

webSocket - the socket to send message to

url - the ws:// or wss:// URL to connect to, preferably the same as the one used when the socket was opened

data - the data to send or null if the socket is supposed to be closed

toString

public String toString(Object data,
              String propName)

Converts raw data (one of its properties) to string representation.

Parameters:

data - the object

propName - the name of object property or null if the whole object should be converted

Returns:

the string representation of the object or its property

toNumber

public Number toNumber(Object data,
              String propName)

Converts raw data (one of its properties) to a number representation.

Parameters:

data - the object

propName - the name of object property or null if the whole object should be converted

Returns:

the number representation of the object or its property

toModel

public <T> T toModel(Class<T> type,
            Object data)

Converts raw JSON data into a Model class representation.

Type Parameters:

T - type of the model to create

Parameters:

type - class of the model to create

data - raw JSON data (depends on associated Technology)

Returns:

new instances of the model class filled with values from the data object

createList

public <T> List<T> createList(String propName,
                     int onChange,
                     String... dependingProps)

Creates new JSON like observable list.

Type Parameters:

T - the type of the list elements

Parameters:

propName - name of a property this list is associated with

onChange - index of the property to use when the list is modified during callback to Proto.Type.onChange(java.lang.Object, int)

dependingProps - the array of derived properties that depend on the value of the list

Returns:

new, empty list associated with this proto-object and its model

cloneList

public <T> void cloneList(Collection<T> to,
                 BrwsrCtx ctx,
                 Collection<T> from)

Copies content of one collection to another, re-assigning all its elements from their current context to the new ctx.

Type Parameters:

T - type of the collections

Parameters:

to - the target collection to be filled with cloned values

ctx - context for the new collection

from - original collection with its data