tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ma...@apache.org
Subject svn commit: r1382551 - in /tomcat/sandbox/trunk-resources/java/org/apache/catalina: WebResource.java WebResourceRoot.java WebResourceSet.java
Date Sun, 09 Sep 2012 18:14:23 GMT
Author: markt
Date: Sun Sep  9 18:14:22 2012
New Revision: 1382551

URL: http://svn.apache.org/viewvc?rev=1382551&view=rev
Log:
Initial definition of new resources API

Added:
    tomcat/sandbox/trunk-resources/java/org/apache/catalina/WebResource.java   (with props)
    tomcat/sandbox/trunk-resources/java/org/apache/catalina/WebResourceRoot.java   (with props)
    tomcat/sandbox/trunk-resources/java/org/apache/catalina/WebResourceSet.java   (with props)

Added: tomcat/sandbox/trunk-resources/java/org/apache/catalina/WebResource.java
URL: http://svn.apache.org/viewvc/tomcat/sandbox/trunk-resources/java/org/apache/catalina/WebResource.java?rev=1382551&view=auto
==============================================================================
--- tomcat/sandbox/trunk-resources/java/org/apache/catalina/WebResource.java (added)
+++ tomcat/sandbox/trunk-resources/java/org/apache/catalina/WebResource.java Sun Sep  9 18:14:22
2012
@@ -0,0 +1,134 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina;
+
+import java.io.InputStream;
+import java.net.URL;
+
+/**
+ * Represents a file or directory within a web application. It borrows heavily
+ * from {@link java.io.File}.
+ */
+public interface WebResource {
+    /**
+     * See {@link java.io.File#lastModified()}.
+     */
+    long getLastModified();
+
+    /**
+     * Return the last modified time of this resource in the correct format for
+     * the HTTP Last-Modified header as specified by RFC 2616.
+     */
+    String getLastModifiedHttp();
+
+    /**
+     * See {@link java.io.File#exists()}.
+     */
+    boolean exists();
+
+    /**
+     * See {@link java.io.File#isDirectory()}.
+     */
+    boolean isDirectory();
+
+    /**
+     * See {@link java.io.File#isFile()}.
+     */
+    boolean isFile();
+
+    /**
+     * See {@link java.io.File#delete()}.
+     */
+    boolean delete();
+
+    /**
+     * See {@link java.io.File#getName()}.
+     */
+    String getName();
+
+    /**
+     * See {@link java.io.File#length()}.
+     */
+    long getContentLength();
+
+    /**
+     * See {@link java.io.File#getCanonicalPath()}.
+     */
+    String getCanonicalPath();
+
+    /**
+     * See {@link java.io.File#canRead()}.
+     */
+    boolean canRead();
+
+    /**
+     * The path of this resource relative to the web application root.
+     */
+    String getWebappPath();
+
+    /**
+     * Return the strong ETag if available (currently not supported) else return
+     * the weak ETag calculated from the content length and last modified.
+     *
+     * @return  The ETag for this resource
+     */
+    String getETag();
+
+    /**
+     * Set the MIME type for this Resource.
+     * TODO: Previous implementation cached this
+     */
+    void setMimeType(String mimeType);
+
+    /**
+     * Get the MIME type for this Resource.
+     * TODO: Previous implementation cached this
+     */
+    String getMimeType();
+
+    /**
+     * Obtain an InputStream based on the contents of this resource.
+     *
+     * @return  An InputStream based on the contents of this resource or
+     *          <code>null</code> if the resource does not exist or does not
+     *          represent a file
+     */
+    InputStream getInputStream();
+
+    /**
+     * Obtain the cached binary content of this resource.
+     */
+    byte[] getContent();
+
+    /**
+     * The time the file was created. If not available, the result of
+     * {@link #getLastModified()} will be returned.
+     */
+    long getCreation();
+
+    /**
+     * Obtain a URL to access the resource or <code>null</code> if no such URL
+     * is available.
+     */
+    URL getURL();
+
+    /**
+     * Obtain a reference to the WebResourceRoot of which this WebResource is a
+     * part.
+     */
+    WebResourceRoot getWebResourceRoot();
+}

