org.mozilla.javascript.commonjs.module.provider

## Class UrlModuleSourceProvider

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

- All Implemented Interfaces:
    java.io.Serializable, ModuleSourceProvider

      public class UrlModuleSourceProvider
      extends ModuleSourceProviderBase

  A URL-based script provider that can load modules against a set of base privileged and fallback URIs. It is deliberately not named "URI provider" but a "URL provider" since it actually only works against those URIs that are URLs (and the JRE has a protocol handler for them). It creates cache validators that are suitable for use with both file: and http: URL protocols. Specifically, it is able to use both last-modified timestamps and ETags for cache revalidation, and follows the HTTP cache expiry calculation model, and allows for fallback heuristic expiry calculation when no server specified expiry is provided.
  Version:
    $Id: UrlModuleSourceProvider.java,v 1.4 2011/04/07 20:26:12 hannes%helma.at Exp $
  Author:
    Attila Szegedi
  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
    `UrlModuleSourceProvider(java.lang.Iterable<java.net.URI> privilegedUris, java.lang.Iterable<java.net.URI> fallbackUris)` Creates a new module script provider that loads modules against a set of privileged and fallback URIs.
    `UrlModuleSourceProvider(java.lang.Iterable<java.net.URI> privilegedUris, java.lang.Iterable<java.net.URI> fallbackUris, UrlConnectionExpiryCalculator urlConnectionExpiryCalculator, UrlConnectionSecurityDomainProvider urlConnectionSecurityDomainProvider)` Creates a new module script provider that loads modules against a set of privileged and fallback URIs.

  - ### 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` | `loadFromActualUri(java.net.URI uri, java.net.URI base, java.lang.Object validator)`
    `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 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.
    `protected void` | `onFailedClosingUrlConnection(java.net.URLConnection urlConnection, java.io.IOException cause)` Override if you want to get notified if the URL connection fails to close.
    `protected java.net.URLConnection` | `openUrlConnection(java.net.URL url)` Can be overridden in subclasses to customize the URL connection opening process.

    - ### Methods inherited from class org.mozilla.javascript.commonjs.module.provider.ModuleSourceProviderBase

      `loadSource, loadSource`

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

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

- - ### Constructor Detail

    - #### UrlModuleSourceProvider

          public UrlModuleSourceProvider(java.lang.Iterable<java.net.URI> privilegedUris,
                                 java.lang.Iterable<java.net.URI> fallbackUris)

      Creates a new module script provider that loads modules against a set of privileged and fallback URIs. It will use a fixed default cache expiry of 60 seconds, and provide no security domain objects for the resource.
      Parameters:
        `privilegedUris` - an iterable providing the privileged URIs. Can be null if no privileged URIs are used.
        `fallbackUris` - an iterable providing the fallback URIs. Can be null if no fallback URIs are used.

    - #### UrlModuleSourceProvider

          public UrlModuleSourceProvider(java.lang.Iterable<java.net.URI> privilegedUris,
                                 java.lang.Iterable<java.net.URI> fallbackUris,
                                 UrlConnectionExpiryCalculator urlConnectionExpiryCalculator,
                                 UrlConnectionSecurityDomainProvider urlConnectionSecurityDomainProvider)

      Creates a new module script provider that loads modules against a set of privileged and fallback URIs. It will use the specified heuristic cache expiry calculator and security domain provider.
      Parameters:
        `privilegedUris` - an iterable providing the privileged URIs. Can be null if no privileged URIs are used.
        `fallbackUris` - an iterable providing the fallback URIs. Can be null if no fallback URIs are used.
        `urlConnectionExpiryCalculator` - the calculator object for heuristic calculation of the resource expiry, used when no expiry is provided by the server of the resource. Can be null, in which case the maximum age of cached entries without validation will be zero.
        `urlConnectionSecurityDomainProvider` - object that provides security domain objects for the loaded sources. Can be null, in which case the loaded sources will have no security domain associated with them.

  - ### Method Detail

    - #### loadFromPrivilegedLocations

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

      Description copied from class: `ModuleSourceProviderBase`
      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.
      Overrides:
        `loadFromPrivilegedLocations` in class `ModuleSourceProviderBase`
      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

      Description copied from class: `ModuleSourceProviderBase`
      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.
      Overrides:
        `loadFromFallbackLocations` in class `ModuleSourceProviderBase`
      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.

    - #### loadFromUri

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

      Description copied from class: `ModuleSourceProviderBase`
      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.
      Specified by:
        `loadFromUri` in class `ModuleSourceProviderBase`
      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

    - #### loadFromActualUri

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

      Throws:
        `java.io.IOException`

    - #### onFailedClosingUrlConnection

          protected void onFailedClosingUrlConnection(java.net.URLConnection urlConnection,
                                          java.io.IOException cause)

      Override if you want to get notified if the URL connection fails to close. Does nothing by default.
      Parameters:
        `urlConnection` - the connection
        `cause` - the cause it failed to close.

    - #### openUrlConnection

          protected java.net.URLConnection openUrlConnection(java.net.URL url)
                                                      throws java.io.IOException

      Can be overridden in subclasses to customize the URL connection opening process. By default, just calls `URL.openConnection()`.
      Parameters:
        `url` - the URL
      Returns:
        a connection to the URL.
      Throws:
        `java.io.IOException` - if an I/O error occurs.

    - #### entityNeedsRevalidation

          protected boolean entityNeedsRevalidation(java.lang.Object validator)

      Description copied from class: `ModuleSourceProviderBase`
      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.
      Overrides:
        `entityNeedsRevalidation` in class `ModuleSourceProviderBase`
      Parameters:
        `validator` - the validator
      Returns:
        returns true if the cached module needs revalidation.