org.netbeans.html.json.spi

Class Proto

java.lang.Object

org.netbeans.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

Modifier and Type	Method and Description
void	accessProperty(String propName) A property on this proto object is about to be accessed.
void	acquireLock() Acquires global lock to compute a derived property on this proto object.
void	acquireLock(String propName) Acquires global lock to compute a derived property on this proto object.
void	applyBindings() Initializes the associated model in the current context.
void	applyBindings(String id) Initializes the associated model to the specified element's subtree.
<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.
void	loadJSON(int index, String urlBefore, String urlAfter, String method, Object data, Object... params) Initializes asynchronous JSON connection to specified URL.
void	loadJSONWithHeaders(int index, String headers, String urlBefore, String urlAfter, String method, Object data, Object... params) 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(int index, Object... args) Invokes the specified function index in the context of the browser.
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	valueHasMutated(String propName, Object oldValue, Object newValue) Whenever model changes a propertyit should notify the associated technology.
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

Acquires global lock to compute a derived property on this proto object. This proto object must not be locked yet. No dependency tracking is performed.

Throws:

IllegalStateException - if already locked

acquireLock

public void acquireLock(String propName)
                 throws IllegalStateException

Acquires global lock to compute a derived property on this proto object. This proto object must not be locked yet. The name of the property is used to track dependencies on own properties of other proto objects - when they are changed, this property is changed too.

Parameters:

propName - name of property we are about to compute

Throws:

IllegalStateException - thrown when there is a cyclic call is detected

Since:

0.9

accessProperty

public void accessProperty(String propName)
                    throws IllegalStateException

A property on this proto object is about to be accessed. Verifies whether this proto object is accessible - e.g. it has not been locked yet. If everything is OK, the propName is recorded in the chain of dependencies tracked by Proto.acquireLock(java.lang.String) and watched by Proto.valueHasMutated(java.lang.String).

Parameters:

propName - name of the property that is requested

Throws:

IllegalStateException - if the model is locked

Since:

0.9

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. Since 0.8.3: This method may be called by any thread - it reschedules its actual execution into appropriate one by using BrwsrCtx.execute(java.lang.Runnable).

Parameters:

propName - name of the changed property

valueHasMutated

public void valueHasMutated(String propName,
                            Object oldValue,
                            Object newValue)

Whenever model changes a propertyit should notify the associated technology. Either by calling this method (if the new value is known and different to the old one) or via (slightly ineffective) Proto.valueHasMutated(java.lang.String) method. Since 0.8.3: This method may be called by any thread - it reschedules its actual execution into appropriate one by using BrwsrCtx.execute(java.lang.Runnable).

Parameters:

propName - name of the changed property

oldValue - provides previous value of the property

newValue - provides new value of the property

Since:

0.7.6

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.

applyBindings

public void applyBindings(String id)

Initializes the associated model to the specified element's subtree. The technology is taken from the current context and in case of knockout.js applies given bindings of the current model to the element of the page with 'id' attribute set to the specified id value.

Parameters:

id - the id of element to apply the binding to

Since:

1.1

See Also:

Technology.ApplyId

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

runInBrowser

public void runInBrowser(int index,
                         Object... args)

Invokes the specified function index in the context of the browser. If the caller is already on the right thread, the index-th function is invoked immediately and synchronously. Otherwise the method returns immediately and the function is invoked later.

Parameters:

index - the index of the function as will be passed to Proto.Type.call(java.lang.Object, int, java.lang.Object, java.lang.Object) method

args - array of arguments that will be passed as data argument of the call method.

Since:

0.7.6

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. Delegates to Proto.loadJSON(int, java.lang.String, java.lang.String, java.lang.String, java.lang.Object, java.lang.Object...) with no extra parameters.

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

loadJSON

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

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

params - extra params to pass back when calling Proto.Type.onMessage(java.lang.Object, int, int, java.lang.Object, java.lang.Object[])

Since:

0.8.1

loadJSONWithHeaders

public void loadJSONWithHeaders(int index,
                                String headers,
                                String urlBefore,
                                String urlAfter,
                                String method,
                                Object data,
                                Object... params)

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).

headers - headers to use for the request or null to use default ones

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

params - extra params to pass back when calling Proto.Type.onMessage(java.lang.Object, int, int, java.lang.Object, java.lang.Object[])

Since:

1.2

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 Proto.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). If the value is Integer.MIN_VALUE, then the list is not fully Property.mutable() and throws UnsupportedOperationException on such attempts.

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