
	Corporate Info \| News \| Solutions \| Products \| Partners \| Services \| Events \| Download \| How To Buy
	e-docs \| Site Map \| Search \| Contact \| Glossary \| WebLogic Server Documentation

Setting up WebLogic as an HTTP server

Using the WebLogic Server as a webserver

Additional steps on UNIX

Serving requests over HTTP with WebLogic

Setting up a document root

Setting up the FileServlet

Setting up default (welcome) pages

Customizing HTTP error responses

Registering servlets in the weblogic.properties file

Serving Java servlets using the ServletServlet

Setting up the ClasspathServlet

Proxying requests to another HTTP server

Setting up dynamic page compilation

Setting up JHTML

Setting up JSP

Using server-side includes

Using legacy CGI

Setting standard MIME types

Setting up WebLogic for HTTP tunneling

Enabling and using the HTTP server logs

Setting up access log rotation

Enabling event-based HTTP request information

Setting up session management

HTTP session properties

Configuring session cookies

Configuring session persistence

Using the WebLogic Server as a webserver

The WebLogic Server can be used as your primary webserver. WebLogic is highly versatile, and can be configured to serve:

Static files, such as HTML, images, JARs, Applets, etc.
Proxy requests to another webserver, even another webserver on a different machine.
HTTP Servlets written as Java servlets, JavaServer Pages, or JHTML. The Servlet API is an open standard that allows you to customize any HTTP service on WebLogic by writing your own HTTP servlets.

This document includes information on how to configure the WebLogic Server as an HTTP server

After installing and configuring the WebLogic Server as a webserver, we recommend you follow this checklist. It's provided here so you do not forget!

Check your HTTP security properties so that your site is secure and private resources remain private.
Set up SSL properties if you require secure communication with your clients.
Configure HTTP logging to keep track of traffic coming through your site. You may also want to configure the weblogic.system.maxLogFileSize property to control the maximum size of the log files.
Understand and be aware of the Default Servlet configuration. It will serve files that are not handled by any other servlet resource.
Check the registration of the WebLogic Servlets and their access control lists
If you use the multihome feature, you must set the weblogic.system.bindAddr to the domain name or IP address for which the WebLogic Server should listen. For more information on setting up multiple WebLogic Servers on a multihomed machine, read the multihome section in the WebLogic Administrators Guide, Setting up and starting a WebLogic Server.

Additional steps on UNIX

There are two additional steps when setting up on UNIX.

WebLogic is pure-Java and requires no installation of native code, but we do provide an UNIX-specific way to start the Server on port 80. Allocating port 80 usually must be done from a privileged account like root, but you do not want to run your web server from a root account -- rather, you want to run it as a non-privileged user, to add an additional layer of security. We provide a UNIX library that performs this function in the weblogic/lib directory; it is called libweblogicunix1.so (general UNIX) or libweblogicunix1.sl (for HPUX 10/11).

Add the directory weblogic/lib/solaris
to your LD_LIBRARY_PATH (UNIX) or SHLIB_PATH (HPUX)
or
Install libweblogicunix1.so somewhere in your LD_LIBRARY_PATH (UNIX) or SHLIB_PATH (HPUX). (If you have problems, check our Troubleshooting guide on using shared libs on UNIX.)
In the weblogic.properties file, set the weblogic.system.enableSetUID and weblogic.system.nonPrivUser properties. Instructions for setting these properties are found in the administrator's guide Setting WebLogic properties.

Serving requests over HTTP with WebLogic

This section describes how to set up the WebLogic Server to serve HTTP requests.

There are two approaches to hosting web-based services on the WebLogic Server since the Servlet2.2 specification introduced the concept of a Web Application and multiple servlet contexts. The original means of configuring web services uses properties from the weblogic.properties file. All web services deployed from the weblogic.properties file are considered as deployed in the default servlet context, and are described in the rest of this document.

Services deployed from a Web Application exist in their own servlet context. The WebLogic Server is capable of hosting multiple Web Applications simultaneously. Each Web Application has its own deployment descriptor that describes how the Web Application is deployed on WebLogic Server.

To deploy a Web Application on the WebLogic Server, add the following property to the weblogic.properties file to register the entire Web Application:

  weblogic.httpd.webApp.context=WebAppLocation

Where context is the servlet context path assigned to all services in the Web Application, and WebAppLocation is either:

the root directory of the Web Application, or
the location of the Web Application aRchive (WAR) file.

For details on deploying your web services from Web Application, see the Developers Guide Writing a Web Application.

The rest of this document describes how to deploy HTTP services from the weblogic.properties file in the default servlet context.

Setting up a document root

Much of the functionality for serving files in WebLogic depends on the location of a directory that operates as a document root. The document root is where the FileServlet, the JSPServlet, and the ServerSideIncludeServlet search for files to serve. You will locate HTML, JSP, and SHTML files and images in this directory (or one of its subdirectories) for serving through browser requests. You will also locate HTML files that serve applets, even though the CODEBASE (and the supporting classes) for the applet are located in a different directory structure. The document root, which is new in 3.1, supercedes the old-style "dochome" property.

By default, the document root for WebLogic, if unset, is the weblogic/myserver/public_html directory. You can change the location of this directory by setting a property in the weblogic.properties file:

weblogic.httpd.documentRoot=path

The path can be absolute or relative, in which case the directory structure of path is assumed to exist in the weblogic/myserver/public_html directory.

Setting up the FileServlet

Included in the distribution is another servlet that serves up any files that you configure it to serve. This property sets a prefix for use in URLs

that maps to a path on the WebLogic Server host; the property also allows you to set a default filename (like "index.html") to protect the directory from scanning. The types of files served by the FileServlet are defined as MIME types in the properties files.

