|
| |
| Sun Java System Application Server Platform Edition 2004Q4 Beta Reference | |
Chapter 1
The domain.xml FileThis chapter describes the domain.xml configuration file in these sections:
About the domain.xml FileThe domain.xml file contains most of the Sun Java™ System Application Server configuration. The encoding is UTF-8 to maintain compatibility with regular UNIX text editors. The domain.xml file is located in the domain configuration directory, which is typically domain_dir/config. This file is further described in the following sections:
The sun-domain_1_1.dtd File
The sun-domain_1_1.dtd file defines the structure of the domain.xml file, including the elements it can contain and the subelements and attributes these elements can have. The sun-domain_1_1.dtd file is located in the install_dir/lib/dtds directory.
For general information about DTD files and XML, see the XML specification at:
Note
Subelements must be defined in the order in which they are listed under each Subelements heading in this chapter unless otherwise noted.
Default Values
In this manual, the term default is used in its broader sense, and not in the specific way it is used in the XML 1.0 standard. A default value is an initial value or the value used if no value is present in the XML file. A default value can be any of the following:
- A value supplied by the XML parser when no value is found in the domain.xml file. The relevant element or attribute is optional.
- A value supplied by the Sun Java System Application Server when no value is found in the domain.xml file and the XML parser doesn’t provide a value. The relevant element or attribute is optional.
- An initial value supplied when the domain.xml file is created. The relevant element or attribute might or might not be optional.
Variables
Variables and variable references are needed for two reasons:
Variable references appear in the domain.xml file as strings that begin with the characters ${ and end with the character }. For example, the string ${com.sun.enterprise.myVar} is a reference to the variable com.sun.enterprise.myVar.
Variables are defined both outside of and within domain.xml. Predefined variables that exist outside of domain.xml are defined as Java System Properties. Within domain.xml, a variable is defined using the system-property element or the jvm-options element.
The system-property element’s name attribute is the name of a variable; its value attribute is the definition of the variable. For example, the following system-property element defines a port-number variable with the value 6500:
<system-property name="port-number" value="6500"/>
Multiple system-property subelements are permitted within server, config, and domain elements.
A variable defined in the jvm-options element is a Java System Property with the -D flag. For example, the following jvm-options element defines a port-number variable with the value 5500:
<jvm-option>-Dport-number=5500</jvm-option>
Multiple definitions for the same variable are permitted. The Sun Java System Application Server determines the actual value of a variable by searching for its first definition in a strict hierarchy of the elements within domain.xml. The hierarchy is as follows:
server -> config -> jvm-options -> domain -> System
Implicit in this hierarchy is the notion of reference and containment. A variable referenced in a server element is only looked up:
Element Referencing
One element references another when an attribute of the referencing element has the same value as an attribute of the referenced element. For example, the application-ref element references an application or module that is deployed to its parent server element. The application-ref element’s ref attribute has the same value as the name attribute of a lifecycle-module, j2ee-application, ejb-module, web-module, connector-module, or appclient-module element.
The referencing application-ref element might look like this:
<application-ref ref="MyServlet"/>
The referenced web-module element might look like this:
<web-module name="MyServlet" location="myservletdir"/>
Element Hierarchy
The element hierarchy for the domain.xml file is as follows. To make the hierarchy more readable, elements having property as their last or only subelement are marked with a P, and the property subelements are not shown. Parent/child relationships between elements are shown, but not order or cardinality. For those details, see the element descriptions.
domain P
. applications
. . lifecycle-module P
. . . description
. . j2ee-application
. . . description
. . web-module
. . . description
. . ejb-module
. . . description
. . connector-module
. . . description
. . appclient-module
. . . description
. resources
. . custom-resource P
. . . description
. . external-jndi-resource P
. . . description
. . jdbc-resource P
. . . description
. . mail-resource P
. . . description
. . persistence-manager-factory-resource P
. . . description
. . admin-object-resource P
. . . description
. . connector-resource P
. . . description
. . resource-adapter-config P
. . jdbc-connection-pool P
. . . description
. . connector-connection-pool P
. . . description
. . . security-map
. . . . principal
. . . . user-group
. . . . backend-principal
. configs
. . config P
. . . http-service P
. . . . http-listener P
. . . . . ssl
. . . . virtual-server P
. . . iiop-service
. . . . orb P
. . . . ssl-client-config
. . . . . ssl
. . . . iiop-listener P
. . . . . ssl
. . . admin-service P
. . . . das-config P
. . . connector-service
. . . web-container P
. . . . session-config
. . . . . session-manager
. . . . . . manager-properties P
. . . . . . store-properties P
. . . . . session-properties P
. . . ejb-container P
. . . . ejb-timer-service P
. . . mdb-container P
. . . jms-service P
. . . . jms-host P
. . . log-service P
. . . . module-log-levels P
. . . security-service P
. . . . auth-realm P
. . . . jacc-provider P
. . . . audit-module P
. . . . message-security-config
. . . . . provider-config P
. . . . . . request-policy
. . . . . . response-policy
. . . transaction-service P
. . . monitoring-service P
. . . . module-monitoring-levels P
. . . java-config P
. . . . profiler P
. . . . . jvm-options
. . . . jvm-options
. . . thread-pools
. . . . thread-pool
. . . alert-service P
. . . . alert-subscription
. . . . . listener-config P
. . . . . filter-config P
. . . system-property
. . . . description
. servers
. . server P
. . . application-ref
. . . resource-ref
. . . system-property
. . . . description
. system-property
. . description
Alphabetical List of ElementsA B C D E F H I J L M O P R S T U V W
Aadmin-object-resource
Defines an administered object for an inbound resource adapter.
Subelements
The following table describes subelements for the admin-object-resource element.
Table 1-1 admin-object-resource Subelements
Element
Required
Description
zero or one
Contains a text description of this element.
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the admin-object-resource element.
Table 1-2 admin-object-resource Attributes
Attribute
Default
Description
jndi-name
none
Specifies the JNDI name for the resource.
res-type
none
Specifies the fully qualified type of the resource.
res-adapter
none
Specifies the name of the inbound resource adapter, as specified in the name or resource-adapter-name attribute of a resource-adapter-config element.
object-type
user
(optional) Defines the type of the resource. Allowed values are:
enabled
true
(optional) Determines whether this resource is enabled at runtime.
Properties
The following table describes the most commonly used JMS properties for the admin-object-resource element. For a complete list of the available properties (called administered object attributes in Sun Java System Message Queue), see the Sun Java System Message Queue Administration Guide.
admin-service
Determines whether the server instance is a regular instance, a domain administration server, or a combination. In the Platform Edition, there is only one server instance, and it is a combination.
Subelements
The following table describes subelements for the admin-service element.
Table 1-4 admin-service Subelements
Element
Required
Description
only one
Defines a domain administration server configuration.
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the admin-service element.
alert-service
Configures the alert service, which allows you to register for and receive system status alerts.
Subelements
The following table describes subelements for the alert-service element.
Table 1-6 alert-service Subelements
Element
Required
Description
zero or more
Configures a subscription to system status alerts.
zero or more
Specifies a property or a variable.
alert-subscription
Configures a subscription to system status alerts.
Subelements
The following table describes subelements for the alert-subscription element.
Attributes
The following table describes attributes for the alert-subscription element.
Table 1-8 alert-subscription Attributes
Attribute
Default
Description
name
none
Specifies the name of this alert subscription.
appclient-module
Specifies a deployed application client container (ACC) module.
Subelements
The following table describes subelements for the appclient-module element.
Table 1-9 appclient-module Subelements
Element
Required
Description
zero or one
Contains a text description of this element.
Attributes
The following table describes attributes for the appclient-module element.
application-ref
References an application or module deployed to the server instance.
Subelements
none
Attributes
The following table describes attributes for the application-ref element.
Table 1-11 application-ref Attributes
Attribute
Default
Description
enabled
true
(optional) Determines whether the application or module is enabled.
virtual-servers
all virtual servers
(optional) In a comma-separated list, references id attributes of the virtual-server elements to which the web-module or the web modules within this j2ee-application are deployed.
lb-enabled
false
(optional) If true, all load-balancers consider this application available to them.
disable-timeout-in-minutes
30
(optional) Specifies the time it takes this application to reach a quiescent state after having been disabled.
ref
none
References the name attribute of a lifecycle-module, j2ee-application, ejb-module, web-module, connector-module, or appclient-module element.
applications
Contains deployed J2EE applications, J2EE modules, and Lifecycle modules.
Subelements
The following table describes subelements for the applications element.
audit-module
Specifies an optional plug-in module that implements audit capabilities.
Subelements
The following table describes subelements for the audit-module element.
Table 1-13 audit-module Subelements
Element
Required
Description
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the audit-module element.
Table 1-14 audit-module Attributes
Attribute
Default
Description
name
none
Specifies the name of this audit module.
classname
none
Specifies the Java class that implements this audit module.
auth-realm
Defines a realm for authentication.
Authentication realms require provider-specific properties, which vary depending on what a particular implementation needs.
For more information about how to define realms, see the Sun Java System Application Server Developer’s Guide.
Here is an example of the default file realm:
<auth-realm name="file"
classname="com.iplanet.ias.security.auth.realm.file.FileRealm">
<property name="file" value="domain_dir/config/keyfile"/>
<property name="jaas-context" value="fileRealm"/>
</auth-realm>Which properties an auth-realm element uses depends on the value of the auth-realm element’s name attribute. The file realm uses file and jaas-context properties. Other realms use different properties.
Subelements
The following table describes subelements for the auth-realm element.
Table 1-15 auth-realm Subelements
Element
Required
Description
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the auth-realm element.
Table 1-16 auth-realm Attributes
Attribute
Default
Description
name
none
Specifies the name of this realm.
classname
none
Specifies the Java class that implements this realm.
Properties
The standard realms provided with Sun Java System Application Server have required and optional properties. A custom realm might have different properties.
The following table describes properties for the auth-realm element.
Bbackend-principal
Specifies the user name and password required by the EIS.
Subelements
none
Attributes
The following table describes attributes for the backend-principal element.
Table 1-18 backend-principal Attributes
Attribute
Default
Description
user-name
none
Specifies the user name required by the EIS.
password
none
Specifies the password required by the EIS.
Cconfig
Defines a configuration, which is a collection of settings that controls how a server instance functions.
Subelements
The following table describes subelements for the config element.
Attributes
The following table describes attributes for the config element.
configs
Contains configurations. In the Platform Edition, there is only one configuration.
Subelements
The following table describes subelements for the configs element.
connector-connection-pool
Defines a connector connection pool.
Subelements
The following table describes subelements for the connector-connection-pool element.
Attributes
The following table describes attributes for the connector-connection-pool element.
Table 1-23 connector-connection-pool Attributes
Attribute
Default
Description
name
none
Specifies the name of the connection pool. A jdbc-resource element’s pool-name attribute refers to this name.
resource-adapter-name
none
Specifies the name of resource adapter. The name of the .rar file is used as the unique name for the resource adapter.
connection-definition-name
none
Specifies a unique name, identifying one connection-definition in a Resource Adapter. This is a ConnectionFactory type.
steady-pool-size
8
(optional) Specifies the initial and minimum number of connections maintained in the pool.
max-pool-size
32
(optional) Specifies the maximum number of connections that can be created to satisfy client requests.
max-wait-time-in-millis
60000
(optional) Specifies the amount of time, in milliseconds, that the caller is willing to wait for a connection. If 0, the caller is blocked indefinitely until a resource is available or an error occurs.
pool-resize-quantity
2
(optional) Specifies the number of connections to be:
This is enforced periodically at the idle-time-out-in-seconds interval. An idle connection is one that has not been used for a period of idle-time-out-in-seconds.
idle-timeout-in-seconds
300
(optional) Specifies the maximum time that a connection can remain idle in the pool. After this amount of time, the pool can close this connection.
fail-all-connections
false
(optional) If true, closes all connections in the pool if a single validation check fails.
transaction-support
none
(optional) Specifies the transaction support for this connection pool. Overrides the transaction support defined in the resource adapter in a downward compatible way: supports a transaction level lower than or equal to the resource adapter’s, but not higher. Allowed values are:
Properties
The following table describes the most commonly used JMS properties for the connector-connection-pool element. Properties of this element override the ManagedConnectionFactory JavaBean configuration settings.
When one or more of these properties are specified, they are passed as if they are setName(Value) methods to the Resource Adapter’s ManagedConnectionFactory class (specified in ra.xml).
For a complete list of the available properties (called administered object attributes in Sun Java System Message Queue), see the Sun Java System Message Queue Administration Guide.
Note
All JMS administered object resource properties that worked with version 7 of the Application Server are supported for backward compatibility.
connector-module
Specifies a deployed connector module.
Subelements
The following table describes subelements for the connector-module element.
Table 1-25 connector-module Subelements
Element
Required
Description
zero or one
Contains a text description of this element.
Attributes
The following table describes attributes for the connector-module element.
connector-resource
Defines a connector (resource adapter) resource.
Subelements
The following table describes subelements for the connector-resource element.
Table 1-27 connector-resource Subelements
Element
Required
Description
zero or one
Contains a text description of this element.
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the connector-resource element.
Table 1-28 connector-resource Attributes
Attribute
Default
Description
jndi-name
none
Specifies the JNDI name for the resource.
pool-name
none
Specifies the name of the associated connector connection pool, defined in a connector-connection-pool element.
object-type
user
(optional) Defines the type of the resource. Allowed values are:
enabled
true
(optional) Determines whether this resource is enabled at runtime.
connector-service
Configures the connector service.
Subelements
none
Attributes
The following table describes attributes for the connector-service element.
custom-resource
Defines a custom resource, which specifies a custom server-wide resource object factory. Such object factories implement the javax.naming.spi.ObjectFactory interface.
Subelements
The following table describes subelements for the custom-resource element.
Table 1-30 custom-resource Subelements
Element
Required
Description
zero or one
Contains a text description of this element.
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the custom-resource element.
Ddas-config
Defines a domain administration server configuration. The domain administration server runs the Administration Console.
Subelements
The following table describes subelements for the das-config element.
Table 1-32 das-config Subelements
Element
Required
Description
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the das-config element. For more information about deployment topics such as dynamic reloading and autodeployment, see the Sun Java System Application Server Developer’s Guide.
description
Contains a text description of the parent element.
Subelements
none - contains data
domain
Defines a domain. This is the root element; there can only be one domain element in a domain.xml file.
Subelements
The following table describes subelements for the domain element.
Attributes
The following table describes attributes for the domain element.
Table 1-35 domain Attributes
Attribute
Default
Description
application-root
domain_dir/applications
(optional) Specifies the absolute path where deployed applications reside for this domain.
log-root
domain_dir/logs
(optional) Specifies where the domain’s log files are kept. The directory in which the log is kept must be writable by whatever user account the server runs as. See the log-service description for details about logs.
locale
operating system default
(optional) Specifies the domain’s language.
Eejb-container
Configures the EJB container. Stateless session beans are maintained in pools. Stateful session beans have session affinity and are cached. Entity beans associated with a database primary key are also cached. Entity beans not yet associated with a primary key are maintained in pools. Pooled entity beans are used to run ejbCreate() and finder methods.
Subelements
The following table describes subelements for the ejb-container element.
Table 1-36 ejb-container Subelements
Element
Required
Description
zero or one
Configures the EJB timer service.
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the ejb-container element.
Table 1-37 ejb-container Attributes
Attribute
Default
Description
steady-pool-size
32
(optional) Specifies the initial and minimum number of beans maintained in the pool. Must be 0 or greater and less than max-pool-size.
Bean instances are removed from the pool and returned after use. The pool is replenished or cleaned up periodically to maintain this size.
Applies to stateless session beans and entity beans.
pool-resize-quantity
16
(optional) Specifies the number of beans to be:
Must be 0 or greater and less than max-pool-size. The pool is not resized below the steady-pool-size.
Applies to stateless session beans and entity beans.
max-pool-size
64
(optional) Specifies the maximum number of beans that can be created to satisfy client requests. A value of 0 indicates an unbounded pool.
Applies to stateless session beans and entity beans.
cache-resize-quantity
32
(optional) Specifies the number of beans to be:
Must be greater than 1 and less than max-cache-size.
Applies to stateful session beans and entity beans.
max-cache-size
512
(optional) Specifies the maximum number of beans in the cache. A value of 0 indicates an unbounded cache.
Applies to stateful session beans and entity beans.
pool-idle-timeout-in-seconds
600
(optional) Specifies the maximum time that a bean can remain idle in the pool. After this amount of time, the pool can remove this bean. A value of 0 specifies that idle beans can remain in the pool indefinitely.
Applies to stateless session beans and entity beans.
cache-idle-timeout-in-seconds
600
(optional) Specifies the maximum time that a bean can remain idle in the cache. After this amount of time, the container can passivate this bean. A value of 0 specifies that beans never become candidates for passivation.
Applies to stateful session beans and entity beans.
removal-timeout-in-seconds
5400
(optional) Specifies the amount of time that a bean can remain passivated before it is removed from the session store. A value of 0 specifies that the container does not remove inactive beans automatically.
If removal-timeout-in-seconds is less than or equal to cache-idle-timeout-in-seconds, beans are removed immediately without being passivated.
The session-store attribute of the server element determines the location of the session store.
Applies to stateful session beans and entity beans.
victim-selection-policy
nru
(optional) Specifies how entity and stateful session beans are selected for passivation. Allowed values are fifo, lru, and nru:
commit-option
B
(optional) Determines which commit option is used for entity beans. Legal values are B or C.
session-store
domain_dir/session-store
(optional) Specifies the directory where passivated beans and persisted HTTP sessions are stored in the file system.
ejb-module
Specifies a deployed EJB module.
Subelements
The following table describes subelements for the ejb-module element.
Table 1-38 ejb-module Subelements
Element
Required
Description
zero or one
Contains a text description of this element.
Attributes
The following table describes attributes for the ejb-module element.
ejb-timer-service
Configures the EJB timer service.
Subelements
The following table describes subelements for the ejb-timer-service element.
Table 1-40 ejb-timer-service Subelements
Element
Required
Description
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the ejb-timer-service element.
external-jndi-resource
Defines a resource that resides in an external JNDI repository. For example, a generic Java object could be stored in an LDAP server. An external JNDI factory must implement the javax.naming.spi.InitialContextFactory interface.
Subelements
The following table describes subelements for the external-jndi-resource element.
Table 1-42 external-jndi-resource Subelements
Element
Required
Description
zero or one
Contains a text description of this element.
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the external-jndi-resource element.
Ffilter-config
Configures the filter class that filters alerts from notification emitters. See also listener-config.
Subelements
The following table describes subelements for the filter-config element.
Table 1-44 filter-config Subelements
Element
Required
Description
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the filter-config element.
Table 1-45 filter-config Attributes
Attribute
Default
Description
filter-class-name
none
Specifies the class name of the filter.
Hhttp-listener
Defines an HTTP listen socket.
Subelements
The following table describes subelements for the http-listener element.
Table 1-46 http-listener Subelements
Element
Required
Description
zero or one
Defines SSL parameters.
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the http-listener element.
Table 1-47 http-listener Attributes
Attribute
Default
Description
id
none
The unique listener name. An http-listener name cannot begin with a number.
address
none
IP address of the listener. Can be in dotted-pair or IPv6 notation. Can be any (for INADDR_ANY) to listen on all IP addresses. Can be a hostname.
port
none
Port number on which the listener listens. Legal values are 1 - 65535. On UNIX, creating sockets that listen on ports 1 - 1024 requires superuser privileges. Configuring an SSL listener to listen on port 443 is standard.
acceptor-threads
1
(optional) Number of acceptor threads for the listener, typically the number of processors in the machine. Legal values are 1 - 1024.
security-enabled
false
(optional) Determines whether the listener runs SSL. To turn SSL2 or SSL3 on or off and set ciphers, use an ssl subelement.
default-virtual-server
none
References the id attribute of the default virtual-server for this particular listener.
server-name
none
Tells the server what to put in the host name section of any URLs it sends to the client. This affects URLs the server automatically generates; it doesn’t affect the URLs for directories and files stored in the server. If your server uses an alias, the server-name should be the alias name.
If a colon and port number are appended, that port is used in URLs the server sends to the client.
redirect-port
none
(optional) If the listener is supporting non-SSL requests and a request is received for which a matching <security-constraint> requires SSL transport, the request is automatically redirected to the port number specified here.
xpowered-by
true
(optional) If true, X-Powered-By headers are used according to the Servlet 2.4 and JSP 2.0 specifications.
enabled
true
(optional) Determines whether the listener is active.
http-service
Defines the HTTP service.
Subelements
The following table describes subelements for the http-service element.
Table 1-48 http-service Subelements
Element
Required
Description
one or more
Defines an HTTP listen socket.
one or more
Defines a virtual server.
zero or more
Specifies a property or a variable.
Properties
The following table describes properties for the http-service element, which configure SSL for all http-listener subelements.
Iiiop-listener
Defines an IIOP listen socket.
To enable SSL for this listener, include an ssl subelement.
Subelements
The following table describes subelements for the iiop-listener element.
Table 1-50 iiop-listener Subelements
Element
Required
Description
zero or one
Defines SSL parameters.
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the iiop-listener element.
iiop-service
Defines the IIOP service.
Subelements
The following table describes subelements for the iiop-service element.
Table 1-52 iiop-service Subelements
Element
Required
Description
only one
Configures the ORB.
zero or one
Defines SSL parameters for the ORB.
zero or more
Defines an IIOP listen socket.
Attributes
The following table describes attributes for the iiop-service element.
Jj2ee-application
Specifies a deployed J2EE application.
Subelements
The following table describes subelements for the j2ee-application element.
Table 1-54 j2ee-application Subelements
Element
Required
Description
zero or one
Contains a text description of this element.
Attributes
The following table describes attributes for the j2ee-application element.
jacc-provider
Specifies a Java Authorization Contract for Containers (JACC) provider for pluggable authorization.
Subelements
The following table describes subelements for the jacc-provider element.
Table 1-56 jacc-provider Subelements
Element
Required
Description
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the jacc-provider element.
java-config
Specifies Java Virtual Machine (JVM) configuration parameters.
Subelements
The following table describes subelements for the java-config element.
Attributes
The following table describes attributes for the java-config element.
Table 1-59 java-config Attributes
Attribute
Default
Description
java-home
none
The path to the directory where the JDK is installed.
debug-enabled
false
(optional) If true, the server starts up in debug mode ready for attachment with a JPDA-based debugger.
debug-options
-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n
(optional) Specifies JPDA (Java Platform Debugger Architecture) options. A list of debugging options is available here:
http://java.sun.com/products/jpda/doc/conninv. html#Invocation
For more information about debugging, see the Sun Java System Application Server Developer’s Guide.
rmic-options
-iiop -poa -alwaysgenerate -keepgenerated -g
(optional) Specifies options passed to the RMI compiler at application deployment time. The -keepgenerated option saves generated source for stubs and ties.
For details about the rmic command, see:
http://java.sun.com/j2se/1.4.2/docs/tooldocs /solaris/rmic.html
javac-options
-g
(optional) Specifies options passed to the Java compiler at application deployment time.
classpath-prefix
none
(optional) Specifies a prefix for the system classpath. Only prefix the system classpath to override system classes, such as the XML parser classes. Use this attribute with caution.
classpath-suffix
none
(optional) Specifies a suffix for the system classpath.
server-classpath
none
(optional) Specifies the classpath for the environment from which the server was started. This classpath can be accessed using System.getProperty("java.class.path").
native-library-path-prefix
none
(optional) Specifies a prefix for the native library path.
The native library path is the automatically constructed concatenation of the Application Server installation relative path for its native shared libraries, the standard JRE native library path, the shell environment setting (LD_LIBRARY_PATH on UNIX), and any path specified in the profiler element. Since this is synthesized, it does not appear explicitly in the server configuration.
native-library-path-suffix
none
(optional) Specifies a suffix for the native library path.
bytecode-preprocessors
none
(optional) A comma separated list of class names, each of which must implement the com.sun.appserv.BytecodePreprocessor interface. Each of the specified preprocessor classes is called in the order specified.
env-classpath-ignored
true
(optional) If false, the CLASSPATH environment variable is read and appended to the Sun Java System Application Server classpath. The CLASSPATH environment variable is added after the classpath-suffix, at the very end.
For a development environment, this value should be set to false. To prevent environment variable side effects in a production environment, set this value to true.
jdbc-connection-pool
Defines the properties that are required for creating a JDBC connection pool.
Subelements
The following table describes subelements for the jdbc-connection-pool element.
Table 1-60 jdbc-connection-pool Subelements
Element
Required
Description
zero or one
Contains a text description of this element.
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the jdbc-connection-pool element.
Table 1-61 jdbc-connection-pool Attributes
Attribute
Default
Description
name
none
Specifies the name of the connection pool. A jdbc-resource element’s pool-name attribute refers to this name.
datasource-classname
none
Specifies the class name of the associated vendor-supplied data source. This class must implement java.sql.DataSource, or java.sql.XADataSource, or both.
res-type
javax.sql.DataSource
(optional) Specifies the interface the data source class implements. The value of this attribute can be javax.sql.DataSource or javax.sql.XADataSource. If the value is not one of these interfaces, the default is used. An error occurs if this attribute has a legal value and the indicated interface is not implemented by the data source class.
steady-pool-size
8
(optional) Specifies the initial and minimum number of connections maintained in the pool.
max-pool-size
32
(optional) Specifies the maximum number of connections that can be created to satisfy client requests.
max-wait-time-in-millis
60000
(optional) Specifies the amount of time, in milliseconds, that the caller is willing to wait for a connection. If 0, the caller is blocked indefinitely until a resource is available or an error occurs.
pool-resize-quantity
2
(optional) Specifies the number of connections to be:
This is enforced periodically at the idle-time-out-in-seconds interval. An idle connection is one that has not been used for a period of idle-time-out-in-seconds.
idle-timeout-in-seconds
300
(optional) Specifies the maximum time that a connection can remain idle in the pool. After this amount of time, the pool can close this connection.
transaction-isolation-level
default JDBC driver isolation level
(optional) Specifies the transaction isolation level on the pooled database connections. Allowed values are read-uncommitted, read-committed, repeatable-read, or serializable.
Applications that change the isolation level on a pooled connection programmatically risk polluting the pool, which can lead to errors. See is-isolation-level-guaranteed for more details.
is-isolation-level-guaranteed
true
(optional) Applicable only when transaction-isolation-level is explicitly set. If true, every connection obtained from the pool is guaranteed to have the desired isolation level. This might impact performance on some JDBC drivers. Only set this attribute to false if you are certain that the hosted applications do not return connections with altered isolation levels.
is-connection-validation-required
false
(optional) Specifies whether connections have to be validated before being given to the application. If a resource’s validation fails, it is destroyed, and a new resource is created and returned.
connection-validation-method
auto-commit
(optional) Legal values are as follows:
validation-table-name
none
(optional) Specifies the table name to be used to perform a query to validate a connection. This parameter is mandatory if and only if connection-validation-type is set to table.
fail-all-connections
false
(optional) If true, closes all connections in the pool if a single validation check fails. This parameter is mandatory if and only if is-connection-validation-required is set to true.
Properties
Most JDBC 2.0 drivers allow use of standard property lists to specify the user, password, and other resource configuration information. Although properties are optional with respect to Sun Java System Application Server, some properties might be necessary for most databases. For details, see Section 5.3 of JDBC 2.0 Standard Extension API.
When properties are specified, they are passed to the vendor’s data source class (specified by the datasource-classname attribute) as is using setName(value) methods.
The user and password properties are used as the default principal if container managed authentication is specified and a default-resource-principal is not found in the application deployment descriptors.
The following table describes some common properties for the jdbc-connection-pool element.
jdbc-resource
Defines a JDBC (javax.sql.DataSource) resource.
Subelements
The following table describes subelements for the jdbc-resource element.
Table 1-63 jdbc-resource Subelements
Element
Required
Description
zero or one
Contains a text description of this element.
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the jdbc-resource element.
Table 1-64 jdbc-resource Attributes
Attribute
Default
Description
jndi-name
none
Specifies the JNDI name for the resource.
pool-name
none
Specifies the name of the associated jdbc-connection-pool or connector-connection-pool.
object-type
user
(optional) Defines the type of the resource. Allowed values are:
enabled
true
(optional) Determines whether this resource is enabled at runtime.
jms-host
Configures the host of the built-in Java Message Service (JMS) that is managed by the Sun Java System Application Server.
Subelements
The following table describes subelements for the jms-host element.
Table 1-65 jms-host Subelements
Element
Required
Description
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the jms-host element.
jms-service
Configures the built-in Java Message Service (JMS) that is managed by the Sun Java System Application Server.
Subelements
The following table describes subelements for the jms-service element.
Table 1-67 jms-service Subelements
Element
Required
Description
zero or more
Specifies a host.
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the jms-service element.
Table 1-68 jms-service Attributes
Attribute
Default
Description
init-timeout-in-seconds
60
(optional) Specifies the amount of time the server instance waits at startup for the corresponding JMS instance to respond. If there is no response, startup is aborted. If set to 0, the server instance waits indefinitely.
type
LOCAL
(optional) Specifies the type of JMS service:
start-args
none
(optional) Specifies the string of arguments supplied for startup of the corresponding JMS instance.
default-jms-host
none
Specifies the name of the default jms-host. If type is set to LOCAL, this jms-host is automatically started at application server start-up.
reconnect-interval-in-seconds
60
(optional) Specifies the interval between reconnect attempts.
reconnect-attempts
3
(optional) Specifies the number of reconnect attempts.
reconnect-enabled
true
(optional) If true, reconnection is enabled.
addresslist-behavior
random
(optional) Specifies whether the reconnection logic selects the broker from the imqAddressList in a random or sequential (priority) fashion.
addresslist-iterations
3
(optional) Specifies the number of times the reconnection logic iterates over the imqAddressList if addresslist-behavior is set to PRIORITY.
mq-scheme
mq
(optional) Specifies the scheme for establishing connection with the broker. For example, specify http for connecting to the broker over HTTP.
mq-service
jms
(optional) Specifies the type of broker service. If a broker supports SSL, the type of service can be ssljms.
Properties
The following table describes properties for the jms-service element.
jvm-options
Contains JVM command line options, for example:
<jvm-options>-Xdebug -Xmx128m</jvm-options>
For information about JVM options, see:
http://java.sun.com/docs/hotspot/VMOptions.html
Subelements
none - contains data
Llifecycle-module
Specifies a deployed lifecycle module. For more information about lifecycle modules, see the Sun Java System Application Server Developer’s Guide.
Subelements
The following table describes subelements for the lifecycle-module element.
Table 1-70 lifecycle-module Subelements
Element
Required
Description
zero or one
Contains a text description of this element.
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the lifecycle-module element.
Table 1-71 lifecycle-module Attributes
Attribute
Default
Description
name
none
The name of the lifecycle module.
class-name
none
The fully qualified name of the lifecycle module’s class file, which must implement the com.sun.appserv.server.LifecycleListener interface.
classpath
value of application-root attribute of server element
(optional) The classpath for the lifecycle module. Specifies where the module is located.
load-order
none
(optional) Determines the order in which lifecycle modules are loaded at startup. Modules with smaller integer values are loaded sooner. Values can range from 101 to the operating system’s MAXINT. Values from 1 to 100 are reserved.
is-failure-fatal
false
(optional) Determines whether the server is shut down if the lifecycle module fails.
enabled
true
(optional) Determines whether the lifecycle module is enabled.
listener-config
Configures the listener class that listens for alerts from notification emitters. For example:
<listener-config
listener-class-name="com.sun.enterprise.admin.notification.MailAlert"
subcribe-listener-with="LogMBean,ServerStatusMonitor" >
<property name="recipients" value="Huey@sun.com,Dewey@sun.com,Louie@sun.com" />
<property name="fromAddress" value="DonaldDuck@sun.com" />
<property name="subject" value="Help!" />
<property name="includeDiagnostics" value="false" />
<property name="mailSMTPHost" value="ducks.sun.com" />
</listener-config>Subelements
The following table describes subelements for the listener-config element.
Table 1-72 listener-config Subelements
Element
Required
Description
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the listener-config element.
log-service
Configures the system logging service, which includes the following log files:
- The server log file stores messages from the default virtual server. Messages from other configured virtual servers also go here, unless the log-file attribute is explicitly specified in the virtual-server element. The default name is server.log.
- A virtual server log file stores messages from a virtual-server element that has an explicitly specified log-file attribute.
- The access log file stores HTTP access messages from the default virtual server. The default name is access.log.
- The transaction log files store transaction messages from the default virtual server. The default name of the directory for these files is tx.
Subelements
The following table describes subelements for the log-service element.
Table 1-74 log-service Subelements
Element
Required
Description
zero or one
Specifies log levels.
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the log-service element.
Table 1-75 log-service Attributes
Attribute
Default
Description
file
server.log
in the directory specified by the log-root attribute of the domain element
(optional) Overrides the name or location of the server log. The file and directory in which the server log is kept must be writable by the user account under which the server runs.
An absolute path overrides the log-root attribute of the domain element.
A relative path is relative to the log-root attribute of the domain element. If no log-root value is specified, it is relative to domain_dir/config.
use-system-logging
false
(optional) If true, uses the UNIX syslog service or Windows Event Logging to produce and manage logs.
log-handler
none
(optional) Specifies a custom log handler to be added to end of the chain of system handlers to log to a different destination.
log-filter
none
(optional) Specifies a log filter to do custom filtering of log records.
log-to-console
false
(optional) If true, specifies that logs are sent to stderr when the asadmin start-domain --verbose command is used.
log-rotation-limit-in-bytes
500000
(optional) Log files are rotated when the file size reaches the specified limit.
log-rotation-timelimit-in-minutes
0
(optional) Enables time-based log rotation. The valid range is 60 minutes (1 hour) to 14400 minutes (10*24*60 minutes or 10 days).
If the value is zero, the files are rotated based on the size specified in log-rotation-limit-in-bytes.
alarms
false
(optional) If true, turns on alarms for the logger. The SEVERE and WARNING messages can be routed through the JMX framework to raise SEVERE and WARNING alerts. See alert-service.
Mmail-resource
Defines a JavaMail (javax.mail.Session) resource.
Subelements
The following table describes subelements for the mail-resource element.
Table 1-76 mail-resource Subelements
Element
Required
Description
zero or one
Contains a text description of this element.
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the mail-resource element.
Properties
You can set properties for the mail-resource element and then get these properties in a JavaMail Session object later. Every property name must start with a mail- prefix. Sun Java System Application Server changes the dash (-) character to a period (.) in the name of the property, then saves the property to the MailConfiguration and JavaMail Session objects. If the name of the property doesn’t start with mail-, the property is ignored.
For example, to define the property mail.password in a JavaMail Session object, first edit domain.xml as follows:
...
<mail-resource jndi-name="mail/Session" ...>
<property name="mail-password" value="adminadmin"/>
</mail-resource>
...After getting the JavaMail Session object, get the mail.password property to retrieve the value adminadmin, as follows:
String password = session.getProperty("mail.password");
manager-properties
Specifies session manager properties.
Subelements
The following table describes subelements for the manager-properties element.
Table 1-78 manager-properties Subelements
Element
Required
Description
zero or more
Specifies a property, which has a name and a value.
Attributes
The following table describes attributes for the manager-properties element.
mdb-container
Configures the message-driven bean (MDB) container.
Subelements
The following table describes subelements for the mdb-container element.
Table 1-80 mdb-container Subelements
Element
Required
Description
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the mdb-container element.
Properties
The following table describes properties for the mdb-container element.
message-security-config
Specifies configurations for message security providers.
Subelements
The following table describes subelements for the message-security-config element.
Table 1-83 message-security-config Subelements
Element
Required
Description
one or more
Specifies a configuration for one message security provider.
Attributes
The following table describes attributes for the message-security-config element.
module-log-levels
Controls the level of messages logged by server subsystems to the server log. Allowed values of each subsystem attribute are, from highest to lowest: FINEST, FINER, FINE, CONFIG, INFO, WARNING, SEVERE, and OFF. Each value logs all messages for all lower values. The default value is INFO, which logs all INFO, SEVERE, and WARNING messages.
Subelements
The following table describes subelements for the module-log-levels element.
Table 1-85 module-log-levels Subelements
Element
Required
Description
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the module-log-levels element.
module-monitoring-levels
Controls the level of monitoring of server subsystems. Allowed values of each subsystem attribute are HIGH and OFF.
Subelements
The following table describes subelements for the module-monitoring-levels element.
Table 1-87 module-monitoring-levels Subelements
Element
Required
Description
zero or more
Specifies a property or a variable.
Attributes
monitoring-service
Configures the monitoring service.
Subelements
The following table describes subelements for the monitoring-service element.
Table 1-89 monitoring-service Subelements
Element
Required
Description
zero or one
Controls the level of monitoring of server subsystems.
zero or more
Specifies a property or a variable.
Oorb
Configures the ORB.
To enable SSL for outbound connections, include an ssl-client-config subelement in the parent iiop-service element.
Subelements
The following table describes subelements for the orb element.
Table 1-90 orb Subelements
Element
Required
Description
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the orb element.
Table 1-91 orb Attributes
Attribute
Default
Description
use-thread-pool-ids
none
Specifies a comma-separated list of thread-pool-id values defined in thread-pool elements used by the ORB.
message-fragment-size
1024
(optional) GIOPv1.2 messages larger than this number of bytes are fragmented.
max-connections
1024
(optional) The maximum number of incoming connections on all IIOP listeners. Legal values are integers.
Ppersistence-manager-factory-resource
Defines a persistence manager factory resource for container-managed persistence (CMP).
Subelements
The following table describes subelements for the persistence-manager-factory-resource element.
Table 1-92 persistence-manager-factory-resource Subelements
Element
Required
Description
zero or one
Contains a text description of this element.
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the persistence-manager-factory-resource element.
Table 1-93 persistence-manager-factory-resource Attributes
Attribute
Default
Description
jndi-name
none
Specifies the JNDI name for the resource.
factory-class
com.sun.jdo.spi.persistence.support.sqlstore.impl.PersistenceManagerFactoryImpl
(optional) Specifies the name of the factory class. This attribute supports third party CMP persistence manager factories. Use the name required by the third party CMP implementation. Do not specify this attribute for the built-in CMP implementation.
jdbc-resource-jndi-name
none
Specifies the jdbc-resource from which database connections are obtained. Must be the jndi-name of an existing jdbc-resource.
object-type
user
(optional) Defines the type of the resource. Allowed values are:
enabled
true
(optional) Determines whether this resource is enabled at runtime.
principal
Contains the principal of the servlet or EJB client.
Subelements
none - contains data
profiler
Configures a profiler for use with Sun Java System Application Server. For more information about profilers, see the Sun Java System Application Server Developer’s Guide.
Subelements
The following table describes subelements for the profiler element.
Table 1-94 profiler Subelements
Element
Required
Description
zero or more
Contains profiler-specific JVM command line options.
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the profiler element.
property
Specifies a property. A property adds configuration information to its parent element that is one or both of the following:
For example, an auth-realm element can include property subelements:
<auth-realm name="file"
classname="com.sun.enterprise.security.auth.realm.file.FileRealm">
<property name="file" value="domain_dir/config/keyfile"/>
<property name="jaas-context" value="fileRealm"/>
</auth-realm>Which properties an auth-realm element uses depends on the value of the auth-realm element’s name attribute. The file realm uses file and jaas-context properties. Other realms use different properties.
Subelements
The following table describes subelements for the property element.
Table 1-96 property Subelements
Element
Required
Description
zero or one
Contains a text description of this element.
Attributes
The following table describes attributes for the property element.
Table 1-97 property Attributes
Attribute
Default
Description
name
none
Specifies the name of the property or variable.
value
none
Specifies the value of the property or variable.
provider-config
Specifies a configuration for one message security provider.
Although the request-policy and response-policy subelements are optional, the provider-config element does nothing if they are not specified.
Use property subelements to configure provider-specific properties. Property values are passed to the provider when its initialize method is called.
Subelements
The following table describes subelements for the provider-config element.
Attributes
The following table describes attributes for the provider-config element.
Rrequest-policy
Defines the authentication policy requirements of the authentication provider’s request processing.
Subelements
none
Attributes
The following table describes attributes for the request-policy element.
resource-adapter-config
Defines a resource adapter configuration.
Subelements
The following table describes subelements for the resource-adapter-config element.
Table 1-101 resource-adapter-config Subelements
Element
Required
Description
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the resource-adapter-config element.
Table 1-102 resource-adapter-config Attributes
Attribute
Default
Description
name
none
(optional) Specifies a unique name for the resource adapter.
thread-pool-ids
none
(optional) Specifies the id of a thread-pool element.
object-type
user
(optional) Defines the type of the resource. Allowed values are:
resource-adapter-name
none
Specifies the fully qualified file name of the resource adapter.
Properties
Any properties defined here override the default values present in ra.xml.
resource-ref
References a resource deployed to the server instance.
Subelements
none
Attributes
The following table describes attributes for the resource-ref element.
Table 1-103 resource-ref Attributes
Attribute
Default
Description
enabled
true
(optional) Determines whether the resource is enabled.
ref
none
References the name attribute of a custom-resource, external-jndi-resource, jdbc-resource, mail-resource, persistence-manager-factory-resource, admin-object-resource, connector-resource, resource-adapter-config, jdbc-connection-pool, or connector-connection-pool element.
resources
Contains configured resources, such as database connections, JavaMail™ sessions, and so on.
Subelements
The following table describes subelements for the resources element.
response-policy
Defines the authentication policy requirements of the authentication provider’s response processing.
Subelements
none
Attributes
The following table describes attributes for the response-policy element.
Ssecurity-map
Maps the principal received during servlet or EJB authentication to the credentials accepted by the EIS.
Subelements
The following table describes subelements for the security-map element.
Attributes
The following table describes attributes for the security-map element.
Table 1-107 security-map Attributes
Attribute
Default
Description
name
none
Specifies a name for the security mapping.
security-service
Defines parameters and configuration information needed by the J2EE security service.
Subelements
The following table describes subelements for the security-service element.
Attributes
The following table describes attributes for the security-service element.
Table 1-109 security-service Attributes
Attribute
Default
Description
default-realm
file
(optional) Specifies the active authentication realm (an auth-realm name attribute) for this server instance.
default-principal
none
(optional) Used as the identity of the default security context when necessary and when no principal is provided. This attribute need not be set for normal server operation.
default-principal-password
none
(optional) The password of the default principal. This attribute need not be set for normal server operation.
anonymous-role
ANYONE
(optional) Used as the name for default, or anonymous, role. The anonymous role is always assigned to all principals. This role value can be used in J2EE deployment descriptors to grant access to anyone.
audit-enabled
false
(optional) If true, additional access logging is performed to provide audit information.
Audit information consists of:
jacc
default
(optional) Specifies the name of the jacc-provider element to use for setting up the JACC infrastructure. Do not change the default value unless you are adding a custom JACC provider.
audit-modules
default
(optional) Specifies a comma-separated list of audit provider modules used by the audit subsystem. The default value refers to the internal log-based audit module.
server
Defines a server instance.
Note
Server instances are not the same thing as virtual servers. Each server instance is a completely separate server that contains one or more virtual servers.
Subelements
The following table describes subelements for the server element.
Attributes
The following table describes attributes for the server element.
Table 1-111 server Attributes
Attribute
Default
Description
name
none
Specifies the name of the server instance.
config-ref
default config element’s name, server-config
(optional) References the name of the config used by the server instance. For the Platform Edition, the default is the only value allowed.
servers
Contains server instances. In the Platform Edition, there is only one server instance.
Subelements
The following table describes subelements for the servers element.
session-config
Specifies session configuration information for the entire web container. Individual web applications can override these settings using the corresponding elements in their sun-web.xml files.
Subelements
The following table describes subelements for the session-config element.
Table 1-113 session-config Subelements
Element
Required
Description
zero or one
Specifies session manager configuration information.
zero or one
Specifies session properties.
session-manager
Specifies session manager information.
Subelements
The following table describes subelements for the session-manager element.
Table 1-114 session-manager Subelements
Element
Required
Description
zero or one
Specifies session manager properties.
zero or one
Specifies session persistence (storage) properties.
session-properties
Specifies session properties.
Subelements
The following table describes subelements for the session-properties element.
Table 1-115 session-properties Subelements
Element
Required
Description
zero or more
Specifies a property, which has a name and a value.
Attributes
Properties
The following table describes properties for the session-properties element.
ssl
Defines SSL (Secure Socket Layer) parameters.
An ssl element is required inside an http-listener or iiop-listener element that has its security-enabled attribute set to on.
In Platform Edition, SSL is globally disabled.
Subelements
none
Attributes
The following table describes attributes for the ssl element.
Table 1-118 ssl Attributes
Attribute
Default
Description
cert-nickname
none
The nickname of the server certificate in the certificate database or the PKCS#11 token. In the certificate, the name format is tokenname:nickname. Including the tokenname: part of the name in this attribute is optional.
ssl2-enabled
false
(optional) Determines whether SSL2 is enabled.
If both SSL2 and SSL3 are enabled for a virtual-server, the server tries SSL3 encryption first. If that fails, the server tries SSL2 encryption.
ssl2-ciphers
none
(optional) A comma-separated list of the SSL2 ciphers used, with the prefix + to enable or - to disable, for example +rc4. Allowed values are rc4, rc4export, rc2, rc2export, idea, des, desede3.
ssl3-enabled
true
(optional) Determines whether SSL3 is enabled. The default is true.
If both SSL2 and SSL3 are enabled for a virtual-server, the server tries SSL3 encryption first. If that fails, the server tries SSL2 encryption.
ssl3-tls-ciphers
none
(optional) A comma-separated list of the SSL3 ciphers used, with the prefix + to enable or - to disable, for example +rsa_des_sha. Allowed SSL3 values are rsa_rc4_128_md5, rsa_3des_sha, rsa_des_sha, rsa_rc4_40_md5, rsa_rc2_40_md5, rsa_null_md5. Allowed TLS values are rsa_des_56_sha, rsa_rc4_56_sha.
tls-enabled
true
(optional) Determines whether TLS is enabled.
client-auth-enabled
false
(optional) Determines whether SSL3 client authentication is performed on every request, independent of ACL-based access control.
ssl-client-config
Defines SSL parameters for the ORB when it makes outbound SSL connections and behaves as a client.
Subelements
The following table describes subelements for the ssl-client-config element.
Table 1-119 ssl-client-config Subelements
Element
Required
Description
only one
Defines SSL parameters.
store-properties
Specifies session persistence (storage) properties.
Subelements
The following table describes subelements for the store-properties element.
Table 1-120 store-properties Subelements
Element
Required
Description
zero or more
Specifies a property, which has a name and a value.
Attributes
system-property
Specifies a system property. A system property defines a common value for a setting at one of these levels, from highest to lowest: domain, server, or config. A value set at a higher level can be overridden at a lower level. Some system properties are predefined; see Table 1-124. You can also create system properties using this element.
The following example shows the use of a predefined system property:
<log-service file="${com.sun.aas.instanceRoot}/logs/server.log">
<module-log-levels admin=INFO .../>
</log-service>The following example shows the creation and use of a system property:
<config name="config1">
...
<http-service>
...
<http-listener id="ls1" host="0.0.0.0" port="${ls1-port}"/>
...
</http-service>
...
<system-property name="ls1-port" value="8080"/>
</config>Subelements
The following table describes subelements for the system-property element.
Table 1-122 system-property Subelements
Element
Required
Description
zero or one
Contains a text description of this element.
Attributes
The following table describes attributes for the system-property element.
Table 1-123 system-property Attributes
Attribute
Default
Description
name
none
Specifies the name of the system property.
value
none
Specifies the value of the system property.
Properties
The following table lists predefined system properties.
Table 1-124 Predefined System Properties
Property
Default
Description
com.sun.aas.installRoot
depends on operating system
Specifies the directory where the Sun Java System Application Server is installed.
com.sun.aas.instanceRoot
depends on operating system
Specifies the top level directory for a server instance.
com.sun.aas.hostName
none
Specifies the name of the host (machine).
com.sun.aas.javaRoot
depends on operating system
Specifies the J2SE installation directory.
com.sun.aas.imqLib
depends on operating system
Specifies the library directory for Sun Java System Message Queue.
com.sun.aas.configName
server-config
Specifies the name of the config used by a server instance.
com.sun.aas.instanceName
server1
Specifies the name of the server instance. This property is not used in the default configuration, but can be used to customize configuration.
com.sun.aas.domainName
domain1
Specifies the name of the domain. This property is not used in the default configuration, but can be used to customize configuration.
Tthread-pool
Defines a thread pool.
Subelements
none
Attributes
thread-pools
Contains thread pools.
Subelements
The following table describes subelements for the thread-pools element.
Table 1-126 thread-pools Subelements
Element
Required
Description
one or more
Defines a thread pool.
transaction-service
Configures the Java Transaction Service (JTS).
Subelements
The following table describes subelements for the transaction-service element.
Table 1-127 transaction-service Subelements
Element
Required
Description
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the transaction-service element.
Table 1-128 transaction-service Attributes
Attribute
Default
Description
automatic-recovery
false
(optional) If true, the server instance attempts transaction recovery during startup.
timeout-in-seconds
0
(optional) Specifies the amount of time after which the transaction is aborted. If set to 0, the transaction never times out.
tx-log-dir
directory specified by the log-root attribute of the server element
(optional) Overrides the location of the transaction log directory. The directory in which the transaction logs are kept must be writable by the user account under which the server runs. See the log-service description for details about logs.
heuristic-decision
rollback
(optional) During recovery, if the outcome of a transaction cannot be determined from the logs, this property determines the outcome. Allowed values are rollback and commit.
retry-timeout-in-seconds
600
(optional) Determines the retry time in the following scenarios:
A negative value specifies infinite retries. A value of 0 (zero) specifies no retries. A positive value indicates the time after which a retry is attempted.
keypoint-interval
2048
(optional) Specifies the number of transactions between keypoint operations in the log. Keypoint operations reduce the size of the transaction log file by compressing it. A larger value for this attribute (for example, 4096) results in a larger transaction log file, but fewer keypoint operations and potentially better performance. A smaller value (for example, 100) results in smaller log files, but slightly reduced performance due to the greater frequency of keypoint operations.
Properties
The following table describes properties for the transaction-service element.
Uuser-group
Contains the group to which the principal belongs.
Subelements
none - contains data
Vvirtual-server
Defines a virtual server. A virtual server, also called a virtual host, is a virtual web server that serves content targeted for a specific URL. Multiple virtual servers can serve content using the same or different host names, port numbers, or IP addresses. The HTTP service can direct incoming web requests to different virtual servers based on the URL.
When the Sun Java System Application Server is first installed, a default virtual server is created. (You can also assign a default virtual server to each new http-listener you create.)
Note
Virtual servers are not the same thing as server instances. Each server instance is a completely separate server that contains one or more virtual servers.
Before the Sun Java System Application Server can process a request, it must accept the request via a listener, then direct the request to the correct virtual server. The virtual server is determined as follows:
- If the listener is configured to only a default virtual server, that virtual server is selected.
- If the listener has more than one virtual server configured to it, the request Host header is matched to the hosts attribute of a virtual server. If no Host header is present or no hosts attribute matches, the default virtual server for the listener is selected.
If a virtual server is configured to an SSL listener, its hosts attribute is checked against the subject pattern of the certificate at server startup, and a warning is generated and written to the server log if they don’t match.
Subelements
The following table describes subelements for the virtual-server element.
Table 1-130 virtual-server Subelements
Element
Required
Description
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the virtual-server element.
Table 1-131 virtual-server Attributes
Attribute
Default
Description
id
none
Virtual server ID. This is a unique ID that allows lookup of a specific virtual server. A virtual server ID cannot begin with a number.
http-listeners
none
(optional) In a comma-separated list, references id attributes of http-listener elements that specify the connection(s) the virtual server uses. Required only for a virtual-server that is not referenced by the default-virtual-server attribute of an http-listener.
default-web-module
system default web module
(optional) References the name attribute of the default web-module for this virtual server, which responds to requests that cannot be resolved to other web modules deployed to this virtual server (see the application-ref element).
hosts
none
A comma-separated list of values, each of which selects the current virtual server when included in the Host request header. Two or more virtual-server elements that reference or are referenced by the same http-listener cannot have any hosts values in common.
state
on
(optional) Determines whether a virtual-server is active (on) or inactive (off, disabled). The default is on (active). When inactive, a virtual-server does not service requests.
If a virtual-server is disabled, only the global server administrator can turn it on.
log-file
server.log in the directory specified by the log-root attribute of the domain element
(optional) Writes this virtual server’s log messages to a log file separate from the server log. The file and directory in which the virtual server log is kept must be writable by the user account under which the server runs. See the log-service description for details about logs.
Properties
The following table describes properties for the virtual-server element.
Wweb-container
Configures the web container.
Subelements
The following table describes subelements for the web-container element.
Table 1-133 web-container Subelements
Element
Required
Description
zero or one
Specifies session configuration information for the web container.
zero or more
Specifies a property or a variable.
web-module
Specifies a deployed web module.
Subelements
The following table describes subelements for the web-module element.
Table 1-134 web-module Subelements
Element
Required
Description
zero or one
Contains a text description of this element.
Attributes
The following table describes attributes for the web-module element.