org.mozilla.javascript.commonjs.module

## Class Require

- java.lang.Object
- - org.mozilla.javascript.ScriptableObject
  - - org.mozilla.javascript.IdScriptableObject
    - - org.mozilla.javascript.BaseFunction
      - - org.mozilla.javascript.commonjs.module.Require

- All Implemented Interfaces:
    java.io.Serializable, Callable, ConstProperties, DebuggableObject, Function, IdFunctionCall, Scriptable

      public class Require
      extends BaseFunction

  Implements the require() function as defined by Common JS modules.

  # Thread safety

  You will ordinarily create one instance of require() for every top-level scope. This ordinarily means one instance per program execution, except if you use shared top-level scopes and installing most objects into them. Module loading is thread safe, so using a single require() in a shared top-level scope is also safe.

  # Creation

  If you need to create many otherwise identical require() functions for different scopes, you might want to use `RequireBuilder` for convenience.

  # Making it available

  In order to make the require() function available to your JavaScript program, you need to invoke either `install(Scriptable)` or `requireMain(Context, String)`.
  Version:
    $Id: Require.java,v 1.4 2011/04/07 20:26:11 hannes%helma.at Exp $
  Author:
    Attila Szegedi
  See Also:
    Serialized Form

- - ### Field Summary

    - ### Fields inherited from class org.mozilla.javascript.ScriptableObject

      `CONST, DONTENUM, EMPTY, PERMANENT, READONLY, UNINITIALIZED_CONST`

    - ### Fields inherited from interface org.mozilla.javascript.Scriptable

      `NOT_FOUND`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Require(Context cx, Scriptable nativeScope, ModuleScriptProvider moduleScriptProvider, Script preExec, Script postExec, boolean sandboxed)` Creates a new instance of the require() function.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.Object` | `call(Context cx, Scriptable scope, Scriptable thisObj, java.lang.Object[] args)` Should be overridden.
    `Scriptable` | `construct(Context cx, Scriptable scope, java.lang.Object[] args)` Call the function as a constructor.
    `int` | `getArity()`
    `java.lang.String` | `getFunctionName()`
    `int` | `getLength()`
    `void` | `install(Scriptable scope)` Binds this instance of require() into the specified scope under the property name "require".
    `Scriptable` | `requireMain(Context cx, java.lang.String mainModuleId)` Calling this method establishes a module as being the main module of the program to which this require() instance belongs.

    - ### Methods inherited from class org.mozilla.javascript.BaseFunction

      `createObject, execIdCall, fillConstructorProperties, findInstanceIdInfo, findPrototypeId, getClassName, getClassPrototype, getInstanceIdName, getInstanceIdValue, getMaxInstanceId, getPrototypeProperty, getTypeOf, hasInstance, hasPrototypeProperty, initPrototypeId, setImmunePrototypeProperty, setInstanceIdValue`

    - ### Methods inherited from class org.mozilla.javascript.IdScriptableObject

      `activatePrototypeMap, addIdFunctionProperty, defaultGet, defaultPut, defineOwnProperty, delete, exportAsJSClass, get, getAttributes, getOwnPropertyDescriptor, has, hasPrototypeMap, incompatibleCallError, initPrototypeConstructor, initPrototypeMethod, initPrototypeValue, instanceIdInfo, put, setAttributes, setInstanceIdAttributes`

    - ### Methods inherited from class org.mozilla.javascript.ScriptableObject

      `applyDescriptorToAttributeBitset, associateValue, avoidObjectDetection, buildDataDescriptor, callMethod, callMethod, checkPropertyChange, checkPropertyDefinition, defineClass, defineClass, defineClass, defineConst, defineConstProperty, defineFunctionProperties, defineOwnProperties, defineOwnProperty, defineProperty, defineProperty, defineProperty, defineProperty, delete, deleteProperty, deleteProperty, ensureScriptable, ensureScriptableObject, equivalentValues, get, get, getAllIds, getArrayPrototype, getAssociatedValue, getAttributes, getAttributes, getAttributes, getClassPrototype, getDefaultValue, getDefaultValue, getFunctionPrototype, getGetterOrSetter, getIds, getObjectPrototype, getParentScope, getProperty, getProperty, getPropertyIds, getPrototype, getSlot, getTopLevelScope, getTopScopeValue, getTypedProperty, getTypedProperty, has, hasProperty, hasProperty, isAccessorDescriptor, isConst, isDataDescriptor, isEmpty, isExtensible, isFalse, isGenericDescriptor, isGetterOrSetter, isSealed, isTrue, preventExtensions, put, putConst, putConstProperty, putProperty, putProperty, redefineProperty, sameValue, sealObject, setAttributes, setAttributes, setAttributes, setGetterOrSetter, setParentScope, setPrototype, size`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface org.mozilla.javascript.Scriptable

      `delete, delete, get, get, getDefaultValue, getIds, getParentScope, getPrototype, has, has, put, put, setParentScope, setPrototype`

