- Direct Known Subclasses:
DirWebMap
,PropertiesWebMap
,RedirectWebMap
,ResourceWebMap
,ServletWebMap
,URLWebMap
,ZipWebMap
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
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).
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic interface
Interface for providing background colors for directory (or similar) listings.static class
Info for accessing a resource.static class
HTTP Request data. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionboolean
acceptsMethod
(HttpMethod method) Indicate if this WebMap can implement a specified HTTP method.void
addErrorEntry
(Object key, String location) Add a mapping between an error type and the location of the resource describing the error.void
addGzipSuffix
(String suffix) Add a file-name/path suffix that indicates the use of gzip compression.void
addMapping
(String suffix, String mtype) Add a mapping between a file-name/path suffix and a MIME type.void
addPageEncoding
(String pattern, String encoding, boolean isxml) Add page encoding data for JSP pages.void
addPageEncoding
(LinkedList<String> patterns, String encoding, boolean isxml) Add page encoding data for JSP pages given a list of patterns.void
addWelcome
(String path) Add a path to the list of paths to 'welcome' files/resources.boolean
Indicate if a URI from an HTTP request can contain a query.static HeaderOps
asHeaderOps
(Headers headers) protected void
Configure a web map.protected void
Deconfigure a web map.getContentTypeFromURL
(String urlString) Get the content type for a JSP page given its path.boolean
Indicate if a directory should be displayed when pointing to a directory.getEmap()
The mapping between an error type and a locationgetEncodingFromURL
(String urlString) Get the character encoding for a JSP page given its path.Get the background color for error pages.Get the foreground color for error pages.getErrorInfo
(int code, Object key, String protocol, HttpExchange t) Get Info for an error document.getErrorInfo
(int code, String protocol, HttpExchange t) Get Info for an error document via a convenience method.getErrorInfo
(String exceptionType) Get Info for an error document given the class name of an exception.static String
getFromHeader
(HeaderOps headers, String key, String parameter) Extract parameters from a header.Get an Info object for a resource given a path.getInfo
(String prepath, HttpExchange t) Get an Info object for a request.Get an Info object for a resource given a path using a prepath.Get an Info object for a resource.Get an Info object for a resource.protected WebMap.Info
getInfoFromPath
(String path) Convenience method for obtaining an Info object for a resource given a path.protected abstract WebMap.Info
getInfoFromPath
(String prepath, String path, String query, String fragment, WebMap.RequestInfo requestInfo) 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.getMimeType
(String path) Get the MIME type for a resource given its path.Get the HashMap associating media types with file-name extensions.boolean
Get the webInfHidden flag.Get the WebMap.Info object for the WEB-INF/web.xml file associated with this instance of WebMap.Find a "welcome' file.getWelcomeInfo
(String base) Deprecated.this method is not needed.protected LinkedList<String>
Get the list of welcome pages associated with this web map.Create an iterable that will provide a sequence of paths that are modified by adding a suffix indicating gzip compression.static WebMap
newInstance
(Object root, Class<? extends WebMap> clasz) Create a new instance of a WebMap subclass.static WebMap
newInstance
(Object root, String className) Create a new instance of a WebMap subclass given a class name.protected void
setAllowsQuery
(boolean value) Set whether or not queries are allowed.void
setDisplayDir
(boolean value) Set whether or not a directory should be displayed when pointing to a directory.protected void
setErrorColors
(String foregroundColor, String backgroundColor) Set the foreground and background colors for error pages.protected void
setMethods
(HttpMethod... methods) Indicate the methods this WebMap can implement If not called, this web map can implementHttpMethod.TRACE
,HttpMethod.HEAD
, andHttpMethod.GET
.void
setWebInfHidden
(boolean value) Set the webInfHidden flag.stripGZipSuffix
(String path) Remove a GZIP suffix from a path.boolean
Determine if a welcome-file has been defined for this web map.
-
Constructor Details
-
WebMap
public WebMap()
-
-
Method Details
-
setMethods
Indicate the methods this WebMap can implement If not called, this web map can implementHttpMethod.TRACE
,HttpMethod.HEAD
, andHttpMethod.GET
. When this method is called, the list of methods is cleared and the methodHttpMethod.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
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
Get the list of welcome pages associated with this web map.- Returns:
- a list of welcome pages.
-
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
- Parameters:
headers
- the headers- Returns:
- the converted object
-
setErrorColors
Set the foreground and background colors for error pages. This will be called byEmbeddedWebServer
when the server starts.- Parameters:
foregroundColor
- the CSS foreground colorbackgroundColor
- the CSS background color- See Also:
-
getErrorForegroundColor
Get the foreground color for error pages. The value is a string following the CSS specification.- Returns:
- the foreground color
-
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' constructorclassName
- the name of the subclass- Returns:
- the new web map
- Throws:
IOException
- an IO error occurredIllegalArgumentException
- 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, usingroot
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' constructorclasz
- the class of the new instance- Returns:
- the new web map
- Throws:
IOException
- an IO error occurredIllegalArgumentException
- an argument prevented this method from running
-
getWebxml
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 forFileHandler
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
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 methodaddWelcome(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.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 methodaddWelcome(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
The mapping between an error type and a location- Returns:
- the map
- See Also:
-
getInfoFromPath
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 URLfragment
- the fragment portion of a URIrequestInfo
- 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 codeprotocol
- the protocol (HTTP or HTTPS) for the requestt
- 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 codekey
- an object (e.g., a Throwable) describing the errorprotocol
- the protocol (http or https) for the requestt
- 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
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
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
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 URIt
- 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
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 URIuri
- 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
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
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 URIpath
- 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
Add a path to the list of paths to 'welcome' files/resources. This method is called byWebxmlParser
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
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
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
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 byWebxmlParser
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 suffixmtype
- the corresponding MIME type
-
addGzipSuffix
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
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
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 byWebxmlParser
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 typelocation
- the path for the resource describing the error
-
addPageEncoding
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 byWebxmlParser
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 specificationencoding
- the character encoding to useisxml
- true if the JSP page produces an XML document; false for an HTML document
-
addPageEncoding
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 specificationencoding
- the character encoding to useisxml
- true if the JSP page produces an XML document; false for an HTML document
-
getContentTypeFromURL
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
Get the character encoding for a JSP page given its path.- Parameters:
urlString
- the path to the JSP page- Returns:
- the character encoding
-
getFromHeader
Extract parameters from a header. This method assumes single-valued headers and the normal header syntax.- Parameters:
headers
- the headerskey
- 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
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 byEmbeddedWebServer
by callingdeconfigure()
. 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()
isConfigured()
-
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:
-
configure()
isConfigured()
-