ModuleSourceProvider (rhino 1.7.7.2 API)
Date: 2017-09-27

org.mozilla.javascript.commonjs.module.provider

## Interface ModuleSourceProvider

- All Known Implementing Classes:
    ModuleSourceProviderBase, UrlModuleSourceProvider

      public interface ModuleSourceProvider

  Implemented by objects that can provide the source text for the script. The design of the interface supports cache revalidation.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static ModuleSource` | `NOT_MODIFIED` A special return value for `loadSource(String, Scriptable, Object)` and `loadSource(URI, URI, Object)` that signifies that the cached representation is still valid according to the passed validator.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `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 baseUri, java.lang.Object validator)` Returns the script source of the requested module from the given URI.

- - ### Field Detail

    - #### NOT_MODIFIED

          static final ModuleSource NOT_MODIFIED

      A special return value for `loadSource(String, Scriptable, Object)` and `loadSource(URI, URI, Object)` that signifies that the cached representation is still valid according to the passed validator.

  - ### Method Detail

    - #### loadSource

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

      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 `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.
      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. `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.
        `java.lang.IllegalArgumentException` - if the module ID is syntactically not a valid absolute module identifier.

    - #### loadSource

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

      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 `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.

      Parameters:
        `uri` - the absolute URI from which to load the module source, but without an extension such as ".js".
        `baseUri` - 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. `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