Propchange: tomcat/sandbox/trunk-resources/java/org/apache/catalina/WebResource.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: tomcat/sandbox/trunk-resources/java/org/apache/catalina/WebResourceRoot.java
URL: http://svn.apache.org/viewvc/tomcat/sandbox/trunk-resources/java/org/apache/catalina/WebResourceRoot.java?rev=1382551&view=auto
==============================================================================
--- tomcat/sandbox/trunk-resources/java/org/apache/catalina/WebResourceRoot.java (added)
+++ tomcat/sandbox/trunk-resources/java/org/apache/catalina/WebResourceRoot.java Sun Sep 
9 18:14:22 2012
@@ -0,0 +1,210 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina;
+
+import java.io.File;
+import java.io.InputStream;
+import java.net.URL;
+import java.util.Set;
+
+/**
+ * Represents the complete set of resources for a web application. The resources
+ * for a web application comprise of multiple ResourceSets and when looking for
+ * a Resource, the ResourceSets are processed in the following order:
+ * <ol>
+ * <li>Pre  - Resources defined by the &lt;PreResource&gt; element in the web
+ *            application&apos;s context.xml. Resources will be searched in the
+ *            order they were specified.</li>
+ * <li>Main - The main resources for the web application - i.e. the WAR or the
+ *            directory containing the expanded WAR</li>
+ * <li>JARs - Resource JARs as defined by the Servlet specification. JARs will
+ *            be searched in the order they were added to the ResourceRoot.</li>
+ * <li>Post - Resources defined by the &lt;PostResource&gt; element in the
web
+ *            application&apos;s context.xml. Resources will be searched in the
+ *            order they were specified.</li>
+ * </ol>
+ * The following conventions should be noted:
+ * <ul>
+ * <li>Write operations (including delete) will only be applied to the main
+ *     ResourceSet. The write operation will fail if the presence of a Resource
+ *     in one of the other ResourceSets effectively makes the operation on the
+ *     main ResourceSet a NO-OP.</li>
+ * <li>A file in a ResourceSet will hide a directory of the same name (and all
+ *     the contents of that directory) in a ResourceSet that is later in the
+ *     search order.</li>
+ * <li>Only the main ResourceSet may define a META-INF/context.xml since that
+ *     file defines the Pre- and Post-Resources.</li>
+ * <li>As per the Servlet specification, any META-INF or WEB-INF directories in
+ *     a resource JAR will be ignored.</li>
+ * <li>Pre- and Post-Resources may define WEB-INF/lib and WEB-INF/classes in
+ *     order to make additional libraries and/or classes available to the web
+ *     application.
+ * </ul>
+ * This mechanism replaces and extends the following features that were present
+ * in earlier versions:
+ * <ul>
+ * <li>Aliases               - Replaced by Post-Resources with the addition of
+ *                             support for single files as well as directories
+ *                             and JARs.</li>
+ * <li>VirtualWebappLoader   - Replaced by Pre- and Post-Resources mapped to
+ *                             WEB-INF/lib and WEB-INF/classes</li>
+ * <li>VirtualDirContext     - Replaced by Pre- and Post-Resources</li>
+ * <li>External repositories - Replaced by Pre- and Post-Resources mapped to
+ *                             WEB-INF/lib and WEB-INF/classes</li>
+ * <li>Resource JARs         - Same feature but implemented using the same
+ *                             mechanism as all the other additional
+ *                             resources.</li>
+ * <li>TBD                   - More to list here</li>
+ * </ul>
+ */
+/*
+ * A potential future enhancement is to allow writing to any ResourceSet,
+ * not just the main ResourceSet although that adds all sorts complications
+ * including:
+ * - which ResourceSet to write to
+ * - unexpected behaviour when deleting a resource from one ResourceSet since
+ *   that may unmask a resource in a lower priority ResouceSet so what was a
+ *   delete looks like a replace with the user having no idea where the 'new'
+ *   resource came from
+ * - how to handle PUT when the target is read-only but it could be written to
+ *   a higher priority ResourceSet that is read-write
+ */
+public interface WebResourceRoot extends Lifecycle {
+    /**
+     * Obtain the object that represents the resource at the given path. Note
+     * that the resource at that path may not exist. If the path does not
+     * exist, the WebResource returned will be associated with the main
+     * WebResourceSet.
+     *
+     * @param path  The path for the resource of interest relative to the root
+     *              of the web application. It must start with '/'.
+     *
+     * @return  The object that represents the resource at the given path
+     */
+    WebResource getResource(String path);
+
+    /**
+     * Obtain the list of the names of all of the files and directories located
+     * in the specified directory.
+     *
+     * @param path  The path for the resource of interest relative to the root
+     *              of the web application. It must start with '/'.
+     *
+     * @return  The list of resources. If path does not refer to a directory
+     *          then a zero length array will be returned.
+     */
+    String[] list(String path);
+
+    /**
+     * Obtain the Set of the web applications pathnames of all of the files and
+     * directories located in the specified directory.
+     *
+     * @param path  The path for the resource of interest relative to the root
+     *              of the web application. It must start with '/'.
+     *
+     * @return  The Set of resources. If path does not refer to a directory
+     *          then an empty set will be returned.
+     */
+    Set<String> listWebAppPaths(String path);
+
+    /**
+     * Obtain the list of all of the WebResources in the specified directory.
+     *
+     * @param path  The path for the resource of interest relative to the root
+     *              of the web application. It must start with '/'.
+     *
+     * @return  The list of resources. If path does not refer to a directory
+     *          then a zero length array will be returned.
+     */
+    WebResource[] listResources(String path);
+
+    /**
+     * Create a new directory at the given path.
+     *
+     * @param path  The path for the new resource to create relative to the root
+     *              of the web application. It must start with '/'.
+     *
+     * @return  <code>true</code> if the directory was created, otherwise
+     *          <code>false</code>
+     */
+    boolean mkdir(String path);
+
+    /**
+     * Create a new resource at the requested path using the provided
+     * InputStream.
+     *
+     * @param path  The path to be used for the new Resource. It is relative to
+     *              the root of the web application and must start with '/'.
+     * @param is    The InputStream that will provide the content for the new
+     *              Resource.
+     *
+     * @return  <code>true</code> if and only if the new Resource is written
+     */
+    boolean write(String path, InputStream is);
+
+    /**
+     * Obtain the unique name for the Context with which these resources are
+     * associated (for logging etc).
+     */
+    String getContextName();
+
+    /**
+     *
+     * @param url   Identifies the root of the new {@link WebResourceSet}. It
+     *              must point to a JAR, directory or file.
+     * @param initialPath   Identifies any initial path (only in a JAR) that
+     *                      must be skipped when matching web application paths
+     *                      to paths in the new {@link WebResourceSet}
+     */
+
+    /**
+     * Creates a new {@link WebResourceSet} for this {@link WebResourceRoot}
+     * based on the provided parameters.
+     *
+     * @param type          The type of {@link WebResourceSet} to create
+     * @param url           The URL of the resource (must locate a JAR, file or
+     *                          directory)
+     * @param webAppPath    The path within the web application that the
+     *                          resources should be published at
+     * @param internalPath  The path within the resource where the content is to
+     *                          be found.
+     */
+    void createWebResourceSet(ResourceSetType type, URL url, String webAppPath,
+            String internalPath);
+
+    /**
+     * Creates a new {@link WebResourceSet} for this {@link WebResourceRoot}
+     * based on the provided parameters.
+     *
+     * @param type          The type of {@link WebResourceSet} to create
+     * @param file          The resource (must be a JAR, file or directory)
+     * @param webAppMount   The path within the web application that the
+     *                          resources should be published at
+     * @param internalPath  The path within the resource where the content is to
+     *                          be found.
+     */
+    void createWebResourceSet(ResourceSetType type, File file,
+            String webAppMount, String internalPath);
+
+    void setAllowLinking(boolean allowLinking);
+
+    public static enum ResourceSetType {
+        PRE,
+        RESOURCE_JAR,
+        POST
+    }
+}

