Using WebLogic Server as an HTTP server

WebLogic Server as an HTTP server (HTTPD)

Setting up WebLogic Server as an HTTP server

Serving requests over HTTP with WebLogic Server

Setting up a document root

Setting up the FileServlet

Setting up a default page

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

Setting standard MIME types

Referring to servlets in a browser

Setting up WebLogic Server 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

WebLogic Server as an HTTP server (HTTPD)

The WebLogic Server can be used as your primary webserver. WebLogic Server is designed to serve Java class files (servlets), arbitrary file types (like HTML pages, JAR files, etc) and images, and can be set up to proxy requests to another webserver, even another webserver on a different machine.

Setting up WebLogic Server as an HTTP Server

There are four steps to setting up WebLogic Server as an HTTP server (HTTPD).

Step One: Install the WebLogic Server distribution on the server host.

Step Two: Choose the appropriate properties from the list below and set them in the weblogic.properties file.

General HTTPD Properties
• weblogic.httpd.enable must be set to true to allow the HTTP server (HTTPD) to run.
• Each servlet that will respond to requests over HTTP, must be registered with weblogic.httpd.register.virtualName . Additionally, if you wish to limit access to registered servlets, you can set up access control lists.
• You can choose whether users can browse directory listings. In 4.5.2 and 4.5.1 service pack 6 or greater, directory listing is turned off by default, in 4.5.1 service pack 5 or below, the default setting allows directory listing. To disable directory listing, set weblogic.httpd.indexDirectories=false.
  Default Servlet

• The default servlet receives all requests that are not registered. In the distribution, the weblogic.httpd.defaultServlet is set to the file servlet. If you wish, you can set the default servlet to the proxy servlet, which will proxy all unregistered requests to another Webserver. There is more information about using the proxy servlet in this document.
  HTTPD Log

• weblogic.httpd.enableLogFile and weblogic.httpd.logFileName must be set to enable HTTP server logs. For more information, see Running and maintaining the WebLogic Server.
• weblogic.system.maxLogFileSize controls (in K) the maximum size of the log files.
  SSL

• SSL properties must be set to use SSL.
  Treating HTTPD Requests as Events

• weblogic.httpd.enableEvents must be set to true, you must register an interest in WEBLOGIC.LOG.HTTPD events in order to treat HTTPD requests as events.
  Using the Multihome Feature

• weblogic.system.bindAddr must be set to the domain name or IP address where the WebLogic Server should listen. For more information on setting up multiple WebLogic Servers on a multihomed machine, see Setting up and starting a WebLogic Server.
  Unix

• To use the HTTPD on a Unix system, you must set the weblogic.system.enableSetUID and weblogic.system.nonPrivUser properties. Instructions for setting these properties are found in Setting WebLogic Server properties.

For more information, see Setting WebLogic Server properties. You use properties to register servlets, set up the proxy servlet, and set up other servlets, all of which are described in more detail in that document.

Step Three: An additional step for Unix

Although WebLogic Server is pure-Java and requires no installation of native code, 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. For security reasons, you do not want to run your web server from a root account. To add an additional layer of security, we ship a UNIX shared object that allows WebLogic Server to run from a non-priveledged account.

To use the shared object, go to the weblogic/lib/UNIX_VERSION directory for the machine that you are using. Install libweblogicunix1.so (general UNIX) or libweblogicunix1.sl (for HPUX 10/11) in your LD_LIBRARY_PATH (UNIX) or SHLIB_PATH (HPUX). (If you have problems, see using shared libs on UNIX.)

If you prefer, instead of installing the shared object, you can simply add the appropriate directory weblogic/lib/UNIX_VERSION
to your LD_LIBRARY_PATH (UNIX) or SHLIB_PATH (HPUX).

Step Four: Run WebLogic Server.

Serving requests over HTTP with WebLogic Server

Setting up a document root

The document root is where the FileServlet, the JSPServlet, and the ServerSideIncludeServlet search for files to serve. HTML, JSP, and SHTML files and images that will be served through browser requests must be placed in the document root (or one of its subdirectories). Additionally, HTML files that serve applets should be placed here, even though the CODEBASE (and the supporting classes) for the applet are located in a different directory structure.

The default document root for WebLogic Server is the weblogic/myserver/public_html directory. You can change the location of the documenet root by setting a property in the weblogic.properties file:

weblogic.httpd.documentRoot=path

Setting up the FileServlet

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

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

