ModuleSourceProviderBase (rhino 1.7.7.1 API)
Date: 2016-02-03

org.mozilla.javascript.commonjs.module.provider

## Class ModuleSourceProviderBase

- java.lang.Object
- - org.mozilla.javascript.commonjs.module.provider.ModuleSourceProviderBase

- All Implemented Interfaces:
    java.io.Serializable, ModuleSourceProvider
  Direct Known Subclasses:
    UrlModuleSourceProvider

      public abstract class ModuleSourceProviderBase
      extends java.lang.Object
      implements ModuleSourceProvider, java.io.Serializable

  A base implementation for all module script providers that actually load module scripts. Performs validation of identifiers, allows loading from preferred locations (attempted before require.paths), from require.paths itself, and from fallback locations (attempted after require.paths). Note that while this base class strives to be as generic as possible, it does have loading from an URI built into its design, for the simple reason that the require.paths is defined in terms of URIs.
  See Also:
    Serialized Form

- - ### Field Summary

    - ### Fields inherited from interface org.mozilla.javascript.commonjs.module.provider.ModuleSourceProvider

      `NOT_MODIFIED`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ModuleSourceProviderBase()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected boolean` | `entityNeedsRevalidation(java.lang.Object validator)` Override to determine whether according to the validator, the cached module script needs revalidation.
    `protected ModuleSource` | `loadFromFallbackLocations(java.lang.String moduleId, java.lang.Object validator)` Override to obtain a module source from fallback locations.
    `protected ModuleSource` | `loadFromPrivilegedLocations(java.lang.String moduleId, java.lang.Object validator)` Override to obtain a module source from privileged locations.
    `protected abstract ModuleSource` | `loadFromUri(java.net.URI uri, java.net.URI base, java.lang.Object validator)` Override in a subclass to load a module script from a logical URI.
    `ModuleSource` | `loadSource(java.lang.String moduleId, Scriptable paths, java.lang.Object validator)` Returns the script source of the requested module.
    `ModuleSource` | `loadSource(java.net.URI uri, java.net.URI base, java.lang.Object validator)` Returns the script source of the requested module from the given URI.

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

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

- - ### Constructor Detail

    - #### ModuleSourceProviderBase

          public ModuleSourceProviderBase()

  - ### Method Detail

    - #### loadSource

          public ModuleSource loadSource(java.lang.String moduleId,
                                Scriptable paths,
                                java.lang.Object validator)
                                  throws java.io.IOException,
                                         java.net.URISyntaxException

      Description copied from interface: `ModuleSourceProvider`
      Returns the script source of the requested module. More specifically, it resolves the module ID to a resource. If it can not resolve it, null is returned. If the caller passes a non-null validator, and the source provider recognizes it, and the validator applies to the same resource that the provider would use to load the source, and the validator validates the current cached representation of the resource (using whatever semantics for validation that this source provider implements), then `ModuleSourceProvider.NOT_MODIFIED` should be returned. Otherwise, it should return a `ModuleSource` object with the actual source text of the module, preferrably a validator for it, and a security domain, where applicable.
      Specified by:
        `loadSource` in interface `ModuleSourceProvider`
      Parameters:
        `moduleId` - the ID of the module. An implementation must only accept an absolute ID, starting with a term.
        `paths` - the value of the require() function's "paths" attribute. If the require() function is sandboxed, it will be null, otherwise it will be a JavaScript Array object. It is up to the provider implementation whether and how it wants to honor the contents of the array.
        `validator` - a validator for an existing loaded and cached module. This will either be null, or an object that this source provider returned earlier as part of a `ModuleSource`. It can be used to validate the existing cached module and avoid reloading it.
      Returns:
        a script representing the code of the module. Null should be returned if the script is not found. `ModuleSourceProvider.NOT_MODIFIED` should be returned if the passed validator validates the current representation of the module (the currently cached module script).
      Throws:
        `java.io.IOException` - if there was an I/O problem reading the script
        `java.net.URISyntaxException` - if the final URI could not be constructed.

    - #### loadSource

          public ModuleSource loadSource(java.net.URI uri,
                                java.net.URI base,
                                java.lang.Object validator)
                                  throws java.io.IOException,
                                         java.net.URISyntaxException

      Description copied from interface: `ModuleSourceProvider`
      Returns the script source of the requested module from the given URI. The URI is absolute but does not contain a file name extension such as ".js", which may be specific to the ModuleSourceProvider implementation.

      If the resource is not found, null is returned. If the caller passes a non-null validator, and the source provider recognizes it, and the validator applies to the same resource that the provider would use to load the source, and the validator validates the current cached representation of the resource (using whatever semantics for validation that this source provider implements), then `ModuleSourceProvider.NOT_MODIFIED` should be returned. Otherwise, it should return a `ModuleSource` object with the actual source text of the module, preferrably a validator for it, and a security domain, where applicable.

      Specified by:
        `loadSource` in interface `ModuleSourceProvider`
      Parameters:
        `uri` - the absolute URI from which to load the module source, but without an extension such as ".js".
        `base` - the module path base URI from which `uri` was derived.
        `validator` - a validator for an existing loaded and cached module. This will either be null, or an object that this source provider returned earlier as part of a `ModuleSource`. It can be used to validate the existing cached module and avoid reloading it.
      Returns:
        a script representing the code of the module. Null should be returned if the script is not found. `ModuleSourceProvider.NOT_MODIFIED` should be returned if the passed validator validates the current representation of the module (the currently cached module script).
      Throws:
        `java.io.IOException` - if there was an I/O problem reading the script
        `java.net.URISyntaxException` - if the final URI could not be constructed

    - #### entityNeedsRevalidation

          protected boolean entityNeedsRevalidation(java.lang.Object validator)

      Override to determine whether according to the validator, the cached module script needs revalidation. A validator can carry expiry information. If the cached representation is not expired, it doesn' t need revalidation, otherwise it does. When no cache revalidation is required, the external resource will not be contacted at all, so some level of expiry (staleness tolerance) can greatly enhance performance. The default implementation always returns true so it will always require revalidation.
      Parameters:
        `validator` - the validator
      Returns:
        returns true if the cached module needs revalidation.

    - #### loadFromUri

          protected abstract ModuleSource loadFromUri(java.net.URI uri,
                                 java.net.URI base,
                                 java.lang.Object validator)
                                               throws java.io.IOException,
                                                      java.net.URISyntaxException

      Override in a subclass to load a module script from a logical URI. The URI is absolute but does not have a file name extension such as ".js". It is up to the ModuleSourceProvider implementation to add such an extension.
      Parameters:
        `uri` - the URI of the script, without file name extension.
        `base` - the base URI the uri was resolved from.
        `validator` - a validator that can be used to revalidate an existing cached source at the URI. Can be null if there is no cached source available.
      Returns:
        the loaded module script, or null if it can't be found, or `ModuleSourceProvider.NOT_MODIFIED` if it revalidated the existing cached source against the URI.
      Throws:
        `java.io.IOException` - if the module script was found, but an I/O exception prevented it from being loaded.
        `java.net.URISyntaxException` - if the final URI could not be constructed

    - #### loadFromPrivilegedLocations

          protected ModuleSource loadFromPrivilegedLocations(java.lang.String moduleId,
                                                 java.lang.Object validator)
                                                      throws java.io.IOException,
                                                             java.net.URISyntaxException

      Override to obtain a module source from privileged locations. This will be called before source is attempted to be obtained from URIs specified in require.paths.
      Parameters:
        `moduleId` - the ID of the module
        `validator` - a validator that can be used to validate an existing cached script. Can be null if there is no cached script available.
      Returns:
        the loaded module script, or null if it can't be found in the privileged locations, or `ModuleSourceProvider.NOT_MODIFIED` if the existing cached module script is still valid.
      Throws:
        `java.io.IOException` - if the module script was found, but an I/O exception prevented it from being loaded.
        `java.net.URISyntaxException` - if the final URI could not be constructed.

    - #### loadFromFallbackLocations

          protected ModuleSource loadFromFallbackLocations(java.lang.String moduleId,
                                               java.lang.Object validator)
                                                    throws java.io.IOException,
                                                           java.net.URISyntaxException

      Override to obtain a module source from fallback locations. This will be called after source is attempted to be obtained from URIs specified in require.paths.
      Parameters:
        `moduleId` - the ID of the module
        `validator` - a validator that can be used to validate an existing cached script. Can be null if there is no cached script available.
      Returns:
        the loaded module script, or null if it can't be found in the privileged locations, or `ModuleSourceProvider.NOT_MODIFIED` if the existing cached module script is still valid.
      Throws:
        `java.io.IOException` - if the module script was found, but an I/O exception prevented it from being loaded.
        `java.net.URISyntaxException` - if the final URI could not be constructed.