To set up the FileServlet, register the FileServlet with a virtual name as the prefix that you will use in your URLs. For example, here is a sample weblogic.properties entry that registers a virtual name of "file" to point to the file servlet:

weblogic.httpd.register.file=weblogic.servlet.FileServlet

Supply a single initialization argument for the FileServlet, which sets the name of a default file that should be read in the event there is no file that matches the request. Usually the default filename will be set to "index.html" or "home.html" to protect the directory from being scanned in the browser. Here is a sample entry from the weblogic.properties file that shows how the initialization arguments might be set up:

weblogic.httpd.initArgs.files=\
	 defaultFilename=index.html

Then construct your URL or CODEBASE after this pattern:

  http://localhost:7001/file/filename.extension

where localhost:7001 is the URL of your WebLogic Server, and filename.extension is the full filename of the file you want to serve, which should be located in the document root. For instance, if you have deposited a file "myapplet.html" in c:/weblogic/myserver/public_html, you would request the WebLogic Server on your local host to serve the HTML page with this URL:

  http://localhost:7001/file/myapplet.html

If you are using Netscape Communicator 4.x, you will experience problems when you run WebLogic on the same machine as your browser client. Please check the FAQ for more information on how to set up your environment.

Warning regarding the File Servlet and JSP

If you will be serving JSP files, be aware that it is possible to serve the source code for JSP files if the file servlet is registered as "file" as shown above. For more information on this problem, see WebLogic Server JSP Configuration in the document Securing a WebLogic Server Deployment.

Setting up default (welcome) pages

The WebLogic Server allows you to set a default page that is served by default if the requested URL is a directory. This is useful for making your site more friendly, since the user may type a URL without giving a specific filename. It may also be used as a security measure to prevent clients from obtaining a directory listing at a particular URL. Note, to turn off directory listing in the WebLogic Server, set the following property in the weblogic.properties file:

   weblogic.httpd.indexDirectories=false

Directory listing is turned on by default.

Currently, there are two separate methods for determining a default filename for static and dynamic content, described next.

weblogic.httpd.servlet.files=weblogic.servlet.FileServlet
weblogic.httpd.initArgs.files=defaultFilename=index.html

You may configure the FileServlet to serve a default file if the URL request is a directory. The FileServlet will attempt to serve a file of that name from the requested directory.

For example:

When a client requests the URL:: http://www.yourserver.com/
The FileServlet will attempt to serve the file at URL:: http://www.yourserver.com/index.html
If a client requests the URL:: http://www.yourserver.com/auctions/
The FileServlet will attempt to serve the file at URL:: http://www.yourserver.com/auctions/index.html

You set the name of the default file with the initialization argument defaultFilename at the FileServlet registration. For example:

weblogic.httpd.servlet.file=weblogic.servlet.FileServlet
weblogic.httpd.initArgs.files=defaultFilename=welcome.html

Will set the default file to "welcome.html". The default value if unset is "index.html".

Serving dynamic pages by default

You may configure the WebLogic Server to serve dynamic default files, delivered by the JSPServlet, the PageCompileServlet, or your own custom servlet. This property instructs the WebLogic Server to look for certain files to be handled by specific servlets handling their file extension types:

  weblogic.httpd.indexFiles=index.foo, index.bar

Where servlets must be registered to handle all files with extension ".foo" and ".bar", such as:

  weblogic.httpd.register.*.foo=com.myservlets.FooServlet
  weblogic.httpd.register.*.bar=com.myservlets.BarServlet

The comma separated list of filenames is searched in order, and precedes the invocation of the FileServlet, and hence precedes the defaultFilename associated with the FileServlet. Note that servlets must be registered to handle the listed file extension types.

Serving a default JSP file

This example shows how to serve a default JSP file from a directory.

Set the following property in your weblogic.properties file:
```
   weblogic.httpd.indexFiles=index.jsp
```
Register the JSPServlet to handle files with the extension ".jsp". For more details, see Setting up Weblogic JSP in the Administrators Guide, "Setting WebLogic Properties".
Add a JSP file named "index.jsp" to each directory.

To setup the older style JHTML files as default, substitute "index.jhtml" for "index.jsp", in the directions above, and register the PageCompileServlet to handle files with extension ".jhtml".

Note: You must have the FileServlet registered as the default servlet, and this functionality will only work for JSP files names "index.jsp" or JHTML files named "index.jhtml".

How it works

Here is how the WebLogic Server attempts to resolve which default files to serve. Understanding this should help you troubleshoot or configure default files handled by your custom servlets.

The FileServlet must be registered as the default servlet for this functionality to work. This constraint may be removed in a future release.
The server looks for the list of files specified by the property weblogic.httpd.indexFiles in order, in the requested directory.
- If a default file is found, the server attempts to match the file extension to a registered servlet. In the case of the name "index.jsp", the JSPServlet must be registered to handle the extension ".jsp", and the file must be present in that directory.
- The registered servlet is invoked to serve it is default filename. In the case of the JSPServlet, this is always the file "index.jsp".
- Each file in the list is attempted. If none are found, the FileServlet (the default servlet) is invoked.
If the FileServlet finds the file configured by defaultFilename, that is served.
If the FileServlet fails to find the defaultFilename file, a directory listing is served if this feature is enabled, or an HTTP 404 error is returned.

Customizing HTTP error responses

You can configure the WebLogic Server to respond with your own custom web pages or other HTTP resources when particular HTTP errors occur, instead of responding with the standard WebLogic response. This functionality is supported for both means of deploying web services on the WebLogic Server.

If you deploy your servlets from a Web Application servlet context (introduced by the Servlet2.2 specification), see the Developers Guide Writing a Web Application.