- - ### Constructor Detail

    - #### Require

          public Require(Context cx,
                 Scriptable nativeScope,
                 ModuleScriptProvider moduleScriptProvider,
                 Script preExec,
                 Script postExec,
                 boolean sandboxed)

      Creates a new instance of the require() function. Upon constructing it, you will either want to install it in the global (or some other) scope using `install(Scriptable)`, or alternatively, you can load the program's main module using `requireMain(Context, String)` and then act on the main module's exports.
      Parameters:
        `cx` - the current context
        `nativeScope` - a scope that provides the standard native JavaScript objects.
        `moduleScriptProvider` - a provider for module scripts
        `preExec` - an optional script that is executed in every module's scope before its module script is run.
        `postExec` - an optional script that is executed in every module's scope after its module script is run.
        `sandboxed` - if set to true, the require function will be sandboxed. This means that it doesn't have the "paths" property, and also that the modules it loads don't export the "module.uri" property.

  - ### Method Detail

    - #### requireMain

          public Scriptable requireMain(Context cx,
                               java.lang.String mainModuleId)

      Calling this method establishes a module as being the main module of the program to which this require() instance belongs. The module will be loaded as if require()'d and its "module" property will be set as the "main" property of this require() instance. You have to call this method before the module has been loaded (that is, the call to this method must be the first to require the module and thus trigger its loading). Note that the main module will execute in its own scope and not in the global scope. Since all other modules see the global scope, executing the main module in the global scope would open it for tampering by other modules.
      Parameters:
        `cx` - the current context
        `mainModuleId` - the ID of the main module
      Returns:
        the "exports" property of the main module
      Throws:
        `java.lang.IllegalStateException` - if the main module is already loaded when required, or if this require() instance already has a different main module set.

    - #### install

          public void install(Scriptable scope)

      Binds this instance of require() into the specified scope under the property name "require".
      Parameters:
        `scope` - the scope where the require() function is to be installed.

    - #### call

          public java.lang.Object call(Context cx,
                              Scriptable scope,
                              Scriptable thisObj,
                              java.lang.Object[] args)

      Description copied from class: `BaseFunction`
      Should be overridden.
      Specified by:
        `call` in interface `Callable`
      Specified by:
        `call` in interface `Function`
      Overrides:
        `call` in class `BaseFunction`
      Parameters:
        `cx` - the current Context for this thread
        `scope` - the scope to execute the function relative to. This is set to the value returned by getParentScope() except when the function is called from a closure.
        `thisObj` - the JavaScript `this` object
        `args` - the array of arguments
      Returns:
        the result of the call

    - #### construct

          public Scriptable construct(Context cx,
                             Scriptable scope,
                             java.lang.Object[] args)

      Description copied from interface: `Function`
      Call the function as a constructor. This method is invoked by the runtime in order to satisfy a use of the JavaScript `new` operator. This method is expected to create a new object and return it.
      Specified by:
        `construct` in interface `Function`
      Overrides:
        `construct` in class `BaseFunction`
      Parameters:
        `cx` - the current Context for this thread
        `scope` - an enclosing scope of the caller except when the function is called from a closure.
        `args` - the array of arguments
      Returns:
        the allocated object

    - #### getFunctionName

          public java.lang.String getFunctionName()

      Overrides:
        `getFunctionName` in class `BaseFunction`

    - #### getArity

          public int getArity()

      Overrides:
        `getArity` in class `BaseFunction`

    - #### getLength

          public int getLength()

      Overrides:
        `getLength` in class `BaseFunction`