Dwarf HTTP Server 1.3.3
Dwarf HTTP Server 1.3.3This document explains configuration of the Dwarf HTTP Server using the XML-based configuration feature. See the XML Configuration Guide from the base Dwarf distribution for more information about the subject.
The HTTP Server configuration is static, that means no new virtual hosts or web applications can be configured and added while the server is running.
In the rest of the document we will assume that the whole configuration of the HTTP server resides in a single "http.xml" file. We can then include it to the main server object via the <include ...> element:
<service classbase="SK.gnome.dwarf." class=".main.MainServer" name="Main Server">
<!-- ... ATTRIBUTES ... -->
<!-- ... SERVICES ... -->
<!-- HTTP SERVER -->
<include url="file:conf/http.xml"/>
</service>
From now, we will deal only with the content of the mentioned "http.xml" file.
Each HTTP server is represented by an instance of the HTTPServer class:
<configuration>
<!-- HTTP SERVER -->
<service classbase="SK.gnome.dwarf.http" class=".HTTPServer" name="HTTP Server">
<set name="logFacility">http</set>
<!-- HTTP PARAMETERS -->
<service class=".HTTPParameters" name="HTTP Parameters">
<set name="sendErrors">true</set>
<set name="keepAliveTimeout">20</set>
<set name="requestsPerConnection">50</set>
</service>
<!-- SESSION MANAGER -->
<service class=".RAMSessionManager" name="Session Manager"/>
<!-- TCP LISTENER -->
<service class="SK.gnome.dwarf.tcpip.TCPListener" name="HTTP Listener">
<set name="port">80</set>
</service>
</service>
</configuration>
Let's discuss the server attributes first. The "logFacility" attribute specifies the identification string for the log messages generated by the server. It is a good practice to set an unique log facility for each contained HTTP host as well as web application service, because it will help you to identify log messages generated by the particular server subsystems. (We will discuss the HTTP hosts and web applications later.)
As you can see, several services are added to the HTTP Server. The first one is the HTTParameters service. It maintains the server's runtime parameters. Furthermore, some of these parameters may be modified via the server's console without restarting the server. We will also discuss the parameters later.
The second service is the RAMSessionManager service. It implements the SessionManager interface and stores all HTTP sessions in the operational memory. A session manager must be added to the server if you are going to use any form of the HTTP authentication.
The third service is the SK.gnome.dwarf.tcpip.TCPListener. It must be added to the server in order to allow it to accept the client TCP/IP connections. This service also specifies the port number on which the server will listen. It is possible to add more than one listener service to a single server - that would mean the server will listen on all ports specified by the listeners. See the base Dwarf API documentation for more information about TCP-based services.
So far we have configured a basic HTTP server, but it is still quite useless. It won't even start, because an exception would be thrown indicating that no HTTP hosts are defined. This section continues with explaining the HTTP hosts.
A HTTP host is an instance of the Host class. It serves primarily as a container for web applications, which we will discuss later, too.
Each host must have its "hostId attribute set. If you do not specify it explicitly, the default "localhost,127.0.0.1" string is used. Such a local HTTP host will serve all requests with URLs starting with the http://localhost/ or http://127.0.0.1/ string, for example.
<configuration>
<service classbase="SK.gnome.dwarf.http" class=".HTTPServer" name="HTTP Server">
<set name="logFacility">http</set>
<!-- HTTP PARAMETERS ... -->
<!-- SESSION MANAGER ... -->
<!-- LOCAL HOST -->
<service class=".Host" name="Localhost">
<set name="logFacility">http_localhost</set>
<set name="hostId">localhost</set>
</service>
<!-- TCP SERVICES ... -->
</service>
</configuration>
If no host can be related to a particular HTTP request, the request processing will fail with the "Invalid host" error message.
Please note also that we continue in the good practice of assigning each service a unique logging facility string.
Configuring virtual hosts is pretty straightforward. You use the same syntax as with the local host, but specify an IP address or a full-qualified domain name of the virtual host as the host's identification:
<!-- LOCAL HOST -->
<service class=".Host" name="Localhost">
<set name="logFacility">http_localhost</set>
<!-- the hostId can be omitted for the localhost -->
</service>
<!-- IP-BASED VIRTUAL HOST -->
<service class=".Host" name="ACME Headquarters">
<set name="logFacility">http_headq</set>
<set name="hostId">192.168.3.1</set>
</service>
<!-- NAME-BASED VIRTUAL HOST -->
<service class=".Host" name="ACME Sales">
<set name="logFacility">http_sales</set>
<set name="hostId">sales.acme.com</set>
</service>
Sometimes it is desirable to identify a HTTP host by more than one hostname/IP address. This can be configured by specifying a comma-separated list of hostnames/IP addresses in the "hostId" attribute:
<!-- LOCAL HOST -->
<service class=".Host" name="Localhost">
<set name="logFacility">http_localhost</set>
<set name="hostId">localhost, 127.0.0.1, webserver, 192.168.3.1</set>
</service>
Please remember that the string "localhost,127.0.0.1" is used automatically as an identification of the newly created Host instances, and this default setting is replaced only if the "hostId" attribute is set to any other value.
There are some other settings which are common to both local and virtual hosts.
A format of the HTTP transfer log messages can be specified for each host. It can be done by adding an instance of the HTTPLogFormat class to it:
<!-- LOCAL HOST -->
<service class=".Host" name="Localhost">
<set name="logFacility">http_localhost</set>
<!-- HTTP LOG FORMAT -->
<service class=".log.ExtendedLogFormat" name="Extended Log Format">
<set name="referer">false</set>
<set name="userAgent">false</set>
</service>
</service>
Such a log format will be used by all web applications belonging to the host if they do not use their own log format. If you do not specify a custom log format for the host, the ExtendedLogFormat will be used by default.
Each HTTP host must contain at least one web application. Dwarf HTTP Server
allows you to use even two formats of the web applications. One is the format
specified by the Servlet API 2.2. We will call it the standard web application
format. The second is the Dwarf's proprietary format and we will call it the
native web application format.
The standard format lets you deploy the WAR files easily with a very little
effort. The native format provides you with a greater configurability and flexibility
over the standard one.
A standard web application is represented by the WebApplication class. The web application service must be configured and added to the particular HTTP host:
<!-- LOCAL HOST -->
<service class=".Host" name="Localhost">
<set name="logFacility">http_localhost</set>
<!-- STANDARD WEB APPLICATION -->
<service class=".WebApplication" name="Welcome Application">
<set name="logFacility">http_welcome</set>
<set name="contextPath">/</set>
<set name="rootDir">www/samples/http/welcome</set>
</service>
</service>
There are two required attributes which must be set for each web application.
The "contextPath" attribute represents the context path of
the application. Use always the "/" string for the default
(root) context path. The "rootDir" attribute must point to
a directory where the web application files reside. If the web application is
distributed in a WAR file, it should be first unpacked to this directory. Alternatively,
you can enable the automatic deploying feature of the HTTP
host.
It is also possible to serve files directly from a WAR file by specifying the
location of the archive file instead of the root directory. However, this works
only for the static files, for which the MIME type is recognized by the server.
The JSP pages or custom servlets, classes and JAR libraries will not work in
this case.
Important: there must an application mapped to the root"/" context path in each HTTP host.
There are few more optional atributes, which can be set for the WebApplication object. The first one is the "implicitMappings" attribute, which specifies implicit extension mappings for the servlets. The implicit mappings take precedence over all other servlet mappings defined in the application. They must correspond to extension mappings defined for the particular servlets. The default implicit mapping is set to the "*.jsp" extension only. That means all requests to JSP files will be served by the JSP servlet, which is mapped to this extension by default. If you need to add another implicit mapping, you must manually change this default setting:
<!-- STANDARD WEB APPLICATION -->
<service class=".WebApplication" name="Root Application">
<set name="logFacility">http_root</set>
<set name="contextPath">/</set>
<set name="rootDir">www/samples/http/welcome</set>
<!-- OVERRIDING THE DEFAULT -->
<set name="implicitMappings">*.jsp,*.xsl</set>
</service>
Of course, there must be a servlet mapped to the "*.xsl" extension in this case, otherwise the setting of this attribute would fail. See the Servlets section for more details about the extension and implicit servlet mappings.
The second optional attribute is the "rolePrincipalClass". The attribute value must be a full-qualified class name of the principal object, which will represent the user's role in the web application. The reason for this configurability is that different login modules may use different principals for representing the user roles. Thus, this feature allows to use an arbitrary login mechanism for the authentication. The default class for the role principals is the SK.gnome.dwarf.auth.RolePrincipal.
Another optional attribute is "followSymlinks", which enables or disables following symbolic links on Unix platforms. By default, the server will not allow an URI path to go beyond the scope of the web application's root directory. If there is a symbolic link in the root directory, which points to a location outside of that directory, you must set this attribute to "true" to enable serving files from the linked directory.
Finally, the "forceAuthentication" attribute may be used to control the server's behavior while performing the basic HTTP authentication.
The mentioned optional attributes may be set also via the corresponding initial context parameters. Each parameter must start with the "sk.gnome.dwarf.http." prefix, like "sk.gnome.dwarf.http.implicitServletMappings", for example. This allows to set the optional attributes via the deployment descriptor if the automatic deploying feature is used.
Directory indexes (i.e. automatically displayed listings of directory contents) can be enabled by setting the "sk.gnome.dwarf.http.dirIndex" initial context parameter via the deployment descriptor. See the FileServlet documentation for more information about the directory indexes.
Although it is possible to set other inherited attributes of the WebApplication class, please avoid doing that! It might conflict with the future versions of the HTTP Server. If your application requires more configurablity, use the Dwarf's native web applications instead.
A native web application is represented by the Application class, which is a parent class of the mentioned WebApplication. The native web application must be configured and added to the HTTP host as well:
<!-- LOCAL HOST -->
<service class=".Host" name="Localhost">
<set name="logFacility">http_localhost</set>
<!-- NATIVE WEB APPLICATION -->
<service class=".Application" name="Welcome Application">
<set name="logFacility">http_welcome</set>
<set name="contextPath">/</set>
<set name="rootDir">www/samples/http/welcome</set>
</service>
</service>
This looks very similar to the standard web application. The difference is that the native application is configured via the Dwarf's own XML-based configuration tool. You configure the web application by setting its attributes and adding a services to it, just as with another parts of the Dwarf-based application. In fact, the same thing is performed by the WebApplication class automatically - it just reads the "web.xml" deployment descriptor first and then configures the native application by calling its setter methods first and then adding the required services to it.
Look at the sample native application now:
<!-- NATIVE WEB APPLICATION -->
<service class=".Application" name="Welcome Application">
<set name="logFacility">http_welcome</set>
<set name="contextPath">/</set>
<set name="rootDir">www/samples/http/welcome</set>
<set name="implicitMappings">*.jsp</set>
<!-- FILE SERVLET -->
<service class=".ServletWrapper" name="File Servlet">
<set name="servletClass">.servlet.FileServlet</set>
<set name="mapping">/*</set>
<set name="initParameters">
defaultPages=index.jsp
dirIndex=true
</set>
</service>
<!-- JSP SERVLET -->
<service class=".ServletWrapper" name="JSP Servlet">
<set name="servletClass">org.apache.jasper.servlet.JspServlet</set>
<set name="mapping">*.jsp</set>
</service>
</service>
You can see that some application attributes are set first and then some services are configured and added to the application later. Please refer to the Dwarf HTTP Server API documentation for the detailed description of all application attributes. Most of the atributes have been explained in the previous chapter. You might also noted that each servlet is represented by an instance of the ServletWrapper class. We will discuss the servlets later in the Servlets section.
These settings can be used for both the standard and the native web applications.
A useful feature is the possibility to setup a different format of HTTP transfer log messages for each web application. It can be done by adding an instance of the HTTPLogFormat class to the application object:
<service class=".WebApplication" name="Welcome Application">
<set name="logFacility">http_welcome</set>
<set name="contextPath">/</set>
<set name="rootDir">www/samples/http/welcome</set>
<!-- HTTP LOG FORMAT -->
<service class=".log.CommonLogFormat" name="Common Log Format">
<set name="referer">true</set>
<set name="userAgent">false</set>
</service>
</service>
If you do not specify a custom log format, the log format of the containing HTTP host will be used automatically by the web application.
A HTTP host can be configured for the automatic deploying of the standard web applications. Create an unique directory for each local or virtual host you want to perform the auto-deploying for. Let's say it is "www/localhost/" for the local host and "www/myhost/" for the virtual host. Then specify the deployment directories for the host instances:
<!-- LOCAL HOST -->
<service class=".Host" name="Localhost">
<set name="logFacility">http_localhost</set>
<set name="deployDir">www/localhost</set>
</service>
<!-- NAME-BASED VIRTUAL HOST -->
<service class=".Host" name="My Host">
<set name="logFacility">http_myhost</set>
<set name="deployDir">www/myhost</set>
</service>
That's all, basically. Now you just need to copy the application files to the
deployment directories. You can do it either by copying the whole subdirectory
containing the web application, or by copying just the WAR file itself. In the
second case, the archive file will be extracted first to a new subdirectory.
The name of the subdirectory will be equal to the name of the WAR file without
the ".war" extension.
In the next phase, the HTTP host will search for all subdirectories within the
deployment directory, and create and configure a new web application for each
subdirectory containing the "WEB-INF/web.xml" file. The basic
application attributes will be determined from the name of the subdirectory.
For example, if the "www/myhost/catalog/WEB-INF/" subdirectory
contains the deployment descriptor file, the corresponding web application named
"$catalog" would be created with its context path set to
"/catalog" and its root directory set to "www/myhost/catalog".
A special case is the "default/" subdirectory, which will
cause the web application to be mapped to the default (root) context path.
Once the WAR file is deployed, it can be removed safely from the deployment directory. However, if you copy a new WAR file with the same name but a different content, the application files in the subdirectory will be updated according to the fresh archive file. This provides an easy way of updating web applications by copying the updated WAR files to a single directory.
Note: a HTTP host with the automatic deploying enabled can contain also manually configured web applications. However, the root directories of these applications must not be located inside the host's deployment directory.
Configuration of servlets in the standard web application must be performed via the application's deployment descriptor - the "web.xml" file. The following servlets are configured and added to the each standard web application automatically:
name servlet class mapping ----------------------------------------------------------------------------- $FileServlet SK.gnome.dwarf.http.servlet.FileServlet / $JspServlet org.apache.jasper.servlet.JspServlet *.jsp $LoginServlet SK.gnome.dwarf.http.servlet.LoginServlet /j_security_check
The default "/" mapping pattern represents a specific type
of mapping. A servlet mapped to this pattern serves all requests for which no
other suitable servlet can be found. We call such a servlet the default
servlet.
The LoginServlet instance is added only if the form-based authentication
is configured via the deployment descriptor.
In a native web application servlets must be wrapped first by the ServletWrapper service and then added to the particular web application. Wrapping is done simply by setting the "servletClass" attribute of the ServletWrapper object:
<!-- NATIVE WEB APPLICATION -->
<service class=".Application" name="Welcome Application">
<set name="logFacility">http_welcome</set>
<set name="contextPath">/</set>
<set name="rootDir">www/samples/http/welcome</set>
<!-- FILE SERVLET -->
<service class=".ServletWrapper" name="File Servlet">
<set name="servletClass">.servlet.FileServlet</set>
<set name="mapping">/*</set>
<set name="initParameters">
defaultPages=index.jsp
</set>
</service>
</service>
The value of the "servletClass" attribute must be a full-qualified
class name of the servlet. (Be not confused - this example uses a shortened
syntax for the attribute values, whose name ends with "Class"
string. See the documentation for the XML-based configuration for the details.)
Other crucial attribute is "mapping", which specifies the
URL pattern for mapping requests to the corresponding servlets. The "initParameters"
attribute specifies the initial configuration parameters of the servlets. The
parameter name and value pairs must be in the format supported by the java.util.Properies
class.
Extension vs. implicit servlet mappings:
An extension mapping is by definition choosen as the last possibility, if no
other mapping can be found for the particular request URI path. For example,
let's have a FileServlet mapped to "/*" pattern
and a JspServlet mapped to "*.jsp" pattern. In this
case, a request to "/catalog/index.jsp" would be mapped to
the FileServlet, because it takes precedence over the extension mapping.
(This rule of precedence is implied by the Java Servlet API 2.2.) In order to
make the JspServlet work for the JSP pages, too, we have to set the
web application's implicit servlet mappings to the desired "*.jsp"
extension pattern. If there is a JdbcXsltServlet mapped to the "*.xsl"
extension, for example, and we need all requests to XSLT files to be mapped
to this servlet, the "implicitMappings" attribute value should
be then "*.jsp,*.xsl".
This chapter explains configuration of the security constraints and user roles in both the standard and the native web applications. It also covers the SSL-related issues.
The security constraints in the standard web applications are configured via the deployment descriptor. All you need is to configure the authentication service for the HTTP Server. The actual authentication process will assign some role-representing principals to the authenticated subjects. By default an instance of the SK.gnome.dwarf.auth.RolePrincipal class is expected to represent the user role, although this can be changed via the "rolePrincipalClass" attribute of the web application.
It is possible to use the "***" wildcard character sequence instead of the security role name in the <role-name> configuration element. This special role identifier will match any user, either authenticated or unauthenticated, therefore use this feature with a great care!
Configuration of the underlying authentication services in Dwarf-based applications is covered in details by the Dwarf Security Guide document in the base Dwarf distribution.
The security constraints in the native web applications are configured via installing a custom subject-based policy. The HTTPPathPermission class must be used to represent the permissions, and the policy entry must include an SK.gnome.dwarf.auth.ServicePrincipal instance with the name equal to the full name of the web application for which the entry is being configured. The subject-based permissions must cover all possible URL's. In other words, for each possible URL and HTTP method combination it must be specified which users have access to it.
See the sample subject-based policy entry:
// grant permission to access any resource within the "Welcome" application to everyone
grant principal SK.gnome.dwarf.auth.ServicePrincipal "Main Server/HTTP Server/Localhost/Welcome",
principal SK.gnome.dwarf.auth.EveryonePrincipal *
{ permission SK.gnome.dwarf.http.auth.HTTPPathPermission "/*", "GET";
};
The first argument of the HTTPPathPermission is an URL pattern, the second one is a list of allowed HTTP methods. This type of permission is special, because the SK.gnome.dwarf.auth.EveryonePrincipal "*" represents any user, either authenticated or unauthenticated. Therefore, this policy entry grants access to all resources via the GET method to all users in the context of the given web application.
Another sample entry might be:
// grant permission to access the specific resource to user "admin"
grant principal SK.gnome.dwarf.auth.ServicePrincipal "Main Server/HTTP Server/Localhost/Welcome",
principal SK.gnome.dwarf.auth.UserPrincipal "admin"
{ permission SK.gnome.dwarf.http.auth.HTTPPathPermission "/protected/*", "GET,POST";
};
This entry grants permissions to access all resources within the "/protected" subdirectory to an authenticated user, represented by the UserPrincipal "admin". The allowed HTTP methods are GET and POST.
You may specify also more permissions per one policy entry:
// grant permissions to access the specific resources to users in role "public"
grant principal SK.gnome.dwarf.auth.ServicePrincipal "Main Server/HTTP Server/Localhost/Welcome",
principal SK.gnome.dwarf.auth.RolePrincipal "public"
{ permission SK.gnome.dwarf.http.auth.HTTPPathPermission "/index.html", "GET";
permission SK.gnome.dwarf.http.auth.HTTPPathPermission "/public/*", "GET,POST";
};
But if you specify more than one user or role principal in the entry, the authenticated subject must contain all of these principals to be granted the access to the given resource:
// grant permission to access the specific resource to user "admin" which is also in the role "public"
grant principal SK.gnome.dwarf.auth.ServicePrincipal "Main Server/HTTP Server/Localhost/Welcome",
principal SK.gnome.dwarf.auth.UserPrincipal "admin",
principal SK.gnome.dwarf.auth.RolePrincipal "public"
{ permission SK.gnome.dwarf.http.auth.HTTPPathPermission "/protected/*", "GET,POST";
};
See the HTTPPathPermission for more information about the exact syntax of the arguments.
Configuration of the underlying authentication services and installing the subject-based policy files are covered in details by the Dwarf Security Guide in the base Dwarf distribution.
When configuring the HTTP authentication in a standard web application just follow the rules defined by the deployment descriptor. The next thing which must be done then is configuration of the underlying authentication mechanism. This topis is covered in details by the Dwarf Security Guide in the base Darf distribution. Basically, the required steps are as follows:
In the case of the native web application the Basic Authentication is choosen by default. If it is suitable for your purposes, you do not need to configure anything - just specify the security constraints and server will invoke the Basic Authentication whenever it finds out that an authentication is required to grant access to the given resource. The authentication realm name is equal to the name of the web application.
If you need the Form-Based Authentication, you must configure and add a LoginServlet instance to the web application. If the login servlet is mapped to the standard "/j_security_check" pattern, it will be invoked by the server automatically, instead of the default Basic Authentication:
<service class=".Application" name="Welcome Application">
<set name="logFacility">http_welcome</set>
<set name="contextPath">/</set>
<set name="rootDir">www/samples/http/welcome</set>
<!-- LOGIN SERVLET -->
<service class=".ServletWrapper" name="Login Servlet">
<set name="servletClass">.servlet.LoginServlet</set>
<set name="mapping">/j_security_check</set>
<set name="initParameters">
loginPage=/login/login.html
loginErrorPage=/login/error.jsp
</set>
</service>
</service>
It is possible to specify a different mapping for the LoginServlet, too. In that case you will have to invoke it manually, but server will still use the Basic Authentication if the resource being accessed requires an authentication.
See the LoginServlet documentation for more information about using and configuring the login serlvets.
Representation of user roles depends on the particular underlying authentication service used. For example, some third-party login modules might use custom principals for user roles. By default, the web application expects that the user roles are represented by the SK.gnome.dwarf.auth.RolePrincipal class. However, a custom authentication service may add a different principals to the authenticated subject to represent the user roles. Therefore it is possible to change the default expectation via the "rolePrincipalClass" attribute of the web application. The specified principal class must of course implement the java.security.Principal interface, and must have a constructor with the single string argument - the name of the user role.
SSL/TLS can be enabled by configuring the HTTP server to initialize a key store containing the server certificate and adding a special SK.gnome.dwarf.tcpip.SSLListener service to it:
<!-- HTTP SERVER -->
<service classbase="SK.gnome.dwarf.http" class=".HTTPServer" name="HTTP Server">
<set name="logFacility">http</set>
<set name="keyStoreURL">file:conf/testkey.crt</set>
<set name="keyStorePwd">123456</set>
<set name="keyPwd">abcdef</set>
<set name="SSLProtocol">TLSv1</set>
<!-- ... -->
<!-- STANDARD LISTENER ON PORT 80 -->
<service class="SK.gnome.dwarf.tcpip.TCPListener" name="HTTP Listener">
<set name="port">80</set>
</service>
<!-- SSL LISTENER ON PORT 443 -->
<service class="SK.gnome.dwarf.tcpip.SSLListener" name="SSL Listener">
<set name="port">443</set>
</service>
</service>
</configuration>
For testing purposes you may use the "bin/keystore.bat" or "bin/keystore.sh" script to create a sample server certificate.
You can also force a standard web application to require the secure connections via the <transport-guarantee> element of the deployment descriptor. Set it either to "INTEGRAL" or "CONFIDENTIAL" and the application will insist on using SSL/TLS for the given web resource collection.
In a native web application use the "SSLRequired" attribute and set it to "true". This setting applies to the whole web application.
An instance of the HTTPParameters class may be added to the HTTP server. This service provides runtime HTTP-related parameters for the server and all its nested services. The parameters are added automatically to the server with a set of suitable default values if you do not do it explicitly.
<!-- HTTP SERVER -->
<service classbase="SK.gnome.dwarf.http" class=".HTTPServer" name="HTTP Server">
<set name="logFacility">http</set>
<!-- HTTP PARAMETERS -->
<service class=".HTTPParameters" name="HTTP Parameters">
<set name="sendErrors">true</set>
<set name="keepAliveTimeout">20</set>
<set name="requestsPerConnection">50</set>
<set name="mimeTypes">file:conf/mimetypes.properties</set>
<set name="encodings">file:conf/encodings.properties</set>
<set name="charsets">file:conf/charsets.properties</set>
<set name="errorCodes">file:conf/errcodes.properties</set>
</service>
<!- ... -->
</service>
Please refer to the API documentation for the exact meaning of each parameter. Please note also that some of the parameters can be changed in runtime through the server console, while others are read-only.
For logging the HTTP transfer log messages use the HTTPFileLogger class. You may add it to the log server in the main server's configuration file, for example. All HTTP transfer log messages are generated with the LOG_XFER level by default.
The log messages generated by the JSP compiler can be captured by the special JSPLogger class. It is a proxy logger, redirecting the JSP-generated messages to the native logging mechanism used by the Dwarf HTTP Server. The JSP messages are assigned with the "jsp" logging facility by default.
There is also possiblity to increase the verbosity of the system log messages generated by the HTTP server. It can be done via the server console by issuing the "debug http" command. This would cause the server to print out an information about the request processing. Similary, the "trace http" command would cause the server to print out even more detailed information. Finally, the "trace http.protocol" command would cause the server to dump out the full HTTP headers of each request/response chain.
Correct parsing of request parameters in other than the system-default encoding depends on the MIME charset information sent in the "Content-Type" request header. However, most browsers do not send this information, therefore the server cannot distinguish the encoding used in the requests properly. By setting the "defaultEncoding" attribute of web application you can instruct the server to use the given default encoding for parsing the request parameters if encoding information is not present in the request:
<!-- HTTP SERVER -->
<service classbase="sk.gnome.dwarf.http" class=".HTTPServer" name="HTTP Server">
<set name="logFacility">http</set>
<service class=".WebApplication" name="Welcome Application">
<set name="logFacility">http_welcome</set>
<set name="contextPath">/</set>
<set name="rootDir">www/samples/http/welcome</set>
<!-- DEFAULT ENCODING -->
<set name="defaultEncoding">UTF-8</set>
</service>
<!- ... -->
</service>
If "defaultEncoding" attribute value matches the encoding used by browser to construct the request, you will get the correct request parameter values as Unicode string objects. You can force the browser to use the particular encoding either by providing the "Content-Type" header in HTTP responses, or by using the <meta http-equiv="Content-Type"> HTML tag, both with the correct "charset=xxxxxx" parameter included.
The request URL unescaping excepts the URLs to be in the UTF-8 encoding. This cannot be changed at the present time.
By default the Sun's Java compiler is used to compile the JSP pages. This requires installation of the Java 2 Software Development Kit (JSDK), because the compiler is not included in the Java 2 Runtime Environment (JRE) distribution package. An alternative is to use the Jikes compiler - in that case, you do not need the JSDK to be installed on your computer. Here's how to do it:
1. Jikes executable must be in your program path, i.e. you must be able to invoke it by typping "jikes" in the command prompt
2. The "useJikesForJSP" parameter must be specified and set to "true" in the HTTP server configuration:
<!-- HTTP SERVER -->
<service classbase="SK.gnome.dwarf.http" class=".HTTPServer" name="HTTP Server">
<set name="logFacility">http</set>
<!-- HTTP PARAMETERS -->
<service class=".HTTPParameters" name="HTTP Parameters">
<!-- ENABLING JIKES -->
<set name="useJikesForJSP">true</set>
</service>
<!- ... -->
</service>
WebDAV support can be enabled by configuring the WebDAVServlet. It must be mapped to the special "/webdav/*" pattern:
<!-- NATIVE WEB APPLICATION -->
<service class=".Application" name="Welcome Application">
<set name="logFacility">http_welcome</set>
<set name="contextPath">/</set>
<set name="rootDir">www/samples/http/welcome</set>
<!-- WEBDAV SERVLET -->
<service class=".ServletWrapper" name="WebDAV Servlet">
<set name="servletClass">.webdav.WebDAVServlet</set>
<set name="mapping">/webdav/*</set>
<set name="initParameters">
dirIndex=true
clientEncoding=WINDOWS-1250
</set>
<service class="SK.gnome.dwarf.utils.LRUCache" name="Cache">
<set name="size">50</set>
<set name="timeout">120</set>
<set name="checkingInterval">300</set>
</service>
</service>
</service>
Since the servlet extends the FileServlet
class, the "dirIndex" initial configuration parameter can
be used to enable displaying of the directory contents in the form of HTML pages.
The "clientEncoding" configuration parameter may be used
to force the servlet to decode the escaped URLs sent by the WebDAV clients with
the particular MIME encoding. This can be useful if the built-in auto-detection
of the client encoding is not sufficient and you experience problems of accessing
files with names in different that the US-ASCII encoding.
In our example we also use a caching service to speed-up browsing of the large directory trees. Please remember that the caching will work correctly only if the web application files are not modified externally.
Note: The servlet creates some special directories and files in the web application's root directory. These files contains the WebDAV metadata such as property names and values, and so on. They are checked and initialized each time the servlet is started.
Since the WebDAV is an extension to the HTTP protocol, the authorization must be configured in the same way as with the standard HTTP methods; the WebDAV-specific methods PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK and UNLOCK can be used to setup the security constraints. The property-based security is not yet supported, therefore all WebDAV properties are readable and modifiable by anyone who has right to access the given resource via the PROPFIND and PROPPATCH methods.
WebDAV will run through SSL transparently if you configure the web application to require the SSL connection and the HTTP server to accept the secure requests.
Return to the main page.