If you deploy your web services from the weblogic.properties file, then you are deploying from the default servlet context. Use the following property in the weblogic.properties file to configure custom error pages.

  weblogic.httpd.errorPage.xxx=URL

When the HTTP error xxx occurs, the resource at URL is returned. If the URL specified is fully qualified -- i.e. it contains the protocol and server address -- then the a send-redirect response is returned to the client. This allows the error page response to be directed to another server.

If a local URI is specified, the request is dispatched within the server to the new resource. If the local URI is relative such as "errorPage.html", the error page is searched from the current URI path directory. If an absolute URI is given such as "/errorPage.html", the error page is searched for from the document root. It is advisable to use the latter absolute URI address except for 401 errors.

To return a 401 error, do not use an absolute URL such as http://somehost/errorPage.html. To redirect the browser to the absolute URL, define an error page in the document root and redirect it in that error page. For example:

 weblogic.httpd.errorPage=/toYahoo.jsp

In the file, toYahoo.jsp, add:

 <% sendRedirect("http://www.yahoo.com"); %>

You can set the error page URL to any address since it is resolved by the WebLogic Server as a regular request. This allows you to reference JSP pages, HTTP servlets, or any other HTTP resource as an error page.

A common requirement is to set a global error page response to a file-not-found 404 error, using a property such as:

  weblogic.httpd.errorPage.404=/errorPage.html

Where /errorPage.html is an HTML page located in the document root on the WebLogic Server.

Registering servlets in the weblogic.properties file

The WebLogic Server supports HTTP Servlets that are written to conform to the JavaSoft Java Servlet API, which are the packages javax.servlet and javax.servlet.http, available from JavaSoft.
Note: These classes are already included in the package in the weblogicaux.jar file.

To use HTTP servlets with the WebLogic Server, you may register them as entries in the WebLogic Server's weblogic.properties file. Servlets are registered with the weblogic.httpd.register property in the properties file, and arguments and initialization parameters to be passed to the servlet are registered with the the weblogic.httpd.initArgs property. Registered servlets are loaded at startup.

When you register a servlet, you can also set access control lists (ACLs) on the servlet (or servlet hierarchy) to restrict access to certain users.

WebLogic has special servlets that allow you to serve classes and other kinds of files without registering them. The ServletServlet, for example, allows you to request any servlet in the servlet classpath. For security reasons, we do not suggest that you deploy a production server with the ServletServlet enabled.

For more information on registering servlets, check the WebLogic Administrator Guide Setting WebLogic properties.

Serving Java servlets using the ServletServlet

The standard approach to using HTTP servlets with the WebLogic Server is to register them in the weblogic.properties file. However, the ServletServlet is a special kind of HTTP servlet that allows you to invoke other HTTP servlets that are not registered in the properties file. There is more about writing servlets and the ServletServlet in the Developers Guide, "Using WebLogic HTTP Servlets".

Setting up the ClasspathServlet

Included in the distribution is a servlet that does one thing: it loads class files from the WebLogic classpath. This allows you to use additional directories for your Java class files (like applets and servlets) as long as you include them in the WebLogic classpath.

Prior to the introduction of the ClasspathServlet, users had to copy all the WebLogic classes and all of their own classes into a single directory tree, then use the base of that directory tree for CODEBASE and register that directory with the FileServlet. Such a method meant that you could not keep your classes separated from the WebLogic classes, because the CODEBASE had to refer to a single directory.

The ClasspathServlet adds another layer of indirection to how WebLogic finds classes; with it, WebLogic searches its entire classpath to find classes for a request. That means you can have multiple directory structures with class files that are all equally accessible to WebLogic.

To use the ClasspathServlet, you must register a virtual name for it in the weblogic.properties file. The virtual name becomes the CODEBASE for your applets.

Here is a sample registration:

  weblogic.httpd.register.classes=\
        weblogic.servlet.ClasspathServlet

Place your applet class files in the WebLogic classpath, as you would for a regular Java class file. The WebLogic classpath is specified on the command line when you start the server with the weblogic.class.path property. For example, the applet "myapplets.mypackage.OpenTheTour.class" might be located on your WebLogic host in the directory c:\appletdir\myapplets\mypackage\OpenTheTour.class, where the C:\appletdir is included in the weblogic.class.path property.

To serve an applet in an HTML page, you must include an <APPLET> tag. For more details on setting applet tag attributes see the tech-support document, Troubleshooting CODEBASE?.

Put the HTML file that calls the applet in your WebLogic Server's document root. Here, we assume the file is called "open.html".

Set the CODEBASE for the applet to "/classes/".

Call the HTML file with the URL:

  http://WebLogicURL:Port/open.html

Where WebLogicURL:Port is the URL and port number of the WebLogic Server. The classes for the applet will be loaded from the WebLogic Server's classpath.

Proxying requests to another HTTP server

When you use the WebLogic Server as your primary webserver, you may also want to configure WebLogic to pass on, or proxy, certain requests to a secondary HTTP server, like Netscape or Microsoft. Any request that the WebLogic Server cannot answer it passes on, as received, to the URL registered as the proxy servlet. You can even proxy to another webserver on a different machine.

To set up a proxy, you set two properties in the weblogic.properties file:

weblogic.httpd.register.proxy=weblogic.t3.srvr.HttpProxyServlet
weblogic.httpd.initArgs.proxy=redirectURL=otherURL

where otherURL is the URL of the server to which proxy requests should be directed.

The HttpProxyServlet (provided as part of the distribution) takes an HTTP request, redirects it to the proxy URL, and sends the response to the client's browser back through the WebLogic Server.

If you have the registration for the proxy servlet set up as the value for the default servlet (in this case, weblogic.httpd.defaultServlet=proxy) then any file for which WebLogic cannot answer a request will be proxied to the other server.

