Class WebMap

java.lang.Object
org.bzdev.ejws.WebMap
Direct Known Subclasses:
DirWebMap, PropertiesWebMap, RedirectWebMap, ResourceWebMap, ServletWebMap, URLWebMap, ZipWebMap

public abstract class WebMap extends Object
Base class for mapping URIs to resources. For details on the format of a WEB-INF/web.xml file, please see web.xml Deployment Descriptor Elements. WebMap recognizes the following elements:
  • web-app
    • mime-mapping
      • extension
      • mime-type
    • welcome-file-list
      • welcome-file
    • error-page
      • exception-code
      • exception-type
      • location
    • jsp-config
      • jsp-property-group
        • url-pattern
        • page-encoding
        • is-xml
Other cases are ignored.

Subclasses of WebMap are expected to have a single-argument constructor that accepts an Object as its sole argument. The method getInfoFromPath(String,String,String,String,WebMap.RequestInfo) must be implemented. Essentially, this method returns a WebMap.Info object that representing a response to an HTTP request.

The constructor for a subclass should call setMethods(HttpMethod...methods) to change the methods it supports from the default (HEAD and GET), and setAllowsQuery(boolean) if queries are allowed (by default they are not allowed).

  • Constructor Details

    • WebMap

      public WebMap()
  • Method Details

    • setMethods

      protected void setMethods(HttpMethod... methods)
      Indicate the methods this WebMap can implement If not called, this web map can implement HttpMethod.TRACE, HttpMethod.HEAD, and HttpMethod.GET. When this method is called, the list of methods is cleared and the method HttpMethod.TRACE is automatically added whether or not it is present in the argument list.
      Parameters:
      methods - the HTTP methods that this web map can implement
    • acceptsMethod

      public boolean acceptsMethod(HttpMethod method)
      Indicate if this WebMap can implement a specified HTTP method.
      Parameters:
      method - the method
      Returns:
      true if this WebMap accepts the method; false otherwise.
    • getWelcomeList

      protected LinkedList<String> getWelcomeList()
      Get the list of welcome pages associated with this web map.
      Returns:
      a list of welcome pages.
    • getSuffixToMimeTypeMap

      protected HashMap<String,String> getSuffixToMimeTypeMap()
      Get the HashMap associating media types with file-name extensions.
      Returns:
      the map
    • setAllowsQuery

      protected void setAllowsQuery(boolean value)
      Set whether or not queries are allowed.
      Parameters:
      value - true if queries are allowed; false otherwise.
    • allowsQuery

      public boolean allowsQuery()
      Indicate if a URI from an HTTP request can contain a query.
      Returns:
      true if queries are allowed; false otherwise
    • getDisplayDir

      public boolean getDisplayDir()
      Indicate if a directory should be displayed when pointing to a directory. The directory will be provided as an HTML page. Subclasses should use this method to determine whether or not a directory page should be generated.
      Returns:
      true if a directory should be displayed; false otherwise
    • setDisplayDir

      public void setDisplayDir(boolean value)
      Set whether or not a directory should be displayed when pointing to a directory. The directories will be provided as HTML pages during periods in which the argument is true. Note that this setting effects all HTTP requests. Attempts to change the setting for particular requests can cause unpredictable behavior due to race conditions.
      Parameters:
      value - true if a directory should be displayed; false otherwise
    • asHeaderOps

      public static HeaderOps asHeaderOps(Headers headers)
      Convert an instance of Headers to an instance of HeaderOps.
      Parameters:
      headers - the headers
      Returns:
      the converted object
    • setErrorColors

      protected void setErrorColors(String foregroundColor, String backgroundColor)
      Set the foreground and background colors for error pages. This will be called by EmbeddedWebServer when the server starts.
      Parameters:
      foregroundColor - the CSS foreground color
      backgroundColor - the CSS background color
      See Also:
    • getErrorForegroundColor

      public String getErrorForegroundColor()
      Get the foreground color for error pages. The value is a string following the CSS specification.
      Returns:
      the foreground color
    • getErrorBackgroundColor

      public String getErrorBackgroundColor()
      Get the background color for error pages. The value is a string following the CSS specification.
      Returns:
      the background color
    • newInstance

      public static WebMap newInstance(Object root, String className) throws IOException, IllegalArgumentException
      Create a new instance of a WebMap subclass given a class name.
      Parameters:
      root - a parameter used by the subclass' constructor
      className - the name of the subclass
      Returns:
      the new web map
      Throws:
      IOException - an IO error occurred
      IllegalArgumentException - an argument prevented this method from running
    • newInstance

      public static WebMap newInstance(Object root, Class<? extends WebMap> clasz) throws IOException, IllegalArgumentException
      Create a new instance of a WebMap subclass. A constructor for the specified class we be invoked, using root as its single argument. Subclasses of WebMap should define a constructor that takes an Object as its sole argument. Each subclass will specify details for the objects the subclass' constructor accepts.
      Parameters:
      root - a parameter used by the subclass' constructor
      clasz - the class of the new instance
      Returns:
      the new web map
      Throws:
      IOException - an IO error occurred
      IllegalArgumentException - an argument prevented this method from running
    • getWebxml

      public WebMap.Info getWebxml() throws IOException
      Get the WebMap.Info object for the WEB-INF/web.xml file associated with this instance of WebMap. This method is called when a constructor for FileHandler is executing.
      Returns:
      an instance of Info containing an input stream for reading the web.xml file; null if none exists.
      Throws:
      IOException - an IO error occurred.
    • welcomeInfoAvailable

      public boolean welcomeInfoAvailable()
      Determine if a welcome-file has been defined for this web map.
      Returns:
      true if a welcome file has been defined; false otherwise
    • getWelcomeInfo

      public WebMap.Info getWelcomeInfo() throws IOException
      Find a "welcome' file. A welcome file is defined in the JSP Web Archive specification, and specifies a default file to use for a web site, so that one is not dependent on server-specific conventions such as naming a 'welcome' file index.html. The method addWelcome(String) adds possible welcome file locations.
      Returns:
      an instance of Info containing an input stream for reading the "welcome" file; null if none exists.
      Throws:
      IOException - an IO error occurred
    • getWelcomeInfo

      @Deprecated public WebMap.Info getWelcomeInfo(String base) throws IOException
      Deprecated.
      this method is not needed.
      Find a "welcome' file given a base directory path. A welcome file is defined in the JSP Web Archive specification, and specifies a default file to use for a web site, so that one is not dependent on server-specific conventions such as naming a 'welcome' file index.html. The method addWelcome(String) adds possible welcome file locations.

      Parameters:
      base - the path (which must end in "/").
      Returns:
      an instance of Info containing an input stream for reading the "welcome" file; null if none exists.
      Throws:
      IOException - an IO error occurred
    • getEmap

      protected HashMap<Object,String> getEmap()
      The mapping between an error type and a location
      Returns:
      the map
      See Also:
    • getInfoFromPath

      protected WebMap.Info getInfoFromPath(String path) throws IOException, EjwsException
      Convenience method for obtaining an Info object for a resource given a path. The prepath is assumed to be null (indicating "/" as the root), and the query and fragment portions are assumed to be null. This method just calls getInfoFromPath(null, path, null, null). A prepath is typically the path associated with an HTTP Context - the portion of the path that determines which HTTP handler to use. The remainder is the portion of the path that used as a key to find an actual resource: i.e., the path relative to the root object used to create the web map.
      Parameters:
      path - the path portion of a URI
      Returns:
      an Info specifying
      Throws:
      IOException - an IO error occurred.
      EjwsException - an ejws exception occurred
      See Also:
    • getInfoFromPath

      protected abstract WebMap.Info getInfoFromPath(String prepath, String path, String query, String fragment, WebMap.RequestInfo requestInfo) throws IOException, EjwsException
      Get an Info object for a resource The prepath argument is typically the path associated with an HTTP Context - the portion of the path that determines which HTTP handler to use. The remainder is the portion of the path that used as a key to find an actual resource: i.e., the path relative to the root object used to create the web map.

      Note: This method does not determine compression

      Parameters:
      prepath - the initial portion of the request URI (the root URI path - or prefix - for the corresponding file handler)
      path - the remainder of the path portion of a URI (the part that may differ between URL's passed to this object)
      query - the query portion of a URL
      fragment - the fragment portion of a URI
      requestInfo - an object encapsulating request data (headers, input streams, etc.)
      Returns:
      an Info object either describing properties of a resource (e.g., headers, content-length, and a response code) and providing an input stream for that resource or handling a request directly; null if the requested resource could not be found and the caller should handle the error
      Throws:
      IOException - an IO error occurred.
      EjwsException - an ejws exception occurred
    • getErrorInfo

      public WebMap.Info getErrorInfo(int code, String protocol, HttpExchange t) throws IOException, EjwsException
      Get Info for an error document via a convenience method.
      Parameters:
      code - the HTTP response code
      protocol - the protocol (HTTP or HTTPS) for the request
      t - the HTTP exchange initiating the request
      Returns:
      an Info object describing properties of a resource (e.g., headers, content-length, and the response code for an HTML page describing an error) and providing an input stream for that resource
      Throws:
      IOException - an IO error occurred.
      EjwsException - an ejws exception, which may be thrown by getInfoFromPath, occurred
      See Also:
    • getErrorInfo

      public WebMap.Info getErrorInfo(int code, Object key, String protocol, HttpExchange t) throws IOException, EjwsException
      Get Info for an error document.
      Parameters:
      code - the HTTP response code
      key - an object (e.g., a Throwable) describing the error
      protocol - the protocol (http or https) for the request
      t - the HTTP exchange initiating the request
      Returns:
      an Info object describing properties of a resource (e.g., headers, content-length, and the response code for an HTML page describing an error) and providing an input stream for that resource
      Throws:
      IOException - an IO error occurred.
      EjwsException - an ejws exception, which may be thrown by getInfoFromPath, occurred
      See Also:
    • getErrorInfo

      public WebMap.Info getErrorInfo(String exceptionType) throws IOException, EjwsException
      Get Info for an error document given the class name of an exception.
      Parameters:
      exceptionType - the class name of an exception
      Returns:
      an Info object describing properties of a resource (e.g., headers, content-length, and the response code for an HTML page describing an error) and providing an input stream for that resource
      Throws:
      IOException - an IO error occurred.
      EjwsException - an ejws exception, which may be thrown by getInfoFromPath, occurred
      See Also:
    • setWebInfHidden

      public void setWebInfHidden(boolean value)
      Set the webInfHidden flag. When an HTTP request's URI's path starts with CONTEXT_PATH/WEB-INF, where CONTEXT_PATH is the path associated with the current object's FileHandler, getInfo by default returns null. This method allows the default behavior to be overridden.
      Parameters:
      value - true if the WEB-INF directory should be hidden; false otherwise
    • getWebInfHidden

      public boolean getWebInfHidden()
      Get the webInfHidden flag. When an HTTP request's URI's path starts with CONTEXT_PATH/WEB-INF, where CONTEXT_PATH is the path associated with the current object's FileHandler, getInfo by default returns null, unless setWebInfHidden was last called with a value of false.
      Returns:
      true if the WEB-INF directory and its subdirectories and contents can be returned by a call got getInfo; false otherwise
      See Also:
    • getInfo

      public WebMap.Info getInfo(URI uri) throws IOException, EjwsException
      Get an Info object for a resource. In this case, the 'prepath' argument that some other getInfo methods provide is assumed to be null.
      Parameters:
      uri - the URI naming a resource
      Returns:
      an Info object describing properties of a resource an providing an input stream to the resource
      Throws:
      IOException - an IO error occurred.
      EjwsException - an ejws exception, which may be thrown by getInfoFromPath, occurred
      See Also:
    • getInfo

      public WebMap.Info getInfo(String prepath, HttpExchange t) throws IOException, EjwsException
      Get an Info object for a request. A prepath argument is typically the path associated with an HTTP Context - the portion of the path that determines which HTTP handler to use. The remainder is the portion of the path that used as a key to find an actual resource: i.e., the path relative to the root object used to create the web map. This will be removed from the request URI's path. If the prepath argument does not end in "/", a "/" will be automatically added.
      Parameters:
      prepath - the initial portion of a path from the request URI
      t - the request-response object.
      Returns:
      an Info object describing properties of a resource an providing an input stream to the resource
      Throws:
      IOException - an IO error occurred.
      EjwsException - an ejws exception, which may be thrown by getInfoFromPath, occurred
      See Also:
    • getInfo

      public WebMap.Info getInfo(String prepath, URI uri) throws IOException, EjwsException
      Get an Info object for a resource. A prepath argument is typically the path associated with an HTTP Context - the portion of the path that determines which HTTP handler to use. The remainder is the portion of the path that used as a key to find an actual resource: i.e., the path relative to the root object used to create the web map. This will be removed from the request URI's path. If the prepath argument does not end in "/", a "/" will be automatically added.
      Parameters:
      prepath - the initial portion of a path from the request URI
      uri - the request URI naming a resource
      Returns:
      an Info object describing properties of a resource an providing an input stream to the resource
      Throws:
      IOException - an IO error occurred.
      EjwsException - an ejws exception, which may be thrown by getInfoFromPath, occurred
      See Also:
    • getInfo

      public WebMap.Info getInfo(String path) throws IOException, EjwsException
      Get an Info object for a resource given a path. This method calls getInfo(null, path, null, null) after stripping any leading "/" from the path.
      Parameters:
      path - the path in a URI requesting a resource
      Returns:
      an Info object describing properties of a resource an providing an input stream to the resource
      Throws:
      IOException - an IO error occurred.
      EjwsException - an ejws exception, which may be thrown by getInfoFromPath, occurred
      See Also:
    • getInfo

      public WebMap.Info getInfo(String prepath, String path) throws IOException, EjwsException
      Get an Info object for a resource given a path using a prepath. This method calls getInfoFromPath(prepath, path, null, null) after stripping off any leading "/" from path.
      Parameters:
      prepath - the initial portion of a path from the request URI
      path - the path in a URI requesting a resource
      Returns:
      an Info object describing properties of a resource an providing an input stream to the resource
      Throws:
      IOException - an IO error occurred.
      EjwsException - an ejws exception, which may be thrown by getInfoFromPath, occurred
      See Also:
    • addWelcome

      public void addWelcome(String path)
      Add a path to the list of paths to 'welcome' files/resources. This method is called by WebxmlParser so when a WEB-INF/web.xml file exists, users or subclasses would generally not use this method explicitly. Note that, when a WEB-INF/web.xml file exists, a WebxmlParser will be created and called by a FileHandler's constructor.

      The paths are relative to the base URL for this web map and should not contain a "/" if the welcome page contains relative links.

      Parameters:
      path - the path to add
    • stripGZipSuffix

      public String stripGZipSuffix(String path)
      Remove a GZIP suffix from a path. The default provides .gz as the suffix.
      Parameters:
      path - the path
      Returns:
      the path without the suffix
      See Also:
    • getMimeType

      public String getMimeType(String path)
      Get the MIME type for a resource given its path. The default implementation bases the mime type on a file suffix.
      Parameters:
      path - the path to the resource
      Returns:
      the resource's MIME type; application/octet-stream if the MIME type cannot be definitively determined.
    • addMapping

      public void addMapping(String suffix, String mtype)
      Add a mapping between a file-name/path suffix and a MIME type. The suffix is the portion of a file name or path that follows the last '.' in the last component of the path or file name. This method is called by WebxmlParser so when a WEB-INF/web.xml file exists, users or subclasses would generally not use this method explicitly. Note that, when a WEB-INF/web.xml file exists, a WebxmlParser will be created and called by a FileHandler's constructor.

      The suffix should not start with a period—if it does, the period will be removed.

      Parameters:
      suffix - the file name or path suffix
      mtype - the corresponding MIME type
    • addGzipSuffix

      public void addGzipSuffix(String suffix)
      Add a file-name/path suffix that indicates the use of gzip compression.

      The suffix should not start with a period—if it does, the period will be removed.

      Parameters:
      suffix - the suffix
    • gzipPaths

      public Iterable<String> gzipPaths(String path)
      Create an iterable that will provide a sequence of paths that are modified by adding a suffix indicating gzip compression.
      Parameters:
      path - the original path
      Returns:
      an iterable providing a sequence of modified paths.
    • addErrorEntry

      public void addErrorEntry(Object key, String location)
      Add a mapping between an error type and the location of the resource describing the error. A key can be either an Integer whose value is an HTTP error code or a String giving the class name of an Exception or Throwable as returned by that object's class' method getName(). The location will be resolved against the root for this web map to find the actual resource. This method is called by WebxmlParser so when a WEB-INF/web.xml file exists, users or subclasses would generally not use this method explicitly. Note that, when a WEB-INF/web.xml file exists, a WebxmlParser will be created and called by a FileHandler's constructor.
      Parameters:
      key - an object indicating the error type
      location - the path for the resource describing the error
    • addPageEncoding

      public void addPageEncoding(String pattern, String encoding, boolean isxml)
      Add page encoding data for JSP pages. This method creates a list of URL patterns for JSP pages that define the text encoding to use for pages that that match the pattern. This method is called by WebxmlParser so when a WEB-INF/web.xml file exists, users or subclasses would generally not use this method explicitly. Note that, when a WEB-INF/web.xml file exists, a WebxmlParser will be created and called by a FileHandler's constructor.
      Parameters:
      pattern - a URL pattern for the path component of a URL as described in the servlet specification
      encoding - the character encoding to use
      isxml - true if the JSP page produces an XML document; false for an HTML document
    • addPageEncoding

      public void addPageEncoding(LinkedList<String> patterns, String encoding, boolean isxml)
      Add page encoding data for JSP pages given a list of patterns.
      Parameters:
      patterns - a list of URL patterns for the path component of a URL as described in the servlet specification
      encoding - the character encoding to use
      isxml - true if the JSP page produces an XML document; false for an HTML document
    • getContentTypeFromURL

      public String getContentTypeFromURL(String urlString)
      Get the content type for a JSP page given its path.
      Parameters:
      urlString - the path to the JSP page
      Returns:
      "application/xml" or "text/html"
    • getEncodingFromURL

      public String getEncodingFromURL(String urlString)
      Get the character encoding for a JSP page given its path.
      Parameters:
      urlString - the path to the JSP page
      Returns:
      the character encoding
    • getFromHeader

      public static String getFromHeader(HeaderOps headers, String key, String parameter)
      Extract parameters from a header. This method assumes single-valued headers and the normal header syntax.
      Parameters:
      headers - the headers
      key - the name of the header (e.g., "content-type")
      parameter - the name of a header parameter (e.g., "charset"); null for the header without its parameters
      Returns:
      the value with quotes and character escapes processed
    • configure

      protected void configure() throws Exception
      Configure a web map. Calling this method should initialize or obtain any resources that the web map will use.

      Subclasses implementing this method must call super.configure() and should do that before performing any subclass-specific actions. If an exception occurs in the configure() method of a subclass, that exception will be handled by EmbeddedWebServer by calling deconfigure(). A consequence of this is that the subclass should track what has actually been configured at each step so that the configuration can be undone safely.

      Throws:
      Exception - an error occurred
      See Also:
    • deconfigure

      protected void deconfigure()
      Deconfigure a web map. Calling this method should release any resources that the web map is using.

      Subclasses implementing this method must call super.deconfigure() and should do that after performing any subclass-specific actions.

      See Also: