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 }