Here is a sample request and how it would be handled:

On a WebLogic Server "toyboat.toybox.com," a request is received for http://toyboat.toybox.com/Docs/SomeFile.html. That file doesn't exist in any of the configured WebLogic Server's searchable directories or document root.
The WebLogic Server is configured to proxy unanswerable requests to http://another.server.com with the property entry weblogic.httpd.initArgs.proxy=redirectURL=http://another.server.com.
The request is proxied as http://another.server.com/Docs/SomeFile.html.

Setting up dynamic page compilation

Dynamic page compilation allows you to embed Java into an HTML page to provide dynamic content to your web pages. Of the existing alternative syntaxes available, WebLogic supports both the JHTML and JSP (JavaServer Pages) standards.

WebLogic can automatically compile JHTML or JSP files into servlets and call upon them to respond to HTTP requests. There is more on writing JHTML and JSP in the Developers Guides, Using WebLogic JHTML, and Using WebLogic JSP.

WebLogic uses special page-compile-servlets for compiling and delivering JHTML and JSP pages. These page-compile-servlets are a standard part of the WebLogic Server, but you must register them in the weblogic.properties file with the relevant file extension. When a user requests a ".jhtml" or ".jsp" page, the registered servlet compiles the page (if necessary) into an HTTP servlet which is invoked to deliver the response to the browser.

For future servlet projects we recommend that you use JSP instead of JHTML.

Setting up JHTML

As of release WebLogic Server 4.5.1, we recommend that you use JSP for future servlet projects instead of JHTML. These notes remain here for completeness.

To serve JHTML files, you must register the PageCompileServlet and several initArgs as illustrated below:

weblogic.httpd.register.*.jhtml=\
  weblogic.servlet.jhtmlc.PageCompileServlet

weblogic.httpd.initArgs.*.jhtml=\
  verbose=boolean, false by default,\
  pageCheckSeconds=interval WebLogic checks for recompilation,\
  compileCommand=path to compiler,\
  workingDir=path to directory of compiled .jhtml files

You will need to set the initialization arguments to match your own installed environment. For example, you need to identify the absolute path to your Java compiler. You also need to specify the directory where the compiled servlet classes will be placed.

weblogic.httpd.initArgs.*.jhtml=\
  compileCommand=c:/java/bin/javac.exe,\
  workingDir=c:/weblogic/myserver/pagecompileHome

There are more details on the registration in the configuration guide, Setting WebLogic properties.

Setting up JSP

To serve JSP files, you must register the JSPServlet and several initialization parameters as illustrated below:

weblogic.httpd.register.*.jsp=\
  weblogic.servlet.jspc.JSPServlet

weblogic.httpd.initArgs.*.jsp=\
  verbose=boolean, false by default,\
  pageCheckSeconds=interval WebLogic checks for recompilation,\
  compileCommand=path to compiler,\
  workingDir=path to directory of compiled .jsp files

weblogic.httpd.initArgs.*.jsp=\
  compileCommand=c:/java/java115/bin/javac.exe,\
  workingDir=c:/weblogic/myserver/pagecompileHome

There are more details on configuring the WebLogic Server for JSP in the Administrators Guide Setting WebLogic Properties. For information on developing JSP, see the Developer Guide, Using WebLogic JSP.

Using server-side includes

WebLogic provides limited server-side include functionality to support your legacy SSI pages. For new projects, we suggest you use the include directive in JavaServer Pages.

The WebLogic Server supports server-side includes using a standard WebLogic servlet called the ServerSideIncludeServlet. Traditionally, server side include pages have the extension .shtml. The ServerSideIncludeServlet is registered in the weblogic.properties file to handle all .shtml files using this property:

  weblogic.httpd.register.*.shtml=\
    weblogic.servlet.ServerSideIncludeServlet

SHTML files must be located under the document root, as is the case for static HTML pages. There is more information about server-side includes in the Developers Guide, Using WebLogic HTTP Servlets.

Using legacy CGI

WebLogic provides functionality to support your legacy CGI scripts. For new projects, we suggest you use HTTP servlets or JavaServer Pages.

The WebLogic Server supports all CGI scripts via a standard WebLogic servlet called the CGIServlet. You must register the CGIServlet in the weblogic.properties file to handle requests to specific URL patterns.

To enable traditional CGI in WebLogic Server, register the CGIServlet against the URL pattern cgi-bin as shown here:

  weblogic.httpd.register.cgi-bin=weblogic.servlet.CGIServlet
  weblogic.httpd.initArgs.cgi-bin=\
      cgiDir=/weblogic/myserver/cgi-bin,\
      *.pl=/bin/perl.exe,\
      *.class=/java/java.exe

You must supply initialization arguments for the CGIServlet -- the second property shown above, where cgiDir specifies the directory where your CGI scripts are located. You can specify multiple CGI directories separated by a semi-colon (;) on NT, a colon (:) on UNIX, or the appropriate file path separator for your operating system. If you do not specify cgiDir, the property defaults to a directory named cgi-bin under the myserver directory.

The other initialization arguments specify extension mappings. These map HTTP requests for scripts with a specific extension to the appropriate interpreter or executable that runs the script. The output from the executed script provides the HTTP response. Your extension mappings must begin with an asterisk followed by a dot. In the example above, all requested files ending with *.pl should be located in the directory given by cgiDir and are interpreted by the /bin/perl.exe executable.

If a script or executable does not require an interpreter, such as a shell script or an .exe file on NT, then it does not require an extension mapping. Simply place the script or executable in one of the cgiDir directories, and request it as you would any other CGI script.

The URL used to request a perl script must follow the pattern:

  http://server:port/cgi-bin/myscript.pl

Where server:port is the address of your WebLogic Server, cgi-bin is the virtual name mapped to the CGIServlet, and myscript.pl is the name of the perl script that is located in the /weblogic/myserver/cgi-bin directory given by the cgiDir initArg.

Known limitations

You cannot use relative URIs in your CGI scripts.

Setting standard MIME types

You will also configure your WebLogic Server to serve certain MIME types by making a registration in the properties file, such as:

  weblogic.httpd.mimeType.text/html=html,htm
  weblogic.httpd.mimeType.image/gif=gif
  weblogic.httpd.mimeType.image/jpeg=jpeg,jpg
  weblogic.httpd.mimeType.application/pdf=pdf
  weblogic.httpd.mimeType.application/zip=zip
  weblogic.httpd.mimeType.application/x-java-vm=class
  weblogic.httpd.mimeType.application/x-java-archive=jar
  weblogic.httpd.mimeType.application/x-java-serialized-object=ser

There is more on this in the the configuration document, Setting WebLogic properties.

Setting up the WebLogic Server for HTTP tunneling

HTTP tunneling provides a way to simulate a statefull socket connection between the WebLogic Server and a Java client when your only option is to use the HTTP protocol. It is generally used to 'tunnel' through an HTTP port in a security firewall. HTTP is a stateless protocol, but WebLogic provides tunneling functionality to make the connection appear to be a regular T3Connection. However, you can expect some performance loss in comparison to a normal socket connection.

Configuring HTTP Tunneling on the WebLogic Server

The WebLogic server is always set up to receive HTTP tunnel requests. However, you must enable servlets in the weblogic.properties file, using the following setting:

  weblogic.allow.execute.weblogic.servlet=everyone

WebLogic HTTP tunneling uses a number of internal servlets to handle the HTTP tunnel requests. You can control access to other specific servlets with other properties as described in Setting up ACLs for servlets in the WebLogic realm.

You control access to services through an HTTP tunnel connection in the same way as you control access to those services accessed via a regular T3Connection.

Connecting from the client

When your client requests a connection with the WebLogic Server, all you need to do in order to use HTTP tunneling is specify the HTTP protocol in the URL. For instance:

  Hashtable env = new Hashtable();
  env.put(Context.PROVIDER_URL, "http://wlhost:80");
  Context ctx = new InitialContext(env);

On the client side, a special tag is appended to the http protocol, so that the WebLogic Server knows this is a tunneling connection, instead of a regular HTTP request. Your application code does not need to do any extra work to make this happen.

The client must specify the port in the URL, even if the port is 80. You can set up your WebLogic Server to listen for HTTP requests on any port, although the most common choice is port 80 since requests to port 80 are customarily allowed through a firewall.

To specify the port for the WebLogic Server, set the property weblogic.system.listenPort in the weblogic.properties file.

Configuring the HTTP tunneling connection

Under the HTTP protocol, a client may only make a request, and then accept a reply from a server. The server may not voluntarily communicate with the client, and the protocol is stateless, meaning that a continuous two-way connection is not possible.

WebLogic HTTP tunneling simulates a T3Connection via the HTTP protocol, overcoming these limitations. There are two properties that you may configure in the weblogic.properties file on the server to tune a tunneled connection for performance. It is advised that you leave them at their default settings unless you experience connection problems. These properties are used by the server to determine that the client connection is still valid, or that the client is still alive.

Here, we talk about the underlying WebLogic implementation of the client-to-server HTTP tunneling connection. This is not behavior that an application developer needs to implement, but we explain it here so that you can understand these properties.

weblogic.httpd.tunneling.clientPingSecs=xx

When an HTTP tunnel connection is setup, the client automatically sends a request to the server, so that the server may volunteer a response to the client. The client may also include instructions in a request, but this behavior happens regardless of whether the client application needs to communicate with the server. If the server does not purposefully respond to the client request within clientPingSecs seconds, it does so anyway. The client accepts the response and automatically sends another request immediately. Default is 45 seconds; valid range is 20 to 900 seconds.

weblogic.httpd.tunneling.clientTimeoutSecs=xx

If clientTimeoutSecs seconds have elapsed since the client last sent a request to the server (in response to a reply), then the server regards the client as dead, and terminates the HTTP tunnel connection. The server checks the elapsed time every clientPingSecs, when it would otherwise respond to the client's request. Default is 40 seconds; valid range is 10 to 900 seconds.

Setting up HTTP server log files

The WebLogic Server can keep a log of all HTTP transactions in a text file in either common log format, or extended log format. Common log format is the default, and follows a standard convention. Extended log format allows you to customize the information that is recorded. As of WebLogic Server 5.1, with service pack sp4, you can also rotate the log file based on either the size of the file or after a specified amount of time has passed. When either these two criteria are met, the current access log file will be closed and a new access log file will be started.

To enable logging, set the following property in your weblogic.properties file:

  weblogic.httpd.enableLogFile=true
  weblogic.httpd.logFileName=name_of_log_file
  weblogic.httpd.logFileFormat=[common | extended]
  weblogic.httpd.logFileFlushSecs=seconds

Where name_of_log_file is the file where HTTP information is appended to. This defaults to access.log and is recorded under the myserver directory in your WebLogic installation directory.

You may set the log format to either extended log format or common log format. Both formats are described below.

Note: If you are testing the log format, you should set the logFileFlushSecs property to 1 second, so it is updated frequently. Otherwise, the server may not flush the log file before you shut down the server. The default value is 60 seconds, to improve performance. For a production system, you should use the default or a higher value.

All regular WebLogic Server logs shall continue to be written to the weblogic.log file; only the subset of log information related to HTTP access shall be written to the access.log file. Note that the HTTP log is always appended to, even between server down-time, and so will grow indefinitely. You should maintain it manually.

