1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/json/src/main/java/org/netbeans/html/json/spi/Technology.java Tue Aug 26 18:13:30 2014 +0200
1.3 @@ -0,0 +1,169 @@
1.4 +/**
1.5 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
1.6 + *
1.7 + * Copyright 2013-2014 Oracle and/or its affiliates. All rights reserved.
1.8 + *
1.9 + * Oracle and Java are registered trademarks of Oracle and/or its affiliates.
1.10 + * Other names may be trademarks of their respective owners.
1.11 + *
1.12 + * The contents of this file are subject to the terms of either the GNU
1.13 + * General Public License Version 2 only ("GPL") or the Common
1.14 + * Development and Distribution License("CDDL") (collectively, the
1.15 + * "License"). You may not use this file except in compliance with the
1.16 + * License. You can obtain a copy of the License at
1.17 + * http://www.netbeans.org/cddl-gplv2.html
1.18 + * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
1.19 + * specific language governing permissions and limitations under the
1.20 + * License. When distributing the software, include this License Header
1.21 + * Notice in each file and include the License file at
1.22 + * nbbuild/licenses/CDDL-GPL-2-CP. Oracle designates this
1.23 + * particular file as subject to the "Classpath" exception as provided
1.24 + * by Oracle in the GPL Version 2 section of the License file that
1.25 + * accompanied this code. If applicable, add the following below the
1.26 + * License Header, with the fields enclosed by brackets [] replaced by
1.27 + * your own identifying information:
1.28 + * "Portions Copyrighted [year] [name of copyright owner]"
1.29 + *
1.30 + * Contributor(s):
1.31 + *
1.32 + * The Original Software is NetBeans. The Initial Developer of the Original
1.33 + * Software is Oracle. Portions Copyright 2013-2014 Oracle. All Rights Reserved.
1.34 + *
1.35 + * If you wish your version of this file to be governed by only the CDDL
1.36 + * or only the GPL Version 2, indicate your decision by adding
1.37 + * "[Contributor] elects to include this software in this distribution
1.38 + * under the [CDDL or GPL Version 2] license." If you do not indicate a
1.39 + * single choice of license, a recipient has the option to distribute
1.40 + * your version of this file under either the CDDL, the GPL Version 2 or
1.41 + * to extend the choice of license to its licensees as provided above.
1.42 + * However, if you add GPL Version 2 code and therefore, elected the GPL
1.43 + * Version 2 license, then the option applies only if the new code is
1.44 + * made subject to such option by the copyright holder.
1.45 + */
1.46 +package org.netbeans.html.json.spi;
1.47 +
1.48 +import net.java.html.BrwsrCtx;
1.49 +import net.java.html.json.Model;
1.50 +import net.java.html.json.Models;
1.51 +
1.52 +/** An implementation of a binding between model classes (see {@link Model})
1.53 + * and particular technology like <a href="http://knockoutjs.com">knockout.js</a>
1.54 + * in a browser window, etc.
1.55 + *
1.56 + * @author Jaroslav Tulach
1.57 + */
1.58 +public interface Technology<Data> {
1.59 + /** Creates an object to wrap the provided model object. The model
1.60 + * has previously been generated by annotation processor associated
1.61 + * with {@link Model} annotation.
1.62 + *
1.63 + * @param model the model generated from {@link Model}
1.64 + * @return internal object representing the model
1.65 + */
1.66 + public Data wrapModel(Object model);
1.67 +
1.68 + /** Converts an element potentially representing a model into the model.
1.69 + * @param <M> the type of the <code>modelClass</code>
1.70 + * @param modelClass expected class to convert the data to
1.71 + * @param data the current data provided from the browser
1.72 + * @return the instance of modelClass somehow extracted from the data, may return <code>null</code>
1.73 + */
1.74 + public <M> M toModel(Class<M> modelClass, Object data);
1.75 +
1.76 + /** Binds a property between the model and the data as used by the technology.
1.77 + *
1.78 + * @param b the description of the requested binding
1.79 + * @param model the original instance of the model
1.80 + * @param data the data to bind with the model
1.81 + */
1.82 + public void bind(PropertyBinding b, Object model, Data data);
1.83 +
1.84 + /** Model for given data has changed its value. The technology is
1.85 + * supposed to update its state (for example DOM nodes associated
1.86 + * with the model). The update usually happens asynchronously.
1.87 + *
1.88 + * @param data technology's own representation of the model
1.89 + * @param propertyName name of the model property that changed
1.90 + */
1.91 + public void valueHasMutated(Data data, String propertyName);
1.92 +
1.93 + public void expose(FunctionBinding fb, Object model, Data d);
1.94 +
1.95 + /** Applies given data to current context (usually an HTML page).
1.96 + * @param data the data to apply
1.97 + */
1.98 + public void applyBindings(Data data);
1.99 +
1.100 + /**
1.101 + * Some technologies may require wrapping a Java array into a special
1.102 + * object. In such case they may return it from this method.
1.103 + *
1.104 + * @param arr original array
1.105 + * @return wrapped array
1.106 + */
1.107 + public Object wrapArray(Object[] arr);
1.108 +
1.109 + /**
1.110 + * Run given runnable in a safe mode. If the runnable can be executed
1.111 + * immediately, do it. If we need to switch to some other thread, do it
1.112 + * and invoke r asynchronously immediately returning from the call to
1.113 + * runSafe method.
1.114 + *
1.115 + * @param r the runnable to execute
1.116 + * @deprecated Use {@link BrwsrCtx#execute(java.lang.Runnable)}
1.117 + */
1.118 + @Deprecated
1.119 + public void runSafe(Runnable r);
1.120 +
1.121 + /** For certain rendering technologies it may be more efficient to register
1.122 + * property and function bindings for one instance of the model at once,
1.123 + * rather then doing it incrementally via
1.124 + * {@link Technology#expose(org.netbeans.html.json.spi.FunctionBinding, java.lang.Object, java.lang.Object) }
1.125 + * and
1.126 + * {@link Technology#bind(org.netbeans.html.json.spi.PropertyBinding, java.lang.Object, java.lang.Object) }.
1.127 + * In such case implement the {@link #wrapModel(java.lang.Object, org.netbeans.html.json.spi.PropertyBinding[], org.netbeans.html.json.spi.FunctionBinding[]) }
1.128 + * method of this interface and it will be called instead of the
1.129 + * previous two ones.
1.130 + *
1.131 + * @since 0.6
1.132 + */
1.133 + public static interface BatchInit<D> extends Technology<D> {
1.134 + /** Wrap the given model into redering technology appropriate object
1.135 + * <code>D</code> and expose given properties and functions on it.
1.136 + *
1.137 + * @param model the {@link Models#isModel(java.lang.Class) model} in Java
1.138 + * @param propArr array of property bindings to expose
1.139 + * @param funcArr array of functions to expose
1.140 + * @return appropriate wrapper around the model
1.141 + */
1.142 + public D wrapModel(Object model, PropertyBinding[] propArr, FunctionBinding[] funcArr);
1.143 + }
1.144 +
1.145 + /** Some technologies are more effective when number of calls between
1.146 + * Java and JavaScript is limited - to do that when a value of property
1.147 + * is changed they should implement this additional interface.
1.148 + *
1.149 + * @param <D> internal type of the technology
1.150 + * @since 0.7.6
1.151 + */
1.152 + public static interface ValueMutated<D> extends Technology<D> {
1.153 + /** Model for given data has changed its value. The technology is
1.154 + * supposed to update its state (for example DOM nodes associated
1.155 + * with the model). The update usually happens asynchronously.
1.156 + * <p>
1.157 + * If both <code>oldValue</code> and <code>newValue</code> are
1.158 + * <code>null</code> then the real value of the technology is
1.159 + * not known.
1.160 + * <p>
1.161 + * If this method is present, then it is called instead of
1.162 + * old, plain {@link #valueHasMutated(java.lang.Object, java.lang.String)}
1.163 + * which is never called by the infrastructure then.
1.164 + *
1.165 + * @param data technology's own representation of the model
1.166 + * @param propertyName name of the model property that changed
1.167 + * @param oldValue provides previous value of the property
1.168 + * @param newValue provides new value of the property
1.169 + */
1.170 + public void valueHasMutated(D data, String propertyName, Object oldValue, Object newValue);
1.171 + }
1.172 +}