org.xmlresolver.ResolvedResource Maven / Gradle / Ivy

Go to download
package org.xmlresolver;

import org.xmlresolver.sources.ResolverResourceInfo;

import java.io.InputStream;
import java.net.URI;
import java.util.Collections;
import java.util.List;
import java.util.Map;

/** A resolved resource represents a successfully resolved resource.
 *
 * While the {@link XMLCatalogResolver} interface simply maps from request parameters to URIs,
 * the resolver interfaces defined by SAX, DOM, etc. expect open streams to be returned. This
 * abstract class provides the information necessary to support those APIs.
 *
 * The "local" URI is always the URI returned by catalog resolution.
 * The "resolved" URI is almost always the same.
 * They can be different when catalog resolution returns a jar: or
 * classpath: URI. Those schemes are not supported by the {@link
 * java.net.URI} class in a useful way. This will cause problems if the
 * document returned contains relative URI references. Consider this
 * XSLT stylesheet:
 *
 * <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 *                 version="3.0">
 *
 * <xsl:import href="module.xsl"/>
 *
 * </xsl:stylesheet>
 *
 * Suppose that it is referenced with the URI http://example.com/xsl/style.xsl
 * and the catalog contains this matching entry:
 *
 * 
<uri name="http://example.com/xsl/style.xsl"
 *      uri="classpath:xsl/style.xsl"/>
 *
 * (An explicit classpath: URI is not the only way for this to arise, if
 * the URI was simply relative to the catalog and the catalog happened to
 * be found with a jar: or classpath: URI, that would have the same
 * effect.)
 *
 * If classpath:xsl/style.xsl is returned as the resolved URI, the XSLT
 * processor will attempt to resolve module.xsl against that as the base
 * URI. If this is done with just the resolve() method on URI, it won’t
 * work. {@link java.net.URI} doesn’t recognize classpath: as a relative
 * URI scheme. The situation is even worse with jar: URIs which have a
 * syntax that is possibly not even sanctioned by the relevant RFCs.
 *
 * In this case, the resolver might choose to return
 * http://example.com/xsl/style.xsl as the resolved URI. The XSLT processor
 * will then form http://example.com/xsl/module.xsl as the URI of the module
 * and, if the catalog author provided an entry for that as well, processing
 * can continue with all of the URIs resolved locally.
 */

public abstract class ResolvedResource implements ResolverResourceInfo {
    /** The resolved URI.
     *
     * This is the URI that should be reported as the resolved URI.
     *
     * @return The resolved URI.
     */
    public abstract URI getResolvedURI();

    /** The local URI.
     *
     * This is the URI that was used to retrieve the resource (to open the input stream). This
     * is usually, but not necessarily always, the same as the resolved URI.
     *
     * @return The local URI.
     */
    public abstract URI getLocalURI();

    /** The input stream.
     *
     * This is the input stream containing the resolved resource. This may return null, in which
     * case it is the application's responsibily to access the resource through its resolved URI.
     *
     * @return The input stream that will return the content of the resolved resource.
     */
    public abstract InputStream getInputStream();

    /** The content type of the resource.
     *
     * If the resolver knows the content type of the resource
     * (for example application/xml), it will be provided here.
     *
     * @return The content type, possibly null.
     */
    public abstract String getContentType();

    /** The status code.
     *
     * This is the status code for this resource. For http: requests, it should be the
     * code returned. For other resource types, it defaults to 200 for convenience.
     *
     * @return The status code of the (final) request.
     */
    public int getStatusCode() {
        return 200;
    }

    /** The headers.
     *
     * This is the set of headers returned for the resolved resource. This may be empty, for example,
     * if the URI was a file: URI. The headers are returned unchanged from the URLConnection,
     * so accessing them has to consider the case-insensitive nature of header names.
     *
     * @return The headers associated with a resource.
     */
    public Map> getHeaders() {
        return Collections.emptyMap();
    }
}