Setting up access log rotation

Note: Access log rotation requires WebLogic Server 5.1, Service Pack sp4 or later.

Access log rotation allows you to rotate your HTTP access log when it reaches a certain size or after a specified amount of time has passed. When the access log rotates, a new log file with a new file name is started. The access log's file name includes a numeric portion that is incremented upon each rotation.

To set up access log rotation, set the following properties (in addition to those properties you set to enable access logs) in your weblogic.properties file:

weblogic.httpd.logRotationType

Set to date to rotate your access log by date. If you choose this option, you must also set two additional properties: weblogic.httpd.logRotationPeriodMins and weblogic.httpd.logRotationBeginTime.

Set to size to rotate your access log when it exceeds a certain size. If you choose this option, you must also set the weblogic.httpd.maxLogFileSizeKBytes property. The default value is size.

weblogic.httpd.logRotationPeriodMins

If you are rotating your access log by date, set this to the number of minutes after which the access log will rotate. (1440 minutes = 24 hours, 100080 minutes = 1 week). The default value is 1440.

weblogic.httpd.logRotationBeginTime

Sets the date when the first access log rotation will occur. If you do not set this property, the access log rotates after the amount of time specified with the weblogic.httpd.logRotationPeriodMins property. Enter the date using the java.text.SimpleDateFormat, MM-dd-yyyy-k:mm:ss. See the javadocs for the java.text.SimpleDateFormat class for more details. For example: 11-24-2000-12:30:00

If, when you start WebLogic Server, this date has already passed, the first access log rotation will occur on the day you start WebLogic Server, at the hour, minute, and second specified by weblogic.httpd.logRotationBeginTime.

weblogic.httpd.maxLogFileSizeKBytes

Set to the maximum size, in kilobytes, for your access log file. When the access log reaches this size, it is rotated. If set to 0 (the default value) access log files do not rotate based on size. This property is ignored when weblogic.httpd.logRotationType is set to date

Using Common Log format

The default format for logged HTTP information is the common log format. This standard format follows the pattern:

  host RFC931 auth_user
   [day/month/year:hour:minute:second UTC_offset]
   "request" status bytes

host: Either the DNS name or the IP number of the remote client
RFC931: Any information returned by IDENTD for the remote client; WebLogic does not support user identification
auth_user: If remote client user sent a userid for authentication, the user name; otherwise "-"
day/month/year:hour:minute:second UTC_offset: Day, calendar month, year and time of day (24-hour format) with the hours difference between local time and GMT, enclose in square brackets
"request": First line of the HTTP request submitted by the remote client enclosed in double quotes
status: HTTP status code returned by the server, if available; otherwise "-"
bytes: Number of bytes listed as the content-length in the HTTP/1.0 header, not including the HTTP/1.0 header, if known; otherwise "-"

Using extended log file format

The WebLogic Server also supports the extended log file format, version 1.0, as defined by the W3C. This is an emerging standard, and WebLogic follows the draft specification outlined at www.w3.org/TR/WD-logfile.html. This URL may be subject to change, but the current definitive reference may be found from the W3C page at www.w3.org/pub/WWW/TR.

The extended log format allows you to specify the type and order of information recorded about each HTTP communication. To enable the extended log format, set the following property in your weblogic.properties file, along with the other properties described above:

weblogic.httpd.logFileFormat=extended

You specify what information should be recorded in the log file with directives, included in the actual log file itself. A directive begins on a new line and starts with a # sign. If the log file does not exist, a new log file will be created with default directives. However, if the log file does already exist when the server starts, it must contain legal directives at the head of the file.

The first line of your log file must contain a directive stating the version number of the log file format. You must also include a Fields directive near the beginning of the file:

  #Version: 1.0
  #Fields: xxxx xxxx xxxx ...

Where each xxxx describes the data fields to be recorded. Field types are specified as either simple identifiers, or may take a prefix-identifier format, as defined in the W3C specification. Here is an example:

  #Fields: date time cs-method cs-uri

This would instruct the server to record the date and time of the transaction, the request method that the client used, and the URI of the request for each HTTP access. Each field is separated by whitespace, and each record is written to a new line, appended to the log file.

Note: The #Fields directive must be followed by a new line in the log file, so that the first log message is not appended to the same line.

Supported Field identifiers

The following identifiers are supported, and do not require a prefix.

date: Date at which transaction completed, field has type <date>, as defined in the W3C specification.
time: Time at which transaction completed, field has type <time>, as defined in the W3C specification.
time-taken: Time taken for transaction to complete in seconds, field has type <fixed>, as defined in the W3C specification.
bytes: Number of bytes transferred, field has type <integer>

Note that the cached field defined in the W3C specification is not supported in the WebLogic Server.

The following identifiers require prefixes, and cannot be used alone. The supported prefix combinations are explained individually.

IP address related fields:

These fields give the IP address and port of either the requesting client, or the responding server. This field has type <address>, as defined in the W3C specification. The supported prefixes are:

c-ip: The IP address of the client.
s-ip: The IP address of the server.

DNS related fields

These fields give the domain names of the client or the server. This field has type <name>, as defined in the W3C specification. The supported prefixes are:

c-dns: The domain name of the requesting client
s-dns: The domain name of the requested server

sc-status

Status code of the response, for example (404) indicating a "File not found" status. This field has type <integer>, as defined in the W3C specification.

sc-comment

The comment returned with status code, for instance "File not found". This field has type <text>

cs-method

The request method, for example GET or POST. This field has type <name>, as defined in the W3C specification.

cs-uri

The full requested URI. This field has type <uri>, as defined in the W3C specification.

cs-uri-stem

