org.mozilla.javascript.commonjs.module.provider.ModuleSourceProvider Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of rhino Show documentation
Rhino is an open-source implementation of JavaScript written entirely in Java. It is typically embedded into Java applications to provide scripting to end users.
The newest version!
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

package org.mozilla.javascript.commonjs.module.provider;

import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;

import org.mozilla.javascript.Scriptable;

/**
 * Implemented by objects that can provide the source text for the script. The
 * design of the interface supports cache revalidation.
 * @author Attila Szegedi
 * @version $Id: ModuleSourceProvider.java,v 1.3 2011/04/07 20:26:12 hannes%helma.at Exp $
 */
public interface ModuleSourceProvider
{
    /**
     * A special return value for {@link #loadSource(String, Scriptable,
     * Object)} and {@link #loadSource(URI, URI, Object)} that signifies that the
     * cached representation is still valid according to the passed validator.
     */
    public static final ModuleSource NOT_MODIFIED = new ModuleSource(null,
            null, null, null, null);

    /**
     * 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 {@link #NOT_MODIFIED} should be returned. Otherwise, it should
     * return a {@link ModuleSource} object with the actual source text of the
     * module, preferrably a validator for it, and a security domain, where
     * applicable.
     * @param moduleId the ID of the module. An implementation must only accept
     * an absolute ID, starting with a term.
     * @param 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.
     * @param 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 {@link ModuleSource}. It can be used to
     * validate the existing cached module and avoid reloading it.
     * @return a script representing the code of the module. Null should be
     * returned if the script is not found. {@link #NOT_MODIFIED} should be
     * returned if the passed validator validates the current representation of
     * the module (the currently cached module script).
     * @throws IOException if there was an I/O problem reading the script
     * @throws URISyntaxException if the final URI could not be constructed.
     * @throws IllegalArgumentException if the module ID is syntactically not a
     * valid absolute module identifier.
     */
    public ModuleSource loadSource(String moduleId, Scriptable paths, Object validator)
            throws IOException, 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 {@link #NOT_MODIFIED}
     * should be returned. Otherwise, it should return a {@link ModuleSource}
     * object with the actual source text of the module, preferrably a
     * validator for it, and a security domain, where applicable.
     * @param uri the absolute URI from which to load the module source, but
     * without an extension such as ".js".
     * @param baseUri the module path base URI from which uri
     * was derived.
     * @param 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 {@link ModuleSource}. It can be used to
     * validate the existing cached module and avoid reloading it.
     * @return a script representing the code of the module. Null should be
     * returned if the script is not found. {@link #NOT_MODIFIED} should be
     * returned if the passed validator validates the current representation of
     * the module (the currently cached module script).
     * @throws IOException if there was an I/O problem reading the script
     * @throws URISyntaxException if the final URI could not be constructed
     */
    public ModuleSource loadSource(URI uri, URI baseUri, Object validator)
            throws IOException, URISyntaxException;
}