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