Only the stem portion of URI (omitting query). This field has type <uri>, as defined in the W3C specification.

cs-uri-query

Only the query portion of the URI. This field has type <uri>, as defined in the W3C specification.

Enabling event-based HTTP request information

After release 2.5, you can also register an interest in HTTP requests by registering at the topic WEBLOGIC.LOG.HTTPD. For more information on events, see Using WebLogic Events. The ParamSet that is passed with each EventMessage includes the following:

REMOTE_HOST
RFC931
AUTH_USER
DATE
REQUEST
STATUS
BYTES

To enable this feature, you must:

Set the property weblogic.httpd.enableEvents to true in the weblogic.properties file, as detailed in the WebLogic Administrators Guide document, Setting WebLogic properties.
Start the WebLogic Server and register an interest in the event WEBLOGIC.LOG.HTTPD.

Setting up session management

For an introduction to HTTP sessions, see the Developer's Guide, Using session tracking from a servlet.

The WebLogic Server is set up to handle session tracking by default. You need not set any of these properties to use session tracking, but configuring how WebLogic manages sessions is a key part of tuning your servlet application for best performance. This will depend upon factors such as:

How many users you expect to hit the servlet
How many concurrent users hit the servlet
How long each session will last
How much data you expect to store for each user

HTTP session properties

You configure WebLogic's session tracking with properties in the weblogic.properties file. (A summary list of all configuration properties are detailed in the WebLogic Administrators Guide, Setting WebLogic properties.) The relevant properties are described here in more detail:

weblogic.httpd.session.enable=true: By default, this property is set to true to enable session tracking using the HttpSession object in the WebLogic Server. You can disable session tracking by setting this property to false.
weblogic.httpd.session.timeoutSecs=x: Sets how long WebLogic waits before timing out a session, where x is the number of seconds between a session's activity. Sessions occupy RAM, and on busy sites you can tune your application by adjusting the time-out of sessions appropriately. While you want to give a browser client every opportunity to finish a session, you do not want to tie up the Server needlessly if the user has left the site or otherwise abandoned the session.(Defaults to 3600; minimum is 1, maximum is Integer.MAX_VALUE.)
weblogic.httpd.session.invalidationIntervalSecs=x: Where x sets how long WebLogic waits between doing house-cleaning checks for timed out and invalid sessions, at which point WebLogic will delete the old sessions and free up memory. Again, this is a parameter you use to tune the server for best performance on high traffic sites. If unset, the property defaults to 60 seconds; the minimum is every second (1), and the maximum is once a week (604,800 seconds).

Configuring session cookies

The WebLogic Server uses cookies for session management when supported by the client browser.

The cookies that the WebLogic Server uses to track sessions are set as transient by default and do not out-live the life of the browser. When a user quits their browser, the cookies are lost and the session lifetime is regarded as over. This behavior is in-the-spirit of session usage and it is recommended that you use sessions in this way. However, it is possible to configure many aspects of the cookies used to track sessions with the following properties in the weblogic.properties file.

weblogic.httpd.session.cookies.enable=boolean

Use of session cookies is enabled by default and is recommended, but you can disable them by setting this property to false. You might turn this option off to test URL rewriting on your site.

weblogic.httpd.session.cookie.comment=cookieComment

Sets the comment that is stored internally in the cookie. The user does not usually see this, but it appears in the cookie file to identify the cookie. This defaults to "WebLogic Session Tracking Cookie" if unset. You can set it to a more appropriate name for your application.

weblogic.httpd.session.cookie.domain

This property identifies the server that the browser shall send this cookie information to when the browser makes a request. This defaults to the server that issued the cookie. For example, .mydomain.com will send cookies back to any server in the *.mydomain.com domain. The domain name must have at least two parts; a name set to *.com or *.net is invalid. You will normally leave this unset to use the default. However, you can set this to a different server, causing the cookie to be sent there when the user visits.

weblogic.httpd.session.cookie.maxAgeSecs

This property sets the lifespan of the cookie, where x is the number of seconds that the cookie shall be valid before it expires on the client. This defaults to "-1" if unset, which sets the cookie to expire when the user exits the browser. The minimum value is 0, which means the cookie is cleaned up immediately (hardly ever used). The maximum value is MAX_VALUE, which means the cookie lasts essentially forever. It is recommended that you leave this value as "-1" which is in-the-spirit of session tracking. That is, a session should die when the user exits the browser.

For longer lived client-side user data, your application should create and set it is own cookies on the browser via the HTTP servlet API, and should not attempt to use the cookies associated with the HTTP session. Your application might use cookies to auto-login a user from a particular machine, in which case you would set a new cookie to last for a long time. Remember that the cookie will only be sent from that client machine; Your application should store data on the server if it must be accessed by the user from multiple locations.

Note that you can't directly connect the age of a browser cookie with the length of a session. If a cookie goes away before its associated session, that session becomes orphaned. If a session goes away before its associated cookie, the servlet will not be able to find a session. At that point, a new session will be assigned when the getSession() method is called. You should only make transient use of sessions.

weblogic.httpd.session.cookie.name

Defaults to "WebLogicSession" if unset. You may set this to a more appropriate name for your application. When you are using in-memory replication, the session cookie name must be the same as the cookie name set in the NSAPI plugin using the parameter "CookieName". Cookie names have local scope to the issuing domain, so there is no problem with conflicts between your server and other servers. However, two or more applications that use session tracking and run on the same server will use the same cookie, and hence share the same session. This is one reason why sessions should be treated as transient data stores.

weblogic.httpd.session.cookie.path

Defaults to "/" if unset, which means that the browser will send cookies to all URLs served by the WebLogic Server. You can set the path to a narrower mapping to limit the request URLs that the browser will send cookies to.

