jaroslav@9
|
1 |
/**
|
jaroslav@358
|
2 |
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
|
jaroslav@9
|
3 |
*
|
jaroslav@551
|
4 |
* Copyright 2013-2014 Oracle and/or its affiliates. All rights reserved.
|
jaroslav@9
|
5 |
*
|
jaroslav@358
|
6 |
* Oracle and Java are registered trademarks of Oracle and/or its affiliates.
|
jaroslav@358
|
7 |
* Other names may be trademarks of their respective owners.
|
jaroslav@9
|
8 |
*
|
jaroslav@358
|
9 |
* The contents of this file are subject to the terms of either the GNU
|
jaroslav@358
|
10 |
* General Public License Version 2 only ("GPL") or the Common
|
jaroslav@358
|
11 |
* Development and Distribution License("CDDL") (collectively, the
|
jaroslav@358
|
12 |
* "License"). You may not use this file except in compliance with the
|
jaroslav@358
|
13 |
* License. You can obtain a copy of the License at
|
jaroslav@358
|
14 |
* http://www.netbeans.org/cddl-gplv2.html
|
jaroslav@358
|
15 |
* or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
|
jaroslav@358
|
16 |
* specific language governing permissions and limitations under the
|
jaroslav@358
|
17 |
* License. When distributing the software, include this License Header
|
jaroslav@358
|
18 |
* Notice in each file and include the License file at
|
jaroslav@358
|
19 |
* nbbuild/licenses/CDDL-GPL-2-CP. Oracle designates this
|
jaroslav@358
|
20 |
* particular file as subject to the "Classpath" exception as provided
|
jaroslav@358
|
21 |
* by Oracle in the GPL Version 2 section of the License file that
|
jaroslav@358
|
22 |
* accompanied this code. If applicable, add the following below the
|
jaroslav@358
|
23 |
* License Header, with the fields enclosed by brackets [] replaced by
|
jaroslav@358
|
24 |
* your own identifying information:
|
jaroslav@358
|
25 |
* "Portions Copyrighted [year] [name of copyright owner]"
|
jaroslav@358
|
26 |
*
|
jaroslav@358
|
27 |
* Contributor(s):
|
jaroslav@358
|
28 |
*
|
jaroslav@358
|
29 |
* The Original Software is NetBeans. The Initial Developer of the Original
|
jaroslav@551
|
30 |
* Software is Oracle. Portions Copyright 2013-2014 Oracle. All Rights Reserved.
|
jaroslav@358
|
31 |
*
|
jaroslav@358
|
32 |
* If you wish your version of this file to be governed by only the CDDL
|
jaroslav@358
|
33 |
* or only the GPL Version 2, indicate your decision by adding
|
jaroslav@358
|
34 |
* "[Contributor] elects to include this software in this distribution
|
jaroslav@358
|
35 |
* under the [CDDL or GPL Version 2] license." If you do not indicate a
|
jaroslav@358
|
36 |
* single choice of license, a recipient has the option to distribute
|
jaroslav@358
|
37 |
* your version of this file under either the CDDL, the GPL Version 2 or
|
jaroslav@358
|
38 |
* to extend the choice of license to its licensees as provided above.
|
jaroslav@358
|
39 |
* However, if you add GPL Version 2 code and therefore, elected the GPL
|
jaroslav@358
|
40 |
* Version 2 license, then the option applies only if the new code is
|
jaroslav@358
|
41 |
* made subject to such option by the copyright holder.
|
jaroslav@9
|
42 |
*/
|
jtulach@838
|
43 |
package org.netbeans.html.json.spi;
|
jaroslav@6
|
44 |
|
jaroslav@575
|
45 |
import net.java.html.BrwsrCtx;
|
jaroslav@6
|
46 |
import net.java.html.json.Model;
|
jaroslav@308
|
47 |
import net.java.html.json.Models;
|
jaroslav@6
|
48 |
|
jaroslav@6
|
49 |
/** An implementation of a binding between model classes (see {@link Model})
|
jaroslav@6
|
50 |
* and particular technology like <a href="http://knockoutjs.com">knockout.js</a>
|
jaroslav@6
|
51 |
* in a browser window, etc.
|
jaroslav@6
|
52 |
*
|
jtulach@790
|
53 |
* @author Jaroslav Tulach
|
jaroslav@6
|
54 |
*/
|
jaroslav@6
|
55 |
public interface Technology<Data> {
|
jaroslav@6
|
56 |
/** Creates an object to wrap the provided model object. The model
|
jaroslav@6
|
57 |
* has previously been generated by annotation processor associated
|
jaroslav@6
|
58 |
* with {@link Model} annotation.
|
jaroslav@6
|
59 |
*
|
jaroslav@6
|
60 |
* @param model the model generated from {@link Model}
|
jaroslav@34
|
61 |
* @return internal object representing the model
|
jaroslav@6
|
62 |
*/
|
jaroslav@6
|
63 |
public Data wrapModel(Object model);
|
jaroslav@9
|
64 |
|
jaroslav@38
|
65 |
/** Converts an element potentially representing a model into the model.
|
jtulach@835
|
66 |
* @param <M> the type of the <code>modelClass</code>
|
jaroslav@38
|
67 |
* @param modelClass expected class to convert the data to
|
jaroslav@38
|
68 |
* @param data the current data provided from the browser
|
jaroslav@38
|
69 |
* @return the instance of modelClass somehow extracted from the data, may return <code>null</code>
|
jaroslav@38
|
70 |
*/
|
jaroslav@38
|
71 |
public <M> M toModel(Class<M> modelClass, Object data);
|
jaroslav@38
|
72 |
|
jaroslav@9
|
73 |
/** Binds a property between the model and the data as used by the technology.
|
jaroslav@9
|
74 |
*
|
jaroslav@9
|
75 |
* @param b the description of the requested binding
|
jaroslav@9
|
76 |
* @param model the original instance of the model
|
jaroslav@9
|
77 |
* @param data the data to bind with the model
|
jaroslav@9
|
78 |
*/
|
jaroslav@9
|
79 |
public void bind(PropertyBinding b, Object model, Data data);
|
jaroslav@6
|
80 |
|
jaroslav@6
|
81 |
/** Model for given data has changed its value. The technology is
|
jaroslav@6
|
82 |
* supposed to update its state (for example DOM nodes associated
|
jaroslav@6
|
83 |
* with the model). The update usually happens asynchronously.
|
jaroslav@6
|
84 |
*
|
jaroslav@6
|
85 |
* @param data technology's own representation of the model
|
jaroslav@6
|
86 |
* @param propertyName name of the model property that changed
|
jaroslav@6
|
87 |
*/
|
jaroslav@6
|
88 |
public void valueHasMutated(Data data, String propertyName);
|
jaroslav@11
|
89 |
|
jaroslav@11
|
90 |
public void expose(FunctionBinding fb, Object model, Data d);
|
jaroslav@14
|
91 |
|
jaroslav@14
|
92 |
/** Applies given data to current context (usually an HTML page).
|
jaroslav@14
|
93 |
* @param data the data to apply
|
jaroslav@14
|
94 |
*/
|
jaroslav@14
|
95 |
public void applyBindings(Data data);
|
jaroslav@23
|
96 |
|
jaroslav@23
|
97 |
/**
|
jaroslav@23
|
98 |
* Some technologies may require wrapping a Java array into a special
|
jaroslav@17
|
99 |
* object. In such case they may return it from this method.
|
jaroslav@23
|
100 |
*
|
jaroslav@17
|
101 |
* @param arr original array
|
jaroslav@17
|
102 |
* @return wrapped array
|
jaroslav@17
|
103 |
*/
|
jaroslav@17
|
104 |
public Object wrapArray(Object[] arr);
|
jaroslav@240
|
105 |
|
jaroslav@240
|
106 |
/**
|
jaroslav@240
|
107 |
* Run given runnable in a safe mode. If the runnable can be executed
|
jaroslav@240
|
108 |
* immediately, do it. If we need to switch to some other thread, do it
|
jaroslav@240
|
109 |
* and invoke r asynchronously immediately returning from the call to
|
jaroslav@240
|
110 |
* runSafe method.
|
jaroslav@240
|
111 |
*
|
jaroslav@240
|
112 |
* @param r the runnable to execute
|
jaroslav@575
|
113 |
* @deprecated Use {@link BrwsrCtx#execute(java.lang.Runnable)}
|
jaroslav@240
|
114 |
*/
|
jaroslav@575
|
115 |
@Deprecated
|
jaroslav@240
|
116 |
public void runSafe(Runnable r);
|
jaroslav@275
|
117 |
|
jaroslav@308
|
118 |
/** For certain rendering technologies it may be more efficient to register
|
jaroslav@308
|
119 |
* property and function bindings for one instance of the model at once,
|
jaroslav@308
|
120 |
* rather then doing it incrementally via
|
jtulach@838
|
121 |
* {@link Technology#expose(org.netbeans.html.json.spi.FunctionBinding, java.lang.Object, java.lang.Object) }
|
jaroslav@308
|
122 |
* and
|
jtulach@838
|
123 |
* {@link Technology#bind(org.netbeans.html.json.spi.PropertyBinding, java.lang.Object, java.lang.Object) }.
|
jtulach@838
|
124 |
* In such case implement the {@link #wrapModel(java.lang.Object, org.netbeans.html.json.spi.PropertyBinding[], org.netbeans.html.json.spi.FunctionBinding[]) }
|
jaroslav@308
|
125 |
* method of this interface and it will be called instead of the
|
jaroslav@308
|
126 |
* previous two ones.
|
jaroslav@308
|
127 |
*
|
jaroslav@534
|
128 |
* @since 0.6
|
jaroslav@308
|
129 |
*/
|
jaroslav@275
|
130 |
public static interface BatchInit<D> extends Technology<D> {
|
jaroslav@308
|
131 |
/** Wrap the given model into redering technology appropriate object
|
jaroslav@308
|
132 |
* <code>D</code> and expose given properties and functions on it.
|
jaroslav@308
|
133 |
*
|
jaroslav@308
|
134 |
* @param model the {@link Models#isModel(java.lang.Class) model} in Java
|
jaroslav@308
|
135 |
* @param propArr array of property bindings to expose
|
jaroslav@308
|
136 |
* @param funcArr array of functions to expose
|
jaroslav@308
|
137 |
* @return appropriate wrapper around the model
|
jaroslav@308
|
138 |
*/
|
jaroslav@275
|
139 |
public D wrapModel(Object model, PropertyBinding[] propArr, FunctionBinding[] funcArr);
|
jaroslav@275
|
140 |
}
|
jaroslav@567
|
141 |
|
jaroslav@567
|
142 |
/** Some technologies are more effective when number of calls between
|
jaroslav@567
|
143 |
* Java and JavaScript is limited - to do that when a value of property
|
jaroslav@567
|
144 |
* is changed they should implement this additional interface.
|
jaroslav@567
|
145 |
*
|
jaroslav@567
|
146 |
* @param <D> internal type of the technology
|
jaroslav@567
|
147 |
* @since 0.7.6
|
jaroslav@567
|
148 |
*/
|
jaroslav@567
|
149 |
public static interface ValueMutated<D> extends Technology<D> {
|
jaroslav@567
|
150 |
/** Model for given data has changed its value. The technology is
|
jaroslav@567
|
151 |
* supposed to update its state (for example DOM nodes associated
|
jaroslav@567
|
152 |
* with the model). The update usually happens asynchronously.
|
jaroslav@567
|
153 |
* <p>
|
jaroslav@567
|
154 |
* If both <code>oldValue</code> and <code>newValue</code> are
|
jaroslav@567
|
155 |
* <code>null</code> then the real value of the technology is
|
jaroslav@567
|
156 |
* not known.
|
jaroslav@567
|
157 |
* <p>
|
jaroslav@567
|
158 |
* If this method is present, then it is called instead of
|
jaroslav@567
|
159 |
* old, plain {@link #valueHasMutated(java.lang.Object, java.lang.String)}
|
jaroslav@567
|
160 |
* which is never called by the infrastructure then.
|
jaroslav@567
|
161 |
*
|
jaroslav@567
|
162 |
* @param data technology's own representation of the model
|
jaroslav@567
|
163 |
* @param propertyName name of the model property that changed
|
jaroslav@567
|
164 |
* @param oldValue provides previous value of the property
|
jaroslav@567
|
165 |
* @param newValue provides new value of the property
|
jaroslav@567
|
166 |
*/
|
jaroslav@567
|
167 |
public void valueHasMutated(D data, String propertyName, Object oldValue, Object newValue);
|
jaroslav@567
|
168 |
}
|
jaroslav@6
|
169 |
}
|