Module org.htmlunit.corejs
Package org.htmlunit.corejs.javascript

Class TopLevel

java.lang.Object
org.htmlunit.corejs.javascript.SlotMapOwner<VarScope>
org.htmlunit.corejs.javascript.ScopeObject
org.htmlunit.corejs.javascript.TopLevel
All Implemented Interfaces:
Serializable, ConstProperties<VarScope>, PropHolder<VarScope>, VarScope
Direct Known Subclasses:
ImporterTopLevel
public class TopLevel extends ScopeObject
A top-level scope object that provides special means to cache and preserve the initial values of the built-in constructor properties for better ECMAScript compliance.

ECMA 262 requires that most constructors used internally construct objects with the original prototype object as value of their [[Prototype]] internal property. Since built-in global constructors are defined as writable and deletable, this means they should be cached to protect against redefinition at runtime.

In order to implement this efficiently, this class provides a mechanism to access the original built-in global constructors and their prototypes via numeric class-ids. To make use of this, the new ScriptRuntime.newBuiltinObject and ScriptRuntime.setBuiltinProtoAndParent methods should be used to create and initialize objects of built-in classes instead of their generic counterparts.

Calling Context.initStandardObjects() with an instance of this class as argument will automatically cache built-in classes after initialization. For other setups involving top-level scopes that inherit global properties from their prototypes (e.g. with dynamic scopes) embeddings should explicitly call cacheBuiltins(boolean) to initialize the class cache for each top-level scope.