For more information on setting configuration properties, see the WebLogic Administrators Guide, Setting WebLogic properties.

Configuring session persistence

For an introduction to HTTP session persistence, see the Developers Guide, Making sessions persistent.

There are four different implementations of session persistence:

Memory (single-server, non-replicated)
File system persistence
JDBC persistence
In-memory replication (across a cluster)

The first three are covered here; in-memory replication is covered in the Administrators Guide Setting up a WebLogic Cluster: Using in-memory state replication with a proxy server.

For each method, you will need to specify the value of the property weblogic.httpd.session.persistence.

For file, JDBC and in-memory replication, you will need to set additional properties, including the weblogic.httpd.session.persistentStoreType. Each method has its own set of properties as shown below.

Common properties

You can configure the number of sessions that are held in RAM by setting the following properties. These properties are only applicable if you are using session persistence:

weblogic.httpd.session.cacheEntries=x: Where x limits the number of cached sessions at any time. If you are expecting high volumes of simultaneous active sessions, you do not want these sessions to soak up the RAM of your server since this may cause performance problems swapping to and from virtual memory. When the cache is full, the least recently used sessions are stored in the persistent store and recalled automatically when required. If you do not use persistence, this property is ignored, and there is no soft limit to the number of sessions allowed in main memory. By default, the number of cached sessions is 1024. The minimum is 16, and maximum is Integer.MAX_VALUE. An empty session uses less than 100 bytes, but will grow as data is added to it.
weblogic.httpd.session.swapIntervalSecs=x: Where x is the interval the server waits between purging the least recently used sessions from the cache to the persistent store, when the cacheEntries limit has been reached.
If unset, this property defaults to 10 seconds; minimum is 1 second, and maximum is 604800 (1 week).

Using memory-based, single-server, non-replicated persistent storage

To use memory-based, single-server, non-replicated persistent storage, set the property:

  weblogic.httpd.session.persistence=false

Using file-based persistent storage

For file-based persistent storage for sessions:

Set the session persistence to true:

  weblogic.httpd.session.persistence=true

Set file as the persistent store method by setting the property:
```
  weblogic.httpd.session.persistentStoreType=file
```
Set the directory where WebLogic will store the sessions, using property:
```
  weblogic.httpd.session.persistentStoreDir=dirPath
```
where dirPath is either a directory relative to the myserver/ directory in your WebLogic installation or an absolute path. Ensure that you have enough room on disk to store the number of valid sessions multiplied by the size of each session.
You can make file-persistent sessions cluster-able by making this directory a shared directory amongst different servers.
You will need to create this directory manually.

Using a database for persistent storage

For JDBC-based persistent storage for sessions:

Set the session persistence to true:

  weblogic.httpd.session.persistence=true

Set jdbc as the persistent store method by setting the property:
```
  weblogic.httpd.session.persistentStoreType=jdbc
```
Set a JDBC connection pool to be used for the persistence storage:
```
  weblogic.httpd.session.persistentStorePool=virtualPoolName
```
Note: virtualPoolName must be a JDBC connection pool that is only used by JTS pool drivers. In other words, you cannot use a JDBC connection that is used by non-JTS drivers. To be safe, you should create a separate JDBC pool for session persistence; but you can share a JDBC pool that is used only for servlet session persistence and/or EJB, since these use JTS pool drivers.
The JTS pool driver uses a JDBC pool to support special transactional connections that do not operate in the same way as straight JDBC pool connections. JTS transactions are used by EJB and by servlet persistence. Regular JDBC connections use a weblogic.jdbc.pool.Driver class, but servlet persistence uses a proxy weblogic.jts.pool.Driver class. Although you set up both types of pools with the same property name (weblogic.jdbc.connectionPool), you can't mix JTS and regular traffic in the same connection.
For more details on setting up a database connection pool, refer to Setting up registration for a connection pool later in this document, and the JDBC connection pools section in the Administrators Guide document, Setting WebLogic properties.
To recap, you might use a non-JTS connection pool in your servlet for general database access, but you can not use the same connection pool to support session persistence.
Set an ACL for the connection pool that corresponds to the users that have permission.
Set this property to the name of the connection pool.
If the back-end database will be used by multiple WebLogic Servers for JDBC-based persistence, set the property:
```
  weblogic.httpd.session.persistentStoreShared=true
```
This property refers to whether database reads are cached. Generally, clustered environments will want persistentStoreShared=true, that is always check the database, but for non-clustered environments using persistentStoreShared=false improves performance with caching.

Set up a database table named wl_servlet_sessions for JDBC-based persistence. The connection pool that connects to the database will need to have read/write access for this table:

wl_servlet_sessions table

Column name Type
wl_id Must be set as a primary key. Variable-width alphanumeric column, up to 100 characters; for example, Oracle VARCHAR2(100)

wl_context_path Variable-width alphanumeric column, up to 100 characters; for example, Oracle VARCHAR2(100). This column is used as part of the primary key. (See the wl_id column description.)

wl_is_new Single char column; for example, Oracle CHAR(1)

wl_create_time Numeric column, 20 digits; for example, Oracle NUMBER(20)

wl_is_valid Single char column; for example, Oracle CHAR(1)

wl_session_values Large binary column; for example, Oracle LONG RAW

wl_access_time Numeric column, 20 digits; for example, NUMBER(20)

You can configure a maximum duration that the JDBC session persistence should wait for a JDBC connection from the connection pool before failing to load the session data wit the property:
```
  weblogic.httpd.session.jdbc.connTimeoutSec=x
```
where x is the number of seconds that the servlet will wait for a connection. The default value is 120 seconds, the minimum is 1 second, and the maximum is 604800 seconds (1 week).