1 /*
   2  * Copyright (c) 2010, 2013, 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 jdk.nashorn.internal.runtime;
  27 
  28 import java.lang.invoke.MethodHandle;
  29 import java.util.concurrent.Callable;
  30 import jdk.internal.dynalink.linker.GuardedInvocation;
  31 import jdk.internal.dynalink.linker.LinkRequest;
  32 import jdk.nashorn.internal.runtime.linker.InvokeByName;
  33 
  34 /**
  35  * Runtime interface to the global scope objects.
  36  */
  37 
  38 public interface GlobalObject {
  39     /**
  40      * Is this global of the given Context?
  41      * @return true if this global belongs to the given Context
  42      */
  43     public boolean isOfContext(Context context);
  44 
  45     /**
  46      * Does this global belong to a strict Context?
  47      * @return true if this global belongs to a strict Context
  48      */
  49     public boolean isStrictContext();
  50 
  51     /**
  52      * Initialize standard builtin objects like "Object", "Array", "Function" etc.
  53      * as well as our extension builtin objects like "Java", "JSAdapter" as properties
  54      * of the global scope object.
  55      */
  56     public void initBuiltinObjects();
  57 
  58     /**
  59      * Wrapper for {@link jdk.nashorn.internal.objects.Global#newScriptFunction(String, MethodHandle, ScriptObject, boolean)}
  60      *
  61      * @param name   function name
  62      * @param handle invocation handle for function
  63      * @param scope  the scope
  64      * @param strict are we in strict mode
  65      *
  66      * @return new script function
  67      */
  68    public ScriptFunction newScriptFunction(String name, MethodHandle handle, ScriptObject scope, boolean strict);
  69 
  70     /**
  71      * Wrapper for {@link jdk.nashorn.internal.objects.Global#wrapAsObject(Object)}
  72      *
  73      * @param obj object to wrap
  74      * @return    wrapped object
  75      */
  76    public Object wrapAsObject(Object obj);
  77 
  78 
  79     /**
  80      * Wrapper for {@link jdk.nashorn.internal.objects.Global#primitiveLookup(LinkRequest, Object)}
  81      *
  82      * @param request the link request for the dynamic call site.
  83      * @param self     self reference
  84      *
  85      * @return guarded invocation
  86      */
  87    public GuardedInvocation primitiveLookup(LinkRequest request, Object self);
  88 
  89 
  90     /**
  91      * Wrapper for {@link jdk.nashorn.internal.objects.Global#newObject()}
  92      *
  93      * @return the new ScriptObject
  94      */
  95    public ScriptObject newObject();
  96 
  97     /**
  98      * Wrapper for {@link jdk.nashorn.internal.objects.Global#isError(ScriptObject)}
  99      *
 100      * @param sobj to check if it is an error object
 101      * @return true if error object
 102      */
 103    public boolean isError(ScriptObject sobj);
 104 
 105     /**
 106      * Wrapper for {@link jdk.nashorn.internal.objects.Global#newError(String)}
 107      *
 108      * @param msg the error message
 109      *
 110      * @return the new ScriptObject representing the error
 111      */
 112    public ScriptObject newError(String msg);
 113 
 114     /**
 115      * Wrapper for {@link jdk.nashorn.internal.objects.Global#newEvalError(String)}
 116      *
 117      * @param msg the error message
 118      *
 119      * @return the new ScriptObject representing the eval error
 120      */
 121    public ScriptObject newEvalError(String msg);
 122 
 123     /**
 124      * Wrapper for {@link jdk.nashorn.internal.objects.Global#newRangeError(String)}
 125      *
 126      * @param msg the error message
 127      *
 128      * @return the new ScriptObject representing the range error
 129      */
 130    public ScriptObject newRangeError(String msg);
 131 
 132     /**
 133      * Wrapper for {@link jdk.nashorn.internal.objects.Global#newReferenceError(String)}
 134      *
 135      * @param msg the error message
 136      *
 137      * @return the new ScriptObject representing the reference error
 138      */
 139    public ScriptObject newReferenceError(String msg);
 140 
 141     /**
 142      * Wrapper for {@link jdk.nashorn.internal.objects.Global#newSyntaxError(String)}
 143      *
 144      * @param msg the error message
 145      *
 146      * @return the new ScriptObject representing the syntax error
 147      */
 148    public ScriptObject newSyntaxError(String msg);
 149 
 150     /**
 151      * Wrapper for {@link jdk.nashorn.internal.objects.Global#newTypeError(String)}
 152      *
 153      * @param msg the error message
 154      *
 155      * @return the new ScriptObject representing the type error
 156      */
 157    public ScriptObject newTypeError(String msg);
 158 
 159     /**
 160      * Wrapper for {@link jdk.nashorn.internal.objects.Global#newURIError(String)}
 161      *
 162      * @param msg the error message
 163      *
 164      * @return the new ScriptObject representing the URI error
 165      */
 166     public ScriptObject newURIError(String msg);
 167 
 168     /**
 169      * Wrapper for {@link jdk.nashorn.internal.objects.Global#newGenericDescriptor(boolean, boolean)}
 170      *
 171      * @param configurable is the described property configurable
 172      * @param enumerable   is the described property enumerable
 173      *
 174      * @return property descriptor
 175      */
 176     public PropertyDescriptor newGenericDescriptor(boolean configurable, boolean enumerable);
 177 
 178     /**
 179      * Wrapper for {@link jdk.nashorn.internal.objects.Global#newDataDescriptor(Object, boolean, boolean, boolean)}
 180      *
 181      * @param value        data value
 182      * @param configurable is the described property configurable
 183      * @param enumerable   is the described property enumerable
 184      * @param writable     is the described property writable
 185      *
 186      * @return property descriptor
 187      */
 188     public PropertyDescriptor newDataDescriptor(Object value, boolean configurable, boolean enumerable, boolean writable);
 189 
 190     /**
 191      * Wrapper for {@link jdk.nashorn.internal.objects.Global#newAccessorDescriptor(Object, Object, boolean, boolean)}
 192      *
 193      * @param get          property getter, or null if none
 194      * @param set          property setter, or null if none
 195      * @param configurable is the described property configurable
 196      * @param enumerable   is the described property enumerable
 197      *
 198      * @return property descriptor
 199      */
 200     public PropertyDescriptor newAccessorDescriptor(Object get, Object set, boolean configurable, boolean enumerable);
 201 
 202     /**
 203      * Wrapper for {@link jdk.nashorn.internal.objects.Global#getDefaultValue(ScriptObject, Class)}
 204      *
 205      * @param sobj     script object
 206      * @param typeHint type hint
 207      *
 208      * @return default value
 209      */
 210     public Object getDefaultValue(ScriptObject sobj, Class<?> typeHint);
 211 
 212     /**
 213      * Find the compiled Class for the given script source, if available
 214      *
 215      * @param source Source object of the script
 216      * @return compiled Class object or null
 217      */
 218     public Class<?> findCachedClass(Source source);
 219 
 220     /**
 221      * Put the Source associated Class object in the Source-to-Class cache
 222      *
 223      * @param source Source of the script
 224      * @param clazz compiled Class object for the source
 225      */
 226     public void cacheClass(Source source, Class<?> clazz);
 227 
 228     /**
 229      * Get cached InvokeByName object for the given key
 230      * @param key key to be associated with InvokeByName object
 231      * @param creator if InvokeByName is absent 'creator' is called to make one (lazy init)
 232      * @return InvokeByName object associated with the key.
 233      */
 234     public InvokeByName getInvokeByName(final Object key, final Callable<InvokeByName> creator);
 235 
 236     /**
 237      * Get cached dynamic method handle for the given key
 238      * @param key key to be associated with dynamic method handle
 239      * @param creator if method handle is absent 'creator' is called to make one (lazy init)
 240      * @return dynamic method handle associated with the key.
 241      */
 242     public MethodHandle getDynamicInvoker(final Object key, final Callable<MethodHandle> creator);
 243 }