Propchange: tomcat/sandbox/trunk-resources/java/org/apache/catalina/WebResourceRoot.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: tomcat/sandbox/trunk-resources/java/org/apache/catalina/WebResourceSet.java
URL: http://svn.apache.org/viewvc/tomcat/sandbox/trunk-resources/java/org/apache/catalina/WebResourceSet.java?rev=1382551&view=auto
==============================================================================
--- tomcat/sandbox/trunk-resources/java/org/apache/catalina/WebResourceSet.java (added)
+++ tomcat/sandbox/trunk-resources/java/org/apache/catalina/WebResourceSet.java Sun Sep  9
18:14:22 2012
@@ -0,0 +1,85 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina;
+
+import java.io.InputStream;
+import java.util.Set;
+
+/**
+ * Represents a set of resources that are part of a web application. Examples
+ * include a directory structure, a resources JAR and a WAR file.
+ */
+public interface WebResourceSet {
+    /**
+     * Obtain the object that represents the resource at the given path. Note
+     * the resource at that path may not exist.
+     *
+     * @param path  The path for the resource of interest relative to the root
+     *              of the web application. It must start with '/'.
+     *
+     * @return  The object that represents the resource at the given path
+     */
+    WebResource getResource(String path);
+
+    /**
+     * Obtain the list of the names of all of the files and directories located
+     * in the specified directory.
+     *
+     * @param path  The path for the resource of interest relative to the root
+     *              of the web application. It must start with '/'.
+     *
+     * @return  The list of resources. If path does not refer to a directory
+     *          then a zero length array will be returned.
+     */
+    String[] list(String path);
+
+    /**
+     * Obtain the Set of the web applications pathnames of all of the files and
+     * directories located in the specified directory.
+     *
+     * @param path  The path for the resource of interest relative to the root
+     *              of the web application. It must start with '/'.
+     *
+     * @return  The Set of resources. If path does not refer to a directory
+     *          then an empty set will be returned.
+     */
+    Set<String> listWebAppPaths(String path);
+
+    /**
+     * Create a new directory at the given path.
+     *
+     * @param path  The path for the new resource to create relative to the root
+     *              of the web application. It must start with '/'.
+     *
+     * @return  <code>true</code> if the directory was created, otherwise
+     *          <code>false</code>
+     */
+    boolean mkdir(String path);
+
+    /**
+     * Create a new resource at the requested path using the provided
+     * InputStream.
+     *
+     * @param path  The path to be used for the new Resource. It is relative to
+     *              the root of the web application and must start with '/'.
+     * @param is    The InputStream that will provide the content for the new
+     *              Resource.
+     *
+     * @return  <code>true</code> if and only if the new Resource is written
+     */
+    boolean write(String path, InputStream is);
+}

Propchange: tomcat/sandbox/trunk-resources/java/org/apache/catalina/WebResourceSet.java
------------------------------------------------------------------------------
    svn:eol-style = native



---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org


Mime
View raw message