See Also:

  • Constructor Details

    • TopLevel

      public TopLevel()

    • TopLevel

      public TopLevel(ScriptableObject customGlobal)

  • Method Details

    • createIsolate

      public static TopLevel createIsolate(TopLevel parent)

    • createIsolate

      public static TopLevel createIsolate(TopLevel parent, ScriptableObject customGlobal)

    • createIsolateCustomPrototypeChain

      public static TopLevel createIsolateCustomPrototypeChain(TopLevel parent, ScriptableObject customGlobal)
      Only use this function if you have already set the customGlobal's prototype chain to point to this top level's global object. This should only be done if you know for certain that no other use will be made of this prototype chain.

    • cacheBuiltins

      @Deprecated public void cacheBuiltins(TopLevel scope, boolean sealed)
      Deprecated.
      Cache the built-in ECMAScript objects to protect them against modifications by the script. This method is called automatically by ScriptRuntime.initStandardObjects if the scope argument is an instance of this class. It only has to be called by the embedding if a top-level scope is not initialized through initStandardObjects().

      This method is deprecated and kept for compatibility. Please use either cacheBuiltins(boolean) or copyBuiltins(org.htmlunit.corejs.javascript.TopLevel,boolean) instead.

    • cacheBuiltins

      public void cacheBuiltins(boolean sealed)

    • copyBuiltins

      public void copyBuiltins(TopLevel other, boolean sealed)

    • getBuiltinCtor

      public static Function getBuiltinCtor(Context cx, VarScope scope, TopLevel.Builtins type)
      Static helper method to get a built-in object constructor with the given type from the given scope. If the scope is not an instance of this class or does have a cache of built-ins, the constructor is looked up via normal property lookup.
      Parameters:
      cx - the current Context
      scope - the top-level scope
      type - the built-in type
      Returns:
      the built-in constructor

    • getBuiltinPrototype

      public static Scriptable getBuiltinPrototype(TopLevel scope, TopLevel.Builtins type)
      Static helper method to get a built-in object prototype with the given type from the given scope. If the scope is not an instance of this class or does have a cache of built-ins, the prototype is looked up via normal property lookup.
      Parameters:
      scope - the top-level scope
      type - the built-in type
      Returns:
      the built-in prototype

    • getBuiltinCtor

      public BaseFunction getBuiltinCtor(TopLevel.Builtins type)
      Get the cached built-in object constructor from this scope with the given type. Returns null if cacheBuiltins(boolean) has not been called on this object.
      Parameters:
      type - the built-in type
      Returns:
      the built-in constructor

    • getBuiltinPrototype

      public Scriptable getBuiltinPrototype(TopLevel.Builtins type)
      Get the cached built-in object prototype from this scope with the given type. Returns null if cacheBuiltins(boolean) has not been called on this object.
      Parameters:
      type - the built-in type
      Returns:
      the built-in prototype

    • getBuiltinPrototype

      public Scriptable getBuiltinPrototype(org.htmlunit.corejs.javascript.TopLevel.NativeErrors type)
      Get the cached built-in object prototype from this scope with the given type. Returns null if cacheBuiltins(boolean) has not been called on this object.
      Parameters:
      type - the built-in type
      Returns:
      the built-in prototype

    • getGlobalThis

      public ScriptableObject getGlobalThis()

    • get

      public Object get(String name, VarScope start)
      Description copied from class: ScopeObject
      Returns the value of the named property or NOT_FOUND.

      If the property was created using defineProperty, the appropriate getter method is called.

      Specified by:
      get in interface PropHolder<VarScope>
      Overrides:
      get in class ScopeObject
      Parameters:
      name - the name of the property
      start - the object in which the lookup began
      Returns:
      the value of the property (may be null), or NOT_FOUND

    • put

      public void put(String name, VarScope start, Object value)
      Description copied from class: ScopeObject
      Sets the value of the named property, creating it if need be.

      If the property was created using defineProperty, the appropriate setter method is called.

      If the property's attributes include READONLY, no action is taken. This method will actually set the property in the start object.

      Specified by:
      put in interface PropHolder<VarScope>
      Overrides:
      put in class ScopeObject
      Parameters:
      name - the name of the property
      start - the object whose property is being set
      value - value to set the property to

    • has

      public boolean has(String name, VarScope start)
      Description copied from class: ScopeObject
      Returns true if the named property is defined.
      Specified by:
      has in interface PropHolder<VarScope>
      Overrides:
      has in class ScopeObject
      Parameters:
      name - the name of the property
      start - the object in which the lookup began
      Returns:
      true if and only if the property was found in the object

    • delete

      public void delete(String name)
      Specified by:
      delete in interface PropHolder<VarScope>
      Overrides:
      delete in class ScopeObject

    • sealObject

      public void sealObject()
      Overrides:
      sealObject in class SlotMapOwner<VarScope>

    • defineProperty

      public void defineProperty(String propertyName, Object value, int attributes)
      Description copied from class: ScopeObject
      Define a JavaScript property.

      Creates the property with an initial value and sets its attributes.

      Overrides:
      defineProperty in class ScopeObject
      Parameters:
      propertyName - the name of the property to define.
      value - the initial value of the property
      attributes - the attributes of the JavaScript property
      See Also:

    • setAttributes

      public void setAttributes(String name, int attributes)
      Description copied from class: ScopeObject
      Set the attributes of a named property.

      The property is specified by name as defined for has.

      The possible attributes are READONLY, DONTENUM, and PERMANENT. Combinations of attributes are expressed by the bitwise OR of attributes. EMPTY is the state of no attributes set. Any unused bits are reserved for future use.

      Overrides:
      setAttributes in class ScopeObject
      Parameters:
      name - the name of the property
      attributes - the bitset of attributes
      See Also:

    • getAttributes

      public int getAttributes(String name)
      Description copied from class: SlotMapOwner
      Get the attributes of a named property.

      The property is specified by name as defined for has.

      Overrides:
      getAttributes in class SlotMapOwner<VarScope>
      Parameters:
      name - the identifier for the property
      Returns:
      the bitset of attributes
      See Also:

    • isConst

      public boolean isConst(Context cx, String name)
      Description copied from class: ScopeObject
      Returns true if the named property is defined as a const on this object.
      Specified by:
      isConst in interface ConstProperties<VarScope>
      Overrides:
      isConst in class ScopeObject
      name - the name of the property
      Returns:
      true if the named property is defined as a const, false otherwise.

    • putConst

      public void putConst(Context cx, String name, VarScope start, Object value)
      Description copied from class: ScopeObject
      Sets the value of the named const property, creating it if need be.

      If the property was created using defineProperty, the appropriate setter method is called.

      If the property's attributes include READONLY, no action is taken. This method will actually set the property in the start object.

      Specified by:
      putConst in interface ConstProperties<VarScope>
      Overrides:
      putConst in class ScopeObject
      name - the name of the property
      start - the object whose property is being set
      value - value to set the property to
      See Also:

    • defineConst

      public void defineConst(Context cx, String name, VarScope start)
      Description copied from interface: ConstProperties
      Reserves a definition spot for a const. This will set up a definition of the const property, but set its value to undefined. The semantics of the start parameter is the same as for putConst.
      Specified by:
      defineConst in interface ConstProperties<VarScope>
      Overrides:
      defineConst in class ScopeObject
      name - The name of the property.
      start - The object whose property is being reserved.

    • defineFunctionProperties

      public void defineFunctionProperties(VarScope scope, String[] names, Class<?> clazz, int attributes)