2. 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 is set to "index.html" or "home.html" to protect the directory from being scanned in the browser (see general HTTPD properties to set access of directory listings). This sample entry from the weblogic.properties file shows how the initialization arguments might be set up:

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

3. 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 place "myapplet.html" in c:/weblogic/myserver/public_html, requests to serve the HTML page from the WebLogic Server on your local host should have this form:

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

Setting up a default page

Serving static default pages

A static default page is served by the FileServlet, and is typically set below the FileServlet registration in the weblogic.properties file, as shown below.

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

If the URL request is a directory, the FileServlet will attempt to serve a file of the set default filename from the requested directory. If the default filename does not exist in that directory, either a directory listing (if weblogic.properties.indexDirectories=true) or an HTTP error (403 for 4.5.2 and 4.5.1 service pack 6 and above, 404 for 4.5.1 service pack 5 and below) will be returned.

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

Serving dynamic default pages

WebLogic Server can serve dynamic default files, delivered by the JSPServlet, the PageCompileServlet, or your own custom servlet. To serve dynamic pages as the default for a directory, you register the dynamic page(s) with the folowing property:

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

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

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 set 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".

Resolving which default page will be served

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.

To be used in the standard manner, HTTP Servlets must be registered with the weblogic.httpd.register property in the weblogic.properties file. 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.

For more information on registering servlets, see Setting WebLogic properties.

Serving Java servlets using the ServletServlet

The ServletServlet 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. However, in a development environment, you may wish to invoke HTTP servlets that are not registered in the properties file. For more information about writing servlets and the ServletServlet see, "Using WebLogic HTTP Servlets".

Setting up the ClasspathServlet

The ClasspathServlet loads class files from the WebLogic Server 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 Server classpath. With the ClasspathServlet, WebLogic Server searches its entire classpath to find classes for a request. This allows multiple directory structures with class files to be equally accessible to WebLogic Server.

1. 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.

   For example:

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

2. Place your applet class files in the WebLogic Server classpath, as you would for a regular Java class file. The WebLogic Server 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 Server host in the directory c:\appletdir\myapplets\mypackage\OpenTheTour.class, where the C:\appletdir is included in the weblogic.class.path property.

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

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

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

6. 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.

7. The classes for the applet will be loaded from the WebLogic Server's classpath.

Proxying requests to another HTTP server

1. 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.

2. To proxy all requests that are not registered with WebLogic Server to a different Webserver, register the proxy servlet as the default servlet in the weblogic.properties file:

   weblogic.httpd.defaultServlet=proxy

   Note that the default filename will not be served by WebLogic Server if the default servlet is the proxy servlet.

This example shows a sample request and how it would be handled:

1. On a WebLogic Server "toyboat.toybox.com," a request is received for http://toyboat.toybox.com/Docs/SomeFile.html. However, that file does not exist in any of the configured WebLogic Server's searchable directories or document root.

2. 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.

3. 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. WebLogic Server supports both the JSP (JavaServer Pages) and JHTML standards.

WebLogic Server can automatically compile JHTML or JSP files into servlets and call upon them to respond to HTTP requests. For more information on writing JSP or JHTML, see Using WebLogic JHTML, and Using WebLogic JSP.

WebLogic Server uses special page-compile-servlets for compiling and delivering JSP and JHTML pages, which must be registered 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.

Warning!

If you use WebLogic Server 4.5.1 on Windows NT to serve JHTML or JSP pages, add the following property to your weblogic.properties file:

weblogic.httpd.servlet.extensionCaseSensitive=true

Without this property, and depending on how the page is requested, WebLogic Server may return the source of a JHTML or JSP page instead of compiling and executing the page. This is fixed in WebLogic Server 4.5.1 service pack 10 and in WebLogic Server 4.5.2.

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

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

There are more details on registration in the 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 Server 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 Setting WebLogic Properties. For information on developing JSP, see Using WebLogic JSP.

Using server-side includes

The WebLogic Server supports server-side includes using a default WebLogic servlet called the ServerSideIncludeServlet. The ServerSideIncludeServlet is registered in the weblogic.properties file to handle all .shtml files using this property:

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

Setting standard MIME types

  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

Referring to servlets in a browser

When you register a servlet -- and optionally set up an access control control list for it -- you then refer to that servlet with its virtual name, which is the registered name. Each time you change a registered servlet or any classes on which it depends, you must restart WebLogic Server for the changes to take effect. (Note that during development, you may find it easier to use the ServletServlet, which does not require restarting the Server.)

