1 /* 2 * Copyright (c) 2006, 2016, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package netscape.javascript; 27 28 import jdk.internal.netscape.javascript.spi.JSObjectProvider; 29 import java.applet.Applet; 30 import java.security.AccessController; 31 import java.security.PrivilegedAction; 32 import java.util.Iterator; 33 import java.util.ServiceLoader; 34 35 /** 36 * <p> 37 * Allows Java code to manipulate JavaScript objects. 38 * </p> 39 * 40 * <p> 41 * When a JavaScript object is passed or returned to Java code, it 42 * is wrapped in an instance of {@code JSObject}. When a 43 * {@code JSObject} instance is passed to the JavaScript engine, 44 * it is unwrapped back to its original JavaScript object. The 45 * {@code JSObject} class provides a way to invoke JavaScript 46 * methods and examine JavaScript properties. 47 * </p> 48 * 49 * <p> Any data returned from the JavaScript engine to Java is 50 * converted to Java data types. Certain data passed to the JavaScript 51 * engine is converted to JavaScript data types. 52 * </p> 53 * 54 */ 55 public abstract class JSObject { 56 /** 57 * Constructs a new JSObject. Users should neither call this method nor 58 * subclass JSObject. 59 */ 60 protected JSObject() { 61 } 62 63 /** 64 * Calls a JavaScript method. Equivalent to 65 * "this.methodName(args[0], args[1], ...)" in JavaScript. 66 * 67 * @param methodName The name of the JavaScript method to be invoked. 68 * @param args the Java objects passed as arguments to the method. 69 * @return Result of the method. 70 * @throws JSException when an error is reported from the browser or 71 * JavaScript engine. 72 */ 73 public abstract Object call(String methodName, Object... args) throws JSException; 74 75 /** 76 * Evaluates a JavaScript expression. The expression is a string of 77 * JavaScript source code which will be evaluated in the context given by 78 * "this". 79 * 80 * @param s The JavaScript expression. 81 * @return Result of the JavaScript evaluation. 82 * @throws JSException when an error is reported from the browser or 83 * JavaScript engine. 84 */ 85 public abstract Object eval(String s) throws JSException; 86 87 /** 88 * Retrieves a named member of a JavaScript object. Equivalent to 89 * "this.name" in JavaScript. 90 * 91 * @param name The name of the JavaScript property to be accessed. 92 * @return The value of the propery. 93 * @throws JSException when an error is reported from the browser or 94 * JavaScript engine. 95 */ 96 public abstract Object getMember(String name) throws JSException; 97 98 /** 99 * Sets a named member of a JavaScript object. Equivalent to 100 * "this.name = value" in JavaScript. 101 * 102 * @param name The name of the JavaScript property to be accessed. 103 * @param value The value of the propery. 104 * @throws JSException when an error is reported from the browser or 105 * JavaScript engine. 106 */ 107 public abstract void setMember(String name, Object value) throws JSException; 108 109 /** 110 * Removes a named member of a JavaScript object. Equivalent 111 * to "delete this.name" in JavaScript. 112 * 113 * @param name The name of the JavaScript property to be removed. 114 * @throws JSException when an error is reported from the browser or 115 * JavaScript engine. 116 */ 117 public abstract void removeMember(String name) throws JSException; 118 119 /** 120 * Retrieves an indexed member of a JavaScript object. Equivalent to 121 * "this[index]" in JavaScript. 122 * 123 * @param index The index of the array to be accessed. 124 * @return The value of the indexed member. 125 * @throws JSException when an error is reported from the browser or 126 * JavaScript engine. 127 */ 128 public abstract Object getSlot(int index) throws JSException; 129 130 /** 131 * Sets an indexed member of a JavaScript object. Equivalent to 132 * "this[index] = value" in JavaScript. 133 * 134 * @param index The index of the array to be accessed. 135 * @param value The value to set 136 * @throws JSException when an error is reported from the browser or 137 * JavaScript engine. 138 */ 139 public abstract void setSlot(int index, Object value) throws JSException; 140 141 /** 142 * Returns a JSObject for the window containing the given applet. This 143 * method only works when the Java code is running in a browser as an 144 * applet. The object returned may be used to access the HTML DOM directly. 145 * 146 * @param applet The applet. 147 * @return JSObject representing the window containing the given applet or 148 * {@code null} if we are not connected to a browser. 149 * @throws JSException when an error is reported from the browser or 150 * JavaScript engine or if applet is {@code null} 151 */ 152 public static JSObject getWindow(Applet applet) throws JSException { 153 return ProviderLoader.callGetWindow(applet); 154 } 155 156 private static class ProviderLoader { 157 private static final JSObjectProvider provider; 158 159 static { 160 provider = AccessController.doPrivileged( 161 new PrivilegedAction<>() { 162 @Override 163 public JSObjectProvider run() { 164 Iterator<JSObjectProvider> providers = 165 ServiceLoader.loadInstalled(JSObjectProvider.class).iterator(); 166 if (providers.hasNext()) { 167 return providers.next(); 168 } 169 return null; 170 } 171 } 172 ); 173 } 174 175 private static JSObject callGetWindow(Applet applet) { 176 if (provider != null) { 177 return provider.getWindow(applet); 178 } 179 return null; 180 } 181 } 182 }