J2EE Doc Bundle Home
Java

JavaTM 2 SDK, Enterprise Edition
Configuration Guide

Version 1.2.1

 

Revised: 5/1/00

Contents

Introduction

This release stores configuration information in a set of properties files that reside in the config directory. You may edit these files with a text editor. This document describes the configuration parameters that you may edit in the properties files.

In most cases, you won't have to make any changes to the properties files. However, if you wish to use a database driver other than Cloudscape, you'll need to follow the instructions in the next section.

JDBCTM Drivers

This release includes a JDBC driver for the Cloudscape DBMS. This driver is already configured in the config/default.properties file. No further changes by you are necessary. By default, Cloudscape databases will be created in the cloudscape directory.

If your enterprise beans use the JDBC API to access a database other than Cloudscape, then you must configure the JDBC drivers according to the instructions in the sections that follow. (If you aren't sure if this release supports your JDBC driver, see the Supported Databases and JDBC Drivers section of the Release Notes.)

Driver Location

You must copy the JDBC driver .jar files to the $J2EE_HOME/lib/system directory. (Files in this directory have the java.security.AllPermission, needed because a driver may perform privileged operations.) Be sure to include the classpath to these .jar files in the J2EE_CLASSPATH environment variable.

The J2EE_CLASSPATH Environment Variable

The J2EE server uses a JDBC driver to access a database. It locates the driver's .jar files by referencing the J2EE_CLASSPATH environment variable. You can set this environment variable on the command line before you run the J2EE server. However, we recommend that you set J2EE_CLASSPATH in the user configuration script. Editing the user configuration script is a required step during the installation procedure. On UNIX the user configuration script is in bin/userconfig.sh, and on Windows it is in bin\userconfig.bat.

Note: You should remove the driver .jar files from the CLASSPATH environment variable.

About XA Datasource Support

Drivers that support XA datasources allow you to connect to multiple databases and to distribute transactions across machines or processes. JDBC 1.0 drivers do not support XA datasources. Some JDBC 2.0 drivers support XA datasources and some do not. If you do not know whether or not your driver supports XA datasources, please check with the driver's vendor.

If your driver does not support XA datasources, you must follow the instructions in the section, Drivers Without XA Datasource Support.

If your driver supports XA datasources, to take advantage of XA's features you must follow the instructions in the section, Drivers with XA Datasource Support.

If your driver supports XA datasources and you follow the instructions in the section, Drivers Without XA Datasource Support, the driver will work but cannot take advantage of XA's features.

Drivers Without XA Datasource Support

To configure a driver without XA datasource support, you set values for the jdbc.drivers and jdbc.datasources property names by editing the config/default.properties file. You must also include the classpath of the JDBC driver in the J2EE_CLASSPATH environment variable.

The jdbc.drivers Property

The jdbc.drivers property value is a list of JDBC driver class names separated by colons. The syntax follows:

jdbc.drivers=<classname>:<classname>: . . .
Here is an example:

jdbc.drivers=oracle.jdbc.driver.OracleDriver:testutil.MyDriver

The jdbc.datasources Property

The jdbc.datasources property value links the JNDI name of a DataSource with the URL of a database. Typically, the JNDI name is the logical name of a database. The URL specifies the actual location of a database. Neither the JNDI name nor the URL are hardcoded in the source code of an enterprise bean. To determine the format of the URL, please check the documentation provided by the vendor of the JDBC driver.

The syntax of jdbc.datasources follows:

jdbc.datasources=<jndi_datasource>|<url>|<jndi_datasource>|<url>. . .
.

The pipe character (|) serves two purposes. First, it separates the <jndi_datasource> and <url> elements that form a pair. Second, it delimits each pair of <jndi_datasource> and <url> elements.

The <jndi_datasource> element has the following syntax:

jdbc/<jndi_name>
The jdbc keyword is followed by a forward slash. The <jndi_name> is the name of the DataSource that is entered in the JNDI directory.

Here is an example:

jdbc.datasources=jdbc/Oracle|jdbc:oracle:thin@rtc:1521:acct|jdbc/MyDB|jdbc:test

Drivers with XA Datasource Support

To configure a driver that supports XA datasources, you set values for the following property names:

jdbc20.datasources
xadatasource.<n>.jndiname
xadatasource.<n>.classname
xadatasource.<n>.dbuser
xadatasource.<n>.dbpassword
xadatasource.<n>.prop.<property-name>
You must also include the classpath of the JDBC driver in the J2EE_CLASSPATH environment variable.

The jdbc20.datasources Property

The jdbc20.datasources property value links the JNDI name used to locate the DataSource (the parameter of the lookup method) with the JNDI name of the XA DataSource.

The syntax of jdbc20.datasources follows:

jdbc20.datasources=<jndi_datasource>|<jndi_XA_datasource>|<jndi_datasource>|<jndi_XA_datasource>. . .

.

The pipe character (|) serves two purposes. First, it separates the <jndi_datasource> and <jndi_XA_datasource> elements that form a pair. Second, it delimits each pair of <jndi_datasource> and <jndi_XA_datasource> elements.

The <jndi_datasource> and <jndi_XA_datasource> elements have the same syntax:

jdbc/<jndi_name>
The jdbc keyword is followed by a forward slash. The <jndi_name> is the name of the DataSource that is entered in the JNDI directory.

Here is an example:

jdbc20.datasources=jdbc/Merant|jdbc/XAMerant|jdbc/Finch|jdbc/XAFinch

The xadatasource Properties

The xadatasource.<n>.jndiname property specifies the JNDI name of the XA DataSource. It has the following syntax:

xadatasource.<n>.jndiname=jdbc/<jndi_XA_datasource>
The <n> integer links each group of xadatasource properties. For the first driver <n> should be 0, for the next it should be 1, then 2, and so forth. The <jndi_XA_datasource> element matches that specified by the jdbc20.datasources property.

The xadatasource.<n>.classname property specifies the class name of the XA DataSource.

The xadatasource.<n>.dbuser and xadatasource.<n>.dbpassword properties specify the database user and password used to sign on to the database to perform recovery. Usually, this database user will have the database administrator privilege. (For more information on recoveries, see the section, The distributed.transaction.recovery Property.)

The xadatasource.<n>.prop.<property_name> specifies the value associated with a particular property name. The actual property names may vary with the JDBC driver.

An example follows:

xadatasource.0.jndiname=jdbc/XAMerant
xadatasource.0.classname=com.merant.sequelink.jdbcx.datasource.SequeLinkDataSource
xadatasource.0.prop.url=jdbc:sequelink://mypc:5000/[Oracle]

Transactions

You can control transaction recoveries and timeouts by editing the config/default.properties file.

The distributed.transaction.recovery Property

This property controls whether or not distributed transactions will be recovered. For these transactions to be recovered, the following conditions must be met: The transaction encompasses multiple databases. The J2EE application accesses the databases with a JDBC driver that supports XA datasources. All of the parties involved in the 2-phase commit protocol have agreed to commit (or rollback) the transaction when the crash occurs. When the server starts up again, the transaction will be committed (or rolled back) during the recovery process.

The value of this property may be either true or false. When J2EE is first installed, the value is false:

distributed.transaction.recovery=false

The transaction.timeout Property

For enterprise beans with container-managed transactions, you control the transaction timeout interval by setting the value of the transaction.timeout property. For example, you would set the timeout value to 5 seconds as follows:

transaction.timeout=5
With this setting, if the transaction has not completed within 5 seconds, the J2EE transaction manager rolls it back.

When J2EE is first installed, the timeout value is set to 0:

transaction.timeout=0
If the value is 0, the transaction will not time out.

Only enterprise beans with container-managed transactions are affected by the transaction.timeout property. For enterprise beans with bean-managed, JTA transactions, you invoke the setTransactionTimeout method of the UserTransaction interface. You also invoke the setTransactionTimeout method for other components, such as servlets and JSP pages, that demarcate transaction with the UserTransaction interface.

Port Numbers

The JavaTM 2 SDK, Enterprise Edition requires three TCP/IP ports. To change a port number, edit the appropriate properties file in the config directory. The following table lists the ports and their corresponding properties files.

TABLE 0-1 JavaTM 2 SDK, Enterprise Edition Ports
Service
Using the Port

 Default
Port Number

 Properties File

 Default Entry
in Properties File

 Description

EJB 9191 ejb.properties http.port=9191 The EJB service uses this port to download stub classes to clients.
HTTP 8000 web.properties port=8000 The HTTP service uses this port to service requests.
HTTPS 7000 web.properties https.port=7000 The HTTPS service uses this port to service requests.
Naming and Directory 1050 orb.properties port=1050 The ORB (Object Request Broker) underlying the JNDI name server uses this port.

Log Files

The J2EE server generates several log files. By default, these files reside in the logs directory. To change the default directory, edit the value of the log.directory property of the config/default.properties file:

log.directory=logs
You can also change the names of several log files by editing the default.properties file. For example, you can change the name of the output.log file by modifying the value of the log.output property.

The log files generated depend on whether you launch j2ee in the single or multiple VM (virtual machine) mode.

Single VM Log Files

By default, j2ee runs in a single virtual machine. In this mode, the log files reside in the directory specified by this syntax:

$J2EE_HOME/<logs>/<host>/ejb
The <logs> element is the directory specified by the log.directory entry in the default.properties file. The default value is logs. The <host> element is the name of the computer.

The following log files are generated:

system.out
system.err
event.log
output.log
error.log
audit.log
The system.out and system.err files contain the output generated by enterprise beans that write to System.out and System.err. If you run j2ee with the verbose option, this output is written to stdout and stderr; the system.out and system.err log files are not created. The audit.log file is generated only if the audit property of the config/auth.properties file equals true.

Multiple VM Log Files

If you launch j2ee with the multiVM option, the EJB and HTTP services run as separate servers in their own VMs. Each deployed application also runs in its own VM. The log files generated are the same as those listed in the previous section, but they reside in different directories.

TABLE 0-2 Log File Directories in Multiple VM Mode
Server Generating Log Files

 Syntax of Log File Directory

EJB $J2EE_HOME/<logs>/ejb/ejbd
HTTP $J2EE_HOME/<logs>/ejb/httpd
deployed application $J2EE_HOME/<logs>/ejb/<app-name>

Web Service Log Files

To modify the names of the log files created by the web service, edit these entries in the web.properties file:

access.log=access.log
error.log=error.log

Security

Unauthenticated User Name

According to the J2EE specifications, when unauthenticated web clients make calls to the EJB container, they must have a credential of a generic unauthenticated user. (This user might be maunfactured by the web container-- it depends on the implementation.) In the JavaTM 2 SDK, Enterprise Edition, the unauthenticated user is called guest and the password for this user is guest123. You can modify the name of the unauthenticated user and password by modifying the following entries in the auth.properties file:

default.principal.name=guest
default.principal.password=guest123

Keystore Password

If users generate public key certificates for HTTPS support, these certificates are created in the directory <user-home>/.keystore file. (Where <user-home> is the value returned by System.getProperty("user.home").)

The .keystore file is typically protected by a password. By default, this password is changeit. You can modify the password by editing the keystore.password entry in the web.properties file.

ANYONE Role

In the Security tabbed pane of the Application Deployment Tool, methods are assigned the ANYONE role by default. This role represents the universal set of all users and groups. Therefore, if you do not map a method to a role (in the Application Deployment Tool), then any user or group may invoke the method. You may change the default ANYONE role by editing the anyone.role.name entry in the auth.properties file.

Memory Threshold for Passivation

When the EJB container passivates an enterprise bean, it saves the bean in secondary storage and attempts to reclaim memory. By default, passivation occurs when memory usage exceeds 128 megabytes. To change the default, you can modify the value of the passivation.threshold.memory property in the config/default.properties file:

passivation.threshold.memory=128000000
The value must be a positive integer. If you decrease the value of this property then passivation will occur more often.

HTTP Document Root

By default, the document root of the HTTP and HTTPS services is public_html. You may change the document root by editing the documentroot entry of the web.properties file. This entry is always relative to the J2EE_HOME environment variable. Here is the default entry in web.properties:

documentroot=public_html/

Copyright © 2000 Sun Microsystems, Inc. All rights reserved.