You invoke the servlet from a browser window by entering its virtual name. For example, the properties file contained in the distribution kit registers a servlet in the package examples.servlets.PhoneServlet, to be invoked with the virtual name "phone." It requires one initialization argument, the full pathname for the text file "phonelist" that contains names and phone numbers. To register this servlet and set its initialization arguments, these lines should appear in your properties file:

  weblogic.httpd.register.phone=examples.servlets.PhoneServlet
  weblogic.httpd.initArgs.phone=\
      phonelist=c:/weblogic/examples/servlets/phonelist

To use this servlet, you point your browser at the URL of the WebLogic Server, with the virtual name of the registered servlet. For a WebLogic Server listening on port 80 of the host "www.abc0.com", you would enter this URL in your browser window:

  http://www.abc0.com/phone

Several servlets come with the distribution to provide administrative and maintenance functions. These include the T3Admin servlets.

The T3Admin servlets are already registered in the default properties file in the distribution. For more information about using the T3Admin servlets, see the WebLogic Administrators Guide document Using the T3Admin servlets.

Also included in the file, but commented out, are several servlets from the weblogic/examples directory of the distribution. You can register these servlets to see how they work by uncommenting the weblogic.properties file and restarting the WebLogic Server. For more information about using the example servlets, see the Code Examples.

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 Server 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

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

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

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.

Enabling and using the HTTP server logs

All WebLogic Server information will continue to be written to the weblogic.log file; the subset of log information that has to do with HTTP access will be written to the file access.log. The access log for the HTTP server is available in the WebLogic Server directory that is parallel to your weblogic.properties file. The default location, if you have only one WebLogic Server running and have not assigned it a name, is in the myserver directory. The WebLogic Server weblogic.log is also located in this directory; if you have enabled JDBC logging, that log will also be located in the myserver directory.

The access.log for WebLogic Server is written in common log format. Each line in this file is patterned after the following format:

  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 "-"

Note that unless you set up access log rotation, the access log will grow indefinitely, and must be maintained manually.

Setting up access log rotation

• WebLogic Server 4.5.1, Service Pack sp12 or later.
• WebLogic Server 4.5.2, Service Pack sp1 or later.
• WebLogic Server 5.1, Service Pack sp5 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

Enabling event-based HTTP request information

• REMOTE_HOST
• RFC931
• AUTH_USER
• DATE
• REQUEST
• STATUS
• BYTES

To enable this feature, you must:

1. Set the property weblogic.httpd.enableEvents to true in the weblogic.properties file, as detailed in the WebLogic Administrators Guide document, Setting WebLogic properties.

2. 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 Server 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 Server session tracking with properties in the weblogic.properties file. (A summary of all configuration properties is in 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 Server 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 Server waits between doing house-cleaning checks for timed out and invalid sessions, at which point WebLogic Server 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. The default is "-1", 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 its 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 ca not 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 you application. 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 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:

1. Memory (single-server, non-replicated) -- fast, short-term storage

2. File system persistence -- slower, long-term storage, does not require a database

3. JDBC persistence -- slower, long-term storage

4. In-memory replication (across a cluster)

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

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

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

Common properties

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:

1. Set the session persistence to true:

     weblogic.httpd.session.persistence=true

2. Set file as the persistent store method by setting the property:

   
   weblogic.httpd.session.persistentStoreType=file

3. Set the directory where WebLogic Server will store the sessions, using the property:

   
   weblogic.httpd.session.persistentStoreDir=dirPath

   where dirPath is a manually created directory, either relative to the myserver/ directory in your WebLogic Server 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.

Using a database for persistent storage

For JDBC-based persistent storage for sessions:

1. Set the session persistence to true:

   
   weblogic.httpd.session.persistence=true

2. Set jdbc as the persistent store method by setting the property:

   
   weblogic.httpd.session.persistentStoreType=jdbc

3. 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 not 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.

4. Set an ACL for the connection pool that corresponds to the users that have permission.

5. Set this property to the name of the connection pool.

6. 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.

7. 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_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	BLOB column; for example, Oracle LONG RAW
   wl_access_time	Numeric column, 20 digits; for example, NUMBER(20)

8. You can configure a maximum duration that the JDBC session persistence should wait for a JDBC connection from the connection pool with 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).

Copyright © 2000 BEA Systems, Inc. All rights reserved.
Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.
Last updated 12/07/1999