Oracle GlassFish Server 3.0.1 Domain File Format Reference

Chapter 1 The domain.xml File

This chapter describes the domain.xml configuration file for Oracle GlassFishTM Server 3.0.1 in these sections:


Note –

Some features are not available if you have installed the Web Profile. Elements related to these features are ignored.



Note –

Oracle GlassFish Server 3.0.1 does not support clustering or load balancing features. Elements related to these features are ignored.



Note –

Subelements must be defined in the order in which they are listed under each Subelements heading in this chapter unless otherwise noted.


About the domain.xml File

The domain.xml file contains most of the Oracle GlassFish Server configuration. The domain.xml file is located in the domain configuration directory, which is typically domain-dir/config.

There is no DTD file or schema that determines the format of the domain.xml file. The server's configuration is dictated by the Java interfaces with appropriate annotations and domain.xml serves as a seed for that configuration. At any point in time, the overall structure of an XML element present in domain.xml is clearer when one sees the Java interface in the package com.sun.enterprise.config.serverbeans. Thus these Java interfaces take the place of the DTD file in previous releases.

This file is further described in the following sections:


Note –

Settings in the GlassFish Server deployment descriptors override corresponding settings in the domain.xml file unless otherwise stated. For more information about the GlassFish Server deployment descriptors, see the Oracle GlassFish Server 3.0.1 Application Deployment Guide.


Verification

To verify that the structure and content of the domain.xml file are correct, use the asadmin verify-domain-xml command. To use this command on the default domain in the default location, simply type asadmin verify-domain-xml at the command line. Any errors found are printed on the screen. For more information about this command, see verify-domain-xml(1).

Extensibility

If you create new add-on components for the GlassFish Server, you can add any configuration these components require to the domain.xml file. For more information on extending the GlassFish Server by creating add-on components, see the Oracle GlassFish Server 3.0.1 Add-On Component Development Guide.

Backup

A backup of the domain.xml file is created whenever the configuration is changed using the Administration Console or the asadmin command. The backup file is located in the domain configuration directory, typically domain-dir/config, and is named domain.xml.bak. If you make a mistake editing the domain.xml file, you can overwrite it using the backup file.

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:


Note –

Removal of initial values in domain.xml is not recommended because attributes may be left without values or values may revert to internal defaults. Explicitly changing values is recommended.

Only values that differ from internal defaults are included in the domain.xml file.


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 GlassFish 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 that is deployed to its parent server element. The application-ref element’s ref attribute has the same value as the name attribute of an application element.

The referencing application-ref element might look like this:

<application-ref ref="MyServlet"/>

The referenced application element might look like this:

<application 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 cardinality. For those details, see the element descriptions.

domain P
.    system-applications
.    .    application P
.    .   .    engine P
.    .   .    module
.    .   .    .    engine P
.    .   .    .   .    web-module-config
.    .   .    .   .    .    env-entry
.    .   .    .   .    .    .    env-entry-name
.    .   .    .   .    .    .    env-entry-type
.    .   .    .   .    .    .    env-entry-value
.    .   .    .   .    .    context-param
.    .   .    .   .    .    .    param-name
.    .   .    .   .    .    .    param-value
.    applications
.    .    application P
.    .   .    engine P
.    .   .    module
.    .   .    .    engine P
.    .   .    .   .    web-module-config
.    .   .    .   .    .    env-entry
.    .   .    .   .    .    .    env-entry-name
.    .   .    .   .    .    .    env-entry-type
.    .   .    .   .    .    .    env-entry-value
.    .   .    .   .    .    context-param
.    .   .    .   .    .    .    param-name
.    .   .    .   .    .    .    param-value
.    .    lifecycle-module P
.    .    j2ee-application P
.    .    web-module P
.    .   .    web-service-endpoint
.    .   .    .    registry-location 
.    .   .    .    transformation-rule 
.    .    ejb-module P
.    .   .    web-service-endpoint 
.    .   .    .    registry-location 
.    .   .    .    transformation-rule 
.    .    connector-module P
.    .    appclient-module P
.    .    extension-module P
.    resources
.    .    custom-resource P
.    .    external-jndi-resource P
.    .    jdbc-resource P
.    .    mail-resource P
.    .    admin-object-resource P
.    .    connector-resource P
.    .    resource-adapter-config P
.    .    jdbc-connection-pool P
.    .    connector-connection-pool P
.    .   .    security-map
.    .   .    .    principal
.    .   .    .    user-group
.    .   .    .    backend-principal
.    .    work-security-map
.    .   .    principal-map
.    .   .    group-map
.    configs
.    .    config P
.    .   .    http-service P
.    .   .    .    access-log
.    .   .    .    virtual-server P
.    .   .    .   .    http-access-log
.    .   .    network-config
.    .   .    .    transports
.    .   .    .   .    selection-key-handler
.    .   .    .   .    transport
.    .   .    .    protocols
.    .   .    .   .    protocol
.    .   .    .   .    .    http
.    .   .    .   .    .    .    file-cache
.    .   .    .   .    .    port-unification
.    .   .    .   .    .    .    protocol-finder
.    .   .    .   .    .    protocol-chain-instance-handler
.    .   .    .   .    .    .    protocol-chain
.    .   .    .   .    .    protocol-filter
.    .   .    .   .    .    ssl
.    .   .    .    network-listeners
.    .   .    .   .    network-listener
.    .   .    iiop-service
.    .   .    .    orb P
.    .   .    .    ssl-client-config 
.    .   .    .   .    ssl  
.    .   .    .    iiop-listener P
.    .   .    .   .    ssl  
.    .   .    admin-service P
.    .   .    .    jmx-connector P
.    .   .    .   .    ssl  
.    .   .    .    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 P
.    .   .    system-property
.    .   .    jruby-container
.    .   .    .    jruby-runtime-pool
.    servers
.    .    server P
.    .   .    application-ref
.    .   .    resource-ref
.    .   .    system-property
.    system-property

Alphabetical List of Elements

A

access-log

Defines access log settings for each http-access-log subelement of each virtual-server.

Superelements

http-service

Subelements

none

Attributes

The following table describes attributes for the access-log element.

Table 1–1 access-log Attributes

Attribute 

Default 

Description 

format

%client.name% %auth-user-name% %datetime% %request% %status% %response.length%

(optional) Specifies the format of the access log. For a complete list of token values you can use in the format, see the online help for the Access Log tab of the HTTP Service page in the Administration Console. 

rotation-policy

time

(optional) Specifies the condition that triggers log rotation. The only legal value is time, which rotates log files at the rotation-interval-in-minutes interval.

rotation-interval-in-minutes

1440

(optional) Specifies the time interval between log rotations if rotation-policy is set to time.

rotation-suffix

yyyy-MM-dd

(optional) Specifies the format of the timestamp appended to the access log name when log rotation occurs.  

For supported formats, see http://java.sun.com/javase/6/docs/api/java/text/SimpleDateFormat.html.

The following value is supported for backward compatibility. It results in the same format as the default. 

%YYYY;%MM;%DD;-%hh;h%mm;m%ss;s

rotation-enabled

true

(optional) If true, enables log rotation.

admin-object-resource

Defines an administered object for a resource adapter.

Superelements

resources

Subelements

The following table describes subelements for the admin-object-resource element.

Table 1–2 admin-object-resource Subelements

Element 

Required 

Description 

description

zero or one 

Contains a text description of this element. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the admin-object-resource element.

Table 1–3 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 resource adapter, as specified in the name attribute of a connector application element.

object-type

user

(optional) Defines the type of the resource. Allowed values are: 

  • system-all - A system resource for all server instances and the domain application server.

  • system-admin - A system resource only for the domain application server.

  • system-instance - A system resource for all server instances only.

  • user - A user resource.

enabled

true

(optional) Determines whether this resource is enabled at runtime. 

Properties

Properties of the admin-object-resource element are the names of setter methods of the class referenced by the adminobject-class element of the ra.xml file. Some of the property names can be specified in the adminobjectType element.

admin-service

Contains configuration for JMX connectors, the domain admin server (DAS), and related properties.

Superelements

config

Subelements

The following table describes subelements for the admin-service element.

Table 1–4 admin-service Subelements

Element 

Required 

Description 

jmx-connector

zero or more 

Configures a JSR 160/255 compliant remote JMX connector, which responds to JConsole port 8686. 

das-config

only one 

Defines a domain administration server configuration. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the admin-service element.

Table 1–5 admin-service Attributes

Attribute 

Default 

Description 

type

das-and-server

Specifies whether the server instance is a regular instance (server), a domain administration server (das), or a combination (das-and-server). modifying this value is not recommended.

system-jmx-connector-name

none 

Specifies the name of the internal jmx-connector.

appclient-module

This element is deprecated. Use an application element instead.

Specifies a deployed application client container (ACC) module.

Superelements

applications

Subelements

The following table describes subelements for the appclient-module element.

Table 1–6 appclient-module Subelements

Element 

Required 

Description 

description

zero or one 

Contains a text description of this element. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the appclient-module element.

Table 1–7 appclient-module Attributes

Attribute 

Default 

Description 

name

none 

The name of the ACC module. 

location

none 

A fully qualified or relative path to the directory to which the contents of the client .jar file have been extracted. If relative, it is relative to the following directory:

domain-dir/applications/

directory-deployed

false

(optional) Specifies whether the application has been deployed as a directory. 

java-web-start-enabled

true

(optional) Specifies whether Java Web Start access is permitted for this application client. 

application

Specifies a system application, a Java EE module or application, or an application created using another supported technology such as JRuby.

The application element replaces the web-module, j2ee-application, appclient-module, connector-module, lifecycle-module, extension-module, and ejb-module elements of previous releases, which are converted to application elements during the upgrade process.

Superelements

system-applications, applications

Subelements

The following table describes subelements for the application element.

Table 1–8 application Subelements

Element 

Required 

Description 

module

one or more 

Specifies a stand-alone module or a component of a Java EE application. 

engine

one or more 

Specifies an engine. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the application element.

Table 1–9 application Attributes

Attribute 

Default 

Description 

name

none 

The name of the application. 

description

none 

(optional) Specifies a text description of this element. 

location

none 

(optional) The location of the application in the GlassFish Server file system. If a relative path is specified, it is relative to the domain-dir/applications/ directory.


Note –

Deployment directories may change between GlassFish Server releases.


libraries

none 

(optional) Specifies a comma-separated list of absolute or relative paths to libraries specific to this module or application. A relative path is relative to domain-dir/lib/applibs. If the path is absolute, the path must be accessible to the domain administration server (DAS), which means it must be under domain-dir. The libraries are made available to the application in the order in which they are specified.

object-type

user

(optional) Defines the type of the resource. For an application, the only allowed value is user.

enabled

true

(optional) Determines whether the application is enabled. 

context-root

none 

(optional) The context root at which the application is deployed. The context root can be the empty string or just /. The context root can start with the / character, but doesn’t have to.

directory-deployed

false

(optional) Specifies whether the application has been deployed as a directory. 

Properties

The following table describes properties for the application element. These properties are specified during deployment using one of the following:

The properties that are valid for a given application depend on the sniffer attribute values of the child or grandchild engine elements.

Table 1–10 application Properties

Property 

Default 

Description 

java-web-start-enabled

true

Specifies whether Java Web Start access is permitted for an application client module. 

jar-signing-alias

s1as

Specifies the alias for the security certificate with which the application client container JAR file is signed. 

Java Web Start won't execute code requiring elevated permissions unless it resides in a JAR file signed with a certificate that the user's system trusts. For your convenience, GlassFish Server signs the JAR file automatically using the self-signed certificate from the domain, s1as. Java Web Start then asks the user whether to trust the code and displays the GlassFish Server certificate information.

To sign this JAR file with a different certificate, add the certificate to the domain keystore, then use this property. To add a certificate to the domain keystore, see Administering JSSE Certificates in Oracle GlassFish Server 3.0.1 Administration Guide.

For example, you can use a certificate from a trusted authority, which avoids the Java Web Start prompt, or from your own company, which users know they can trust. 

class-name

none 

The fully qualified name of a lifecycle module class file. A lifecycle module class must implement the com.sun.appserv.server.LifecycleListener interface.

classpath

value of application-root attribute of domain element

The classpath for a lifecycle module. Specifies where the module is located. 

load-order

none 

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

Determines whether the server is shut down if a lifecycle module fails. 

keepSessions

false

If true, specifies that active sessions of the application being redeployed are preserved and then restored when redeployment is complete.

If any active session of the application fails to be preserved or restored, none of the sessions are available when the redeployment is complete. However, redeployment continues and a warning is logged. 

To preserve active sessions, the GlassFish Server serializes the sessions and saves them in memory. To restore the sessions, the class loader of the newly redeployed application deserializes any sessions that were previously saved. 

compatibility

none (no backward compatibility) 

Specifies the GlassFish Server release with which to be backward compatible in terms of JAR visibility requirements for applications. The only allowed value is v2, which refers to GlassFish version 2 or GlassFish Server version 9.1 or 9.1.1.

The Java EE 6 platform specification imposes stricter requirements than Java EE 5 did on which JAR files can be visible to various modules within an EAR file. In particular, application clients must not have access to EJB JAR files or other JAR files in the EAR file unless references use the standard Java SE mechanisms (extensions, for example) or the Java EE library-directory mechanism. Setting this property to v2 removes these Java EE 6 restrictions.

jruby.home

as-install/jruby

Specifies the directory where JRuby itself (not the GlassFish Server JRuby container) is installed. Overrides the jruby-home attribute of jruby-container.

jruby.runtime

1

Specifies the initial number of JRuby runtimes to start. Must be at greater than zero, at least jruby.runtime.min, and jruby.runtime.max or less. Overrides the jruby-runtime attribute of jruby-runtime-pool.

jruby.runtime.min

1

Specifies the minimum number of JRuby runtimes in the pool. Must be greater than zero, jruby.runtime or less, and jruby.runtime.max or less. Overrides the jruby-runtime-min attribute of jruby-runtime-pool.

jruby.runtime.max

1

Specifies the maximum number of JRuby runtimes in the pool. Must be greater than zero, at least jruby.runtime.min, and at least jruby.runtime. Overrides the jruby-runtime-max attribute of jruby-runtime-pool.

jruby.rackEnv

development

Specifies the environment in which a JRuby application such as Rails or Merb runs. Allowed values are development, production, or test.

jruby.applicationType

Computed through auto-detection 

Specifies the name of a supported framework or the path to a script that initializes the user's framework. Allowed values corresponding to supported frameworks are rails, merb, or sinatra.

Setting this property bypasses the normal, and potentially lengthy, auto-detection process and forces deployment on the specified framework. If the deployed application is not written for the specified framework, errors result. 

jruby.MTSafe

Computed through auto-detection 

If true, specifies that a framework being started using jruby.applicationType is thread-safe and therefore does not need a pool created for it.

This property affects applications started using an auto-detected user-provided startup script. If jruby.applicationType is set and jruby.MTsafe is not set or is set to false, the application starts with a pool of application instances, and each instance of the application is accessed by one thread at a time. This property only affects frameworks being launched where the thread safety cannot be automatically determined. Setting jruby.MTsafe to true does not cause an auto-detected Rails 2.1.x application to be launched in thread-safe mode, nor can it be used to force a thread-safe framework to start in pooled mode.

application-ref

References an application or module deployed to the server.

Superelements

server

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 on the server on which it is deployed. 

virtual-servers

all virtual servers 

(optional) In a comma-separated list, references id attributes of the virtual-server elements to which the web application is deployed.

If you deploy a web application and don't specify any assigned virtual servers, the web application is assigned to all currently defined virtual servers. If you then create additional virtual servers and want to assign existing web applications to them, you must redeploy the web applications. For more information about deployment, see the Oracle GlassFish Server 3.0.1 Application Deployment Guide.

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 an application element.

applications

Contains deployed Java EE applications, Java EE modules, and applications created using other supported technologies.

Superelements

domain

Subelements

The following table describes subelements for the applications element.

Table 1–12 applications Subelements

Element 

Required 

Description 

application

zero or more 

Specifies an application. 

The application element replaces the web-module, j2ee-application, appclient-module, connector-module, lifecycle-module, extension-module, and ejb-module elements of previous releases, which are converted to application elements during the upgrade process.

lifecycle-module

zero or more 

Deprecated. Use application instead.

j2ee-application

zero or more 

Deprecated. Use application instead.

ejb-module

zero or more 

Deprecated. Use application instead.

web-module

zero or more 

Deprecated. Use application instead.

connector-module

zero or more 

Deprecated. Use application instead.

appclient-module

zero or more 

Deprecated. Use application instead.

extension-module

zero or more 

Deprecated. Use application instead.

audit-module

Specifies an optional plug-in module that implements audit capabilities. Audit modules collect and store information on incoming requests (servlets, EJB components) and outgoing responses.

Superelements

security-service

Subelements

The following table describes subelements for the audit-module element.

Table 1–13 audit-module Subelements

Element 

Required 

Description 

property

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

default

Specifies the name of this audit module. 

classname

com.sun.enterprise.security.Audit

Specifies the Java class that implements this audit module. 

Properties

The following table describes properties for the audit-module element.

Table 1–15 audit-module Properties

Attribute 

Default 

Description 

auditOn

false

If true, causes the loading of the audit module and ensures that it is called by the GlassFish Server’s audit library at audit points.

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 Oracle GlassFish Server 3.0.1 Administration Guide.

Here is an example of the default file realm:

<auth-realm name="file"
     classname="com.sun.enterprise.security.auth.realm.file.FileRealm">
     <property name="file" value="${com.sun.aas.instanceRoot}/config/admin-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.

Superelements

security-service

Subelements

The following table describes subelements for the auth-realm element.

Table 1–16 auth-realm Subelements

Element 

Required 

Description 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the auth-realm element.

Table 1–17 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 GlassFish Server have required and optional properties. A custom realm might have different properties.

The following table describes properties for the auth-realm element.

Table 1–18 auth-realm Properties

Property 

Realms 

Description 

jaas-context

all 

Specifies the JAAS (Java Authentication and Authorization Service) context. 

assign-groups

all 

(optional) If this property is set, its value is taken to be a comma-separated list of group names. All clients who present valid certificates are assigned membership to these groups for the purposes of authorization decisions in the web and EJB containers.

file

file

Specifies the file that stores user names, passwords, and group names. The default is domain-dir/config/keyfile.

clientAuth

certificate

If true, specifies that client authentication is required for all applications that use the certificate realm. The default is false.

To require client authentication for a specific web application, set the method of authentication in the web.xml file to CLIENT-CERT.

directory

ldap

Specifies the LDAP URL to your server. 

base-dn

ldap

Specifies the LDAP base DN for the location of user data. This base DN can be at any level above the user data, since a tree scope search is performed. The smaller the search tree, the better the performance. 

search-filter

ldap

(optional) Specifies the search filter to use to find the user. The default is uid=%s (%s expands to the subject name).

group-base-dn

ldap

(optional) Specifies the base DN for the location of groups data. By default, it is same as the base-dn, but it can be tuned, if necessary.

group-search-filter

ldap

(optional) Specifies the search filter to find group memberships for the user. The default is uniquemember=%d (%d expands to the user element DN).

group-target

ldap

(optional) Specifies the LDAP attribute name that contains group name entries. The default is CN.

search-bind-dn

ldap

(optional) Specifies an optional DN used to authenticate to the directory for performing the search-filter lookup. Only required for directories that do not allow anonymous search.

search-bind-password

ldap

(optional) Specifies the LDAP password for the DN given in search-bind-dn .

datasource-jndi

jdbc

Specifies the jndi-name of the jdbc-resource for the database.

user-table

jdbc

Specifies the name of the user table in the database. 

user-name-column

jdbc

Specifies the name of the user name column in the database's user table. 

password-column

jdbc

Specifies the name of the password column in the database's user table. 

group-table

jdbc

Specifies the name of the group table in the database. 

group-name-column

jdbc

Specifies the name of the group name column in the database's group table. 

db-user

jdbc

(optional) Allows you to specify the database user name in the realm instead of the jdbc-connection-pool. This prevents other applications from looking up the database, getting a connection, and browsing the user table. By default, the jdbc-connection-pool configuration is used.

db-password

jdbc

(optional) Allows you to specify the database password in the realm instead of the jdbc-connection-pool. This prevents other applications from looking up the database, getting a connection, and browsing the user table. By default, the jdbc-connection-pool configuration is used.

digest-algorithm

jdbc

(optional) Specifies the digest algorithm. The default is MD5. You can use any algorithm supported in the JDK, or none.

encoding

jdbc

(optional) Specifies the encoding. Allowed values are Hex and Base64. If digest-algorithm is specified, the default is Hex. If digest-algorithm is not specified, by default no encoding is specified.

charset

jdbc

(optional) Specifies the charset for the digest algorithm. 

B

backend-principal

Specifies the user name and password required by the Enterprise Information System (EIS).

Superelements

security-map

Subelements

none

Attributes

The following table describes attributes for the backend-principal element.

Table 1–19 backend-principal Attributes

Attribute 

Default 

Description 

user-name

none 

Specifies the user name required by the EIS. 

password

none 

(optional) Specifies the password required by the EIS, if any. 

C

config

Defines a configuration, which is a collection of settings that controls how a server instance functions.

Superelements

configs

Subelements

The following table describes subelements for the config element.

Table 1–20 config Subelements

Element 

Required 

Description 

http-service

only one 

Configures the HTTP service. 

network-config

only one 

Configures the communication network for the GlassFish Server. 

iiop-service

only one 

Configures the IIOP service. 

admin-service

only one 

Determines whether the server to which the configuration applies is an administration server. 

connector-service

zero or one 

Configures the connector service. 

web-container

only one 

Configures the web container. 

ejb-container

only one 

Configures the Enterprise JavaBeansTM (EJBTM) container.

mdb-container

only one 

Configures the message-driven bean (MDB) container. 

jms-service

zero or one 

Configures the JavaTM Message Service (JMS) provider.

log-service

only one 

Configures the system logging service. 

security-service

only one 

Configures the Java EE security service. 

transaction-service

only one 

Configures the transaction service. 

monitoring-service

only one 

Configures the monitoring service. 

java-config

only one 

Configures the Virtual Machine for the Java platform (JVMTM software).

thread-pools

only one 

Configures thread pools. 

system-property

zero or more 

Specifies a system property. 

property

zero or more 

Specifies a property or a variable. 

jruby-container

zero or one 

Configures the JRuby container. 

Attributes

The following table describes attributes for the config element.

Table 1–21 config Attributes

Attribute 

Default 

Description 

name

server-config

Specifies the name of the configuration. 

dynamic-reconfiguration-enabled

true

(optional) If true, any changes to the system (for example, applications deployed, resources created) are automatically applied to the affected servers without a restart being required. If false, such changes are only picked up by the affected servers when each server restarts.

configs

Contains configurations.

Superelements

domain

Subelements

The following table describes subelements for the configs element.

Table 1–22 configs Subelements

Element 

Required 

Description 

config

only one 

Defines a configuration. 

connection-pool

This element is not supported. If this element is present in the domain.xml file, its attributes are remapped to other elements and then it is deleted. For remapping details, see the Attributes table for this element.

Superelements

http-service

Subelements

none

Attributes

The following table describes attributes for the connection-pool element.

Table 1–23 connection-pool Attributes

Attribute 

Default 

Description 

queue-size-in-bytes

4096

Remapped to the max-queue-size attribute of the thread-pool element.

max-pending-count

4096

Remapped to the max-connections-count attribute of the transport element.

receive-buffer-size-in-bytes

4096

Remapped to the request-body-buffer-size-bytes attribute of the http element.

send-buffer-size-in-bytes

8192

Remapped to the send-buffer-size-bytes attribute of the http element.

connector-connection-pool

Defines a connector connection pool.

Superelements

resources

Subelements

The following table describes subelements for the connector-connection-pool element.

Table 1–24 connector-connection-pool Subelements

Element 

Required 

Description 

description

zero or one 

Contains a text description of this element. 

security-map

zero or more 

Maps the principal received during servlet or EJB authentication to the credentials accepted by the EIS. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the connector-connection-pool element. Changing the following attributes requires a server restart: resource-adapter-name, connection-definition-name, transaction-support, associate-with-thread, lazy-connection-association, and lazy-connection-enlistment. In addition, when you change a connector-connection-pool configuration, you should also redeploy or disable and re-enable the referring modules and applications.

Table 1–25 connector-connection-pool Attributes

Attribute 

Default 

Description 

name

none 

Specifies the name of the connection pool. A connector-resource element’s pool-name attribute refers to this name.

resource-adapter-name

none 

Specifies the name attribute of the deployed connector application element. If no name is specified during deployment, the name of the .rar file is used. If the resource adapter is embedded in an application, then it is app_name#rar_name.

connection-definition-name

none 

Specifies a unique name, identifying a resource adapter’s connection-definition element in the ra.xml file. This is usually the connectionfactory-interface of the connection-definition element.

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 idle connections to be destroyed if the existing number of connections is above the steady-pool-size (subject to the max-pool-size limit).

This is enforced periodically at the idle-timeout-in-seconds interval. An idle connection is one that has not been used for a period of idle-timeout-in-seconds. When the pool size reaches steady-pool-size, connection removal stops.

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 in descending order are: 

  • XATransaction - Supports distributed transactions.

  • LocalTransaction - Supports local transactions only.

  • NoTransaction - No transaction support.

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. 

validate-atmost-once-period-in-seconds

0

Specifies the time interval within which a connection is validated at most once. Minimizes the number of validation calls. A value of zero allows unlimited validation calls. 

connection-leak-timeout-in-seconds

0

Detects potential connection leaks by the application. A connection that is not returned back to the pool by the application within the specified period is assumed to be potentially leaking, and a stack trace of the caller is logged. A zero value disables leak detection. A nonzero value enables leak tracing. 

connection-leak-reclaim

false

If true, the pool will reclaim a connection after connection-leak-timeout-in-seconds occurs.

connection-creation-retry-attempts

0

Specifies the number of attempts to create a new connection. 

connection-creation-retry-interval-in-seconds

10

Specifies the time interval between attempts to create a connection when connection-creation-retry-attempts is greater than 0.

lazy-connection-enlistment

false

If true, a connection is not enlisted in a transaction until it is used. If false, any connection object available to a transaction is enlisted in the transaction.

lazy-connection-association

false

If true, a physical connection is not associated with a logical connection until it is used. If false, a physical connection is associated with a logical connection even before it is used.

associate-with-thread

false

If true, allows connections to be saved as ThreadLocal in the calling thread. Connections get reclaimed only when the calling thread dies or when the calling thread is not in use and the pool has run out of connections. If false, the thread must obtain a connection from the pool each time the thread requires a connection.

This attribute associates connections with a thread such that when the same thread is in need of connections, it can reuse the connections already associated with that thread. In this case, the overhead of getting connections from the pool is avoided. However, when this value is set to true, you should verify that the value of the max-pool-size attribute is comparable to the max-thread-pool-size attribute of the thread-pool element. If the max-thread-pool-size value is much higher than the max-pool-size value, a lot of time is spent associating connections with a new thread after dissociating them from an older one. Use this attribute in cases where the thread pool should reuse connections to avoid this overhead.

match-connections

true

If true, enables connection matching. You can set to false if connections are homogeneous.

max-connection-usage-count

0

Specifies the number of times a connections is reused by the pool, after which it is closed. A zero value disables this feature. 

ping

false

(optional) Specifies whether to ping the pool during pool creation or reconfiguration to identify and warn of any erroneous attribute values. 

pooling

true

(optional) If false, disables connection pooling.

Properties

Most properties of the connector-connection-pool element are the names of setter methods of the managedconnectionfactory-class element in the ra.xml file. Properties of the connector-connection-pool element override the ManagedConnectionFactory JavaBean configuration settings.

All but the last four properties in the following table are connector-connection-pool properties of jmsra, the resource adapter used to communicate with the GlassFish Message Queue software. For a complete list of the available properties (called administered object attributes in the Message Queue software), see the Oracle GlassFish Message Queue 4.4.2 Administration Guide.

Changes to connector-connection-pool properties require a server restart.

Table 1–26 connector-connection-pool Properties

Property 

Default 

Description 

AddressList

none 

Specifies a list of host/port combinations of the Message Queue software. For JMS resources of the Type javax.jms.TopicConnectionFactory or javax.jms.QueueConnectionFactory.

ClientId

none 

Specifies the JMS Client Identifier to be associated with a Connection created using the createTopicConnection method of the TopicConnectionFactory class. For JMS resources of the Type javax.jms.TopicConnectionFactory .

Durable subscription names are unique and only valid within the scope of a client identifier. To create or reactivate a durable subscriber, the connection must have a valid client identifier. The JMS specification ensures that client identifiers are unique and that a given client identifier is allowed to be used by only one active connection at a time. 

UserName

guest

Specifies the user name for connecting to the Message Queue software. For JMS resources of the Type javax.jms.TopicConnectionFactory or javax.jms.QueueConnectionFactory.

Password

guest

Specifies the password for connecting to the Message Queue software. For JMS resources of the Type javax.jms.TopicConnectionFactory or javax.jms.QueueConnectionFactory.

ReconnectAttempts

6

Specifies the number of attempts to connect (or reconnect) for each address in the imqAddressList before the client runtime moves on to try the next address in the list. A value of -1 indicates that the number of reconnect attempts is unlimited (the client runtime attempts to connect to the first address until it succeeds).

ReconnectInterval

30000

Specifies the interval between reconnect attempts in milliseconds. This applies to attempts on each address in the imqAddressList and on successive addresses in the list. If too short, this time interval does not give a broker time to recover. If too long, the reconnect might represent an unacceptable delay.

ReconnectEnabled

false

If true, specifies that the client runtime attempts to reconnect to a message server (or the list of addresses in imqAddressList) when a connection is lost.

AddressListBehavior

priority

Specifies whether connection attempts are in the order of addresses in the imqAddressList attribute (priority) or in a random order (random). If many clients are attempting a connection using the same connection factory, use a random order to prevent them from all being connected to the same address.

AddressListIterations

-1

Specifies the number of times the client runtime iterates through the imqAddressList in an effort to establish (or reestablish) a connection. A value of -1 indicates that the number of attempts is unlimited.

prefer-validate-over-recreate

false

Specifies that validating idle connections is preferable to closing them. This property has no effect on non-idle connections. If set to true, idle connections are validated during pool resizing, and only those found to be invalid are destroyed and recreated. If false, all idle connections are destroyed and recreated during pool resizing.

LazyConnectionEnlistment

false

Deprecated. Use the equivalent attribute. 

LazyConnectionAssociation

false

Deprecated. Use the equivalent attribute. 

AssociateWithThread

false

Deprecated. Use the equivalent attribute. 

MatchConnections

true

Deprecated. Use the equivalent attribute. 


Note –

All JMS administered object resource properties that worked with version 7 of the GlassFish Server are supported for backward compatibility.


connector-module

This element is deprecated. Use an application element instead.

Specifies a deployed connector module.

Superelements

applications

Subelements

The following table describes subelements for the connector-module element.

Table 1–27 connector-module Subelements

Element 

Required 

Description 

description

zero or one 

Contains a text description of this element. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the connector-module element.

Table 1–28 connector-module Attributes

Attribute 

Default 

Description 

name

none 

The name of the connector module. 

location

none 

A fully qualified or relative path to the directory to which the contents of the .rar file have been extracted. If relative, it is relative to the following directory:

domain-dir/applications/

object-type

user

(optional) Defines the type of the resource. Allowed values are: 

  • system-all - A system resource for all server instances and the domain application server.

  • system-admin - A system resource only for the domain application server.

  • system-instance - A system resource for all server instances only.

  • user - A user resource.

enabled

true

(optional) Determines whether the connector module is enabled. 

directory-deployed

false

(optional) Specifies whether the application has been deployed as a directory. 

connector-resource

Defines the connection factory object of a specific connection definition in a connector (resource adapter).

Superelements

resources

Subelements

The following table describes subelements for the connector-resource element.

Table 1–29 connector-resource Subelements

Element 

Required 

Description 

description

zero or one 

Contains a text description of this element. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the connector-resource element.

Table 1–30 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: 

  • system-all - A system resource for all server instances and the domain application server.

  • system-admin - A system resource only for the domain application server.

  • system-instance - A system resource for all server instances only.

  • user - A user resource.

enabled

true

(optional) Determines whether this resource is enabled at runtime. 

connector-service

Configures the connector service.

Superelements

config

Subelements

none

Attributes

The following table describes attributes for the connector-service element.

Table 1–31 connector-service Attributes

Attribute 

Default 

Description 

shutdown-timeout-in-seconds

30

(optional) Specifies the maximum time allowed during GlassFish Server shutdown for the ResourceAdapter.stop() method of a connector module’s instance to complete. Resource adapters that take longer to shut down are ignored, and GlassFish Server shutdown continues.

class-loading-policy

derived

(optional) Specifies the resource adapters accessible to applications. Allowed values are: 

  • derived — Applications access resource adapters based on references in their deployment descriptors. These references can be resource-ref, resource-env-ref, resource-adapter-mid, or equivalent annotations.

  • global — All stand-alone resource adapters are available to all applications.

context-param

Configures a context parameter for a web module at deployment time. This is an alternative to setting a context-param in the web.xml file. To override a context-param in the web.xml file, set the ignore-descriptor-item attribute to true.

Superelements

web-module-config

Subelements

The following table describes subelements for the context-param element.

Table 1–32 context-param Subelements

Element 

Required 

Description 

param-name

only one 

Contains a context parameter name. 

param-value

only one 

Contains a context parameter value. 

description

zero or one 

Contains a text description of this element. 

Attributes

The following table describes attributes for the context-param element.

Table 1–33 context-param Attributes

Attribute 

Default 

Description 

ignore-descriptor-item

false

(optional) If true, specifies that if the same context parameter occurs in the deployment descriptor it is ignored.

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.

Superelements

resources

Subelements

The following table describes subelements for the custom-resource element.

Table 1–34 custom-resource Subelements

Element 

Required 

Description 

description

zero or one 

Contains a text description of this element. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the custom-resource element.

Table 1–35 custom-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. 

factory-class

none 

Specifies the fully qualified name of the user-written factory class, which implements javax.naming.spi.ObjectFactory.

object-type

user

(optional) Defines the type of the resource. Allowed values are: 

  • system-all - A system resource for all server instances and the domain application server.

  • system-admin - A system resource only for the domain application server.

  • system-instance - A system resource for all server instances only.

  • user - A user resource.

enabled

true

(optional) Determines whether this resource is enabled at runtime. 

D

das-config

Defines a domain administration server configuration. The domain administration server runs the Administration Console.

Superelements

admin-service

Subelements

The following table describes subelements for the das-config element.

Table 1–36 das-config Subelements

Element 

Required 

Description 

property

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 Oracle GlassFish Server 3.0.1 Application Development Guide.

Table 1–37 das-config Attributes

Attribute 

Default 

Description 

dynamic-reload-enabled

true

(optional) If true, checks the timestamp on a .reload file at every module and application directory level, to trigger dynamic reloading.

dynamic-reload-poll-interval-in-seconds

2

(optional) Controls the polling frequency of dynamic reloading. 

autodeploy-enabled

true

(optional) If true, enables autodeployment, which lets you quickly deploy applications and modules to a running GlassFish Server without performing an explicit server instance restart or a separate deployment operation.

autodeploy-polling-interval-in-seconds

2

(optional) Controls the polling frequency of autodeployment. 

autodeploy-dir

autodeploy

(optional) Specifies the source directory (absolute or relative to domain-dir) in which autodeployment looks for deployable components.

autodeploy-verifier-enabled

false

(optional) If true, the verifier is run before autodeployment. If verification fails, deployment is not performed.

autodeploy-jsp-precompilation-enabled

false

(optional) If true, JSP pages are precompiled during autodeployment.

auto-deploy-retry-timeout

4

(optional) Specifies the number of autodeployment retry attempts before autodeployment times out. 

deploy-xml-validation

full

(optional) Specifies the type of XML validation performed on standard and GlassFish Server deployment descriptors: 

  • full - If XML validation fails, deployment fails.

  • parsing - XML validation errors are reported but deployment occurs.

  • none - No XML validation is performed.

admin-session-timeout-in-minutes

sun-web.xml timeoutSeconds property value or web.xml session-timeout attribute value

(optional) Specifies the Administration Console timeout. 

description

Contains a text description of the parent element.

Superelements

admin-object-resource, appclient-module, application, connector-connection-pool, connector-module, connector-resource, context-param, custom-resource, ejb-module, env-entry, extension-module, external-jndi-resource, j2ee-application, jdbc-connection-pool, jdbc-resource, lifecycle-module, mail-resource, property, system-property, transformation-rule, web-module

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.

Superelements

none

Subelements

The following table describes subelements for the domain element.

Table 1–38 domain Subelements

Element 

Required 

Description 

system-applications

zero or one 

Contains system applications. 

applications

zero or one 

Contains deployed Java EE applications, Java EE modules, and applications created using other supported technologies. 

resources

zero or one 

Contains configured resources. 

configs

only one 

Contains configurations. 

servers

only one 

Contains server instances. 

system-property

zero or more 

Specifies a system property. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the domain element.

Table 1–39 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. 

version

none; value changes with each major release 

Specifies the version of the GlassFish Server as returned by the fullVersion field of the com.sun.appserv.server.util.Version class.

E

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

Superelements

config

Subelements

The following table describes subelements for the ejb-container element.

Table 1–40 ejb-container Subelements

Element 

Required 

Description 

ejb-timer-service

zero or one 

Configures the EJB timer service. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the ejb-container element.

Table 1–41 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 removed when the pool-idle-timeout-in-seconds timer expires. A cleaner thread removes any unused instances.

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: 

  • created if a request arrives when the pool has no available beans (subject to the max-cache-size limit)

  • passivated when the cache-idle-timeout-in-seconds timer expires and a cleaner thread removes any unused instances, or when the cache size exceeds max-cache-size.

    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. 

victim-selection-policy

nru

(optional) Specifies how stateful session beans are selected for passivation. Allowed values are fifo, lru, and nru :

  • fifo - Selects the oldest instance.

  • lru - Selects the least recently accessed instance.

  • nru - Selects a not recently used instance.

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 stateful session beans and persisted HTTP sessions are stored in the file system. 

ejb-module

This element is deprecated. Use an application element instead.

Specifies a deployed EJB module.

Superelements

applications

Subelements

The following table describes subelements for the ejb-module element.

Table 1–42 ejb-module Subelements

Element 

Required 

Description 

description

zero or one 

Contains a text description of this element. 

web-service-endpoint

zero or more 

Configures a web service endpoint. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the ejb-module element.

Table 1–43 ejb-module Attributes

Attribute 

Default 

Description 

name

none 

The name of the EJB module. 

location

none 

A fully qualified or relative path to the directory to which the contents of the EJB .jar file have been extracted. If relative, it is relative to the following directory:

domain-dir/applications/

object-type

user

(optional) Defines the type of the resource. For an EJB module, the only allowed value is user.

enabled

true

(optional) Determines whether the EJB module is enabled. 

libraries

none 

(optional) Specifies an absolute or relative path to libraries specific to this module or application. A relative path is relative to domain-dir/lib/applibs. If the path is absolute, the path must be accessible to the domain administration server (DAS), which means it must be under domain-dir. To include more than one path, use a system-specific separator, such as a colon for Solaris or a semicolon for Windows. The libraries are made available to the application in the order in which they are specified.

directory-deployed

false

(optional) Specifies whether the application has been deployed as a directory. 

ejb-timer-service

Configures the EJB timer service.

Superelements

ejb-container

Subelements

The following table describes subelements for the ejb-timer-service element.

Table 1–44 ejb-timer-service Subelements

Element 

Required 

Description 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the ejb-timer-service element.

Table 1–45 ejb-timer-service Attributes

Attribute 

Default 

Description 

minimum-delivery-interval-in-millis

1000

(optional) Specifies the minimum time before an expiration for a particular timer can occur. This guards against extremely small timer increments that can overload the server. 

max-redeliveries

1

(optional) Specifies the maximum number of times the EJB timer service attempts to redeliver a timer expiration due for exception or rollback. 

timer-datasource

jdbc/__TimerPool

(optional) Overrides, for the server instance, the cmp-resource value specified in sun-ejb-jar.xml for the timer service system application (__ejb_container_timer_app ).

redelivery-interval-internal-in-millis

5000

(optional) Specifies how long the EJB timer service waits after a failed ejbTimeout delivery before attempting a redelivery.

engine

Specifies an engine for an application or module. An engine runs a sniffer during deployment, which is responsible for identifying a type of deployment artifact (such as a WAR file) and setting up the associated container (such as the web container). Multiple engines, each with its own sniffer, can be associated with a given application or module.

Superelements

application, module

Subelements

The following table describes subelements for the engine element.

Table 1–46 engine Subelements

Element 

Required 

Description 

web-module-config

zero or one 

Configures the parent web module. Applicable only if this engine element has a sniffer value of web.

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the engine element.

Table 1–47 engine Attributes

Attribute 

Default 

Description 

sniffer

none 

Specifies the type of sniffer. Allowed values include the following: 

  • web — Specifies that the parent module is a web application.

  • security — Specifies that security is enabled for the parent module.

  • jpa — Specifies that the parent module uses the Java Persistence API.

  • connector — Specifies that the parent module is a connector.

  • ejb — Specifies that the parent module is an EJB module. The EJB container add-on component must be installed in the GlassFish Server.

  • webservices — Specifies that the parent module is a web service endpoint. The Metro add-on component must be installed in the GlassFish Server.

  • appclient — Specifies that the parent module is an application client. This value is valid only in the full platform distribution of the GlassFish Server.

  • ear — Specifies that the parent application is a Java EE application (EAR file). This value is valid only in the full platform distribution of the GlassFish Server.

  • webbeans — Specifies that the parent module is a Web Bean. The Web Beans add-on component must be installed in the GlassFish Server.

  • jruby — Specifies that the parent module is a JRuby application. The JRuby add-on component must be installed in the GlassFish Server.

  • osgi — Specifies that the parent module is an OSGi add-on component.

  • grizzly — Specifies that the parent module is a Grizzly add-on component.

description

none 

(optional) Specifies a text description for this element. 

env-entry

Configures an environment entry for a web module at deployment time. This is an alternative to setting an env-entry in the web.xml file. To override an env-entry in the web.xml file, set the ignore-descriptor-item attribute to true.

Superelements

web-module-config

Subelements

The following table describes subelements for the env-entry element.

Table 1–48 env-entry Subelements

Element 

Required 

Description 

env-entry-name

only one 

Contains an environment entry name. 

env-entry-type

only one 

Contains an environment entry type. 

env-entry-value

only one 

Contains an environment entry value. 

description

zero or one 

Contains a text description of this element. 

Attributes

The following table describes attributes for the env-entry element.

Table 1–49 env-entry Attributes

Attribute 

Default 

Description 

ignore-descriptor-item

false

(optional) If true, specifies that if the same environment entry occurs in the deployment descriptor it is ignored.

env-entry-name

Contains an environment entry name.

Superelements

env-entry

Subelements

none - contains data

env-entry-type

Contains an environment entry type.

Superelements

env-entry

Subelements

none - contains data

env-entry-value

Contains an environment entry value.

Superelements

env-entry

Subelements

none - contains data

extension-module

This element is deprecated. Use an application element instead.

Specifies a deployed extension module.

Superelements

applications

Subelements

The following table describes subelements for the extension-module element.

Table 1–50 extension-module Subelements

Element 

Required 

Description 

description

zero or one 

Contains a text description of this element. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the extension-module element.

Table 1–51 extension-module Attributes

Attribute 

Default 

Description 

name

none 

The name of the extension module. 

location

none 

A fully qualified or relative path to the directory to which the contents of the .jar or .war file have been extracted. If relative, it is relative to the following directory:

domain-dir/applications/

module-type

none 

Specifies a String that identifies the extension module type, which the runtime uses to find the appropriate add-on container. When an extension module is registered with the GlassFish Server, the GlassFish Server specifies the module type automatically.

object-type

user

(optional) Defines the type of the resource. For an extension module, the only allowed value is user.

enabled

true

(optional) Determines whether the extension module is enabled. 

libraries

none 

(optional) Specifies an absolute or relative path to libraries specific to this module or application. A relative path is relative to domain-dir/lib/applibs. If the path is absolute, the path must be accessible to the domain administration server (DAS), which means it must be under domain-dir. To include more than one path, use a system-specific separator, such as a colon for Solaris or a semicolon for Windows. The libraries are made available to the application in the order in which they are specified.

directory-deployed

false

(optional) Specifies whether the application has been deployed as a directory. 

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.

Superelements

resources

Subelements

The following table describes subelements for the external-jndi-resource element.

Table 1–52 external-jndi-resource Subelements

Element 

Required 

Description 

description

zero or one 

Contains a text description of this element. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the external-jndi-resource element.

Table 1–53 external-jndi-resource Attributes

Attribute 

Default 

Description 

jndi-name

none 

Specifies the JNDI name for the resource. 

jndi-lookup-name

none 

Specifies the JNDI lookup name for the resource. 

res-type

none 

Specifies the fully qualified type of the resource. 

factory-class

none 

Specifies the fully qualified name of the factory class, which implements javax.naming.spi.InitialContextFactory.

For more information about JNDI, see the Oracle GlassFish Server 3.0.1 Application Development Guide.

object-type

user

(optional) Defines the type of the resource. Allowed values are: 

  • system-all - A system resource for all server instances and the domain application server.

  • system-admin - A system resource only for the domain application server.

  • system-instance - A system resource for all server instances only.

  • user - A user resource.

enabled

true

(optional) Determines whether this resource is enabled at runtime. 

F

file-cache

Configures the HTTP file cache.

Superelements

http

Subelements

none

Attributes

The following table describes attributes for the file-cache element.

Table 1–54 file-cache Attributes

Attribute 

Default 

Description 

enabled

false

(optional) If true, enables caching of the file content.

max-age-seconds

30

(optional) Specifies the maximum age of a file cache entry. 

max-cache-size-bytes

1048576

(optional) Specifies the total size of all files that are cached as memory mapped files. 

max-files-count

1024

(optional) Specifies the maximum number of files in the file cache. 

G

group-map

Maps an EIS group to a group defined in the GlassFish Server domain.

Superelements

work-security-map

Subelements

none

Attributes

The following table describes attributes for the group-map element.

Table 1–55 group-map Attributes

Attribute 

Default 

Description 

eis-group

none 

Specifies an EIS group. 

mapped-group

none 

Specifies a group defined in the GlassFish Server domain. 

H

http

Configures HTTP parameters.

Superelements

protocol

Subelements

The following table describes subelements for the http element.

Table 1–56 http Subelements

Element 

Required 

Description 

file-cache

zero or one 

Configures the HTTP file cache. 

Attributes

The following table describes attributes for the http element.

Table 1–57 http Attributes

Attribute 

Default 

Description 

default-virtual-server

none 

Specifies the id attribute of the default virtual-server for the network-listener that references the parent protocol element.

server-name

none 

(optional) 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 network-listener that references the parent protocol element 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.

request-body-buffer-size-bytes

4096

(optional) Specifies the size of the request buffer for network-listener elements that reference the parent protocol element.

send-buffer-size-bytes

8192

(optional) Specifies the size of the send buffer for network-listener elements that reference the parent protocol element.

auth-pass-through-enabled

false

(optional) If true, indicates that the network-listener that references the parent protocol element receives traffic from an SSL-terminating proxy server.

max-connections

250

(optional) Specifies the maximum number of requests that can be pipelined until the connection is closed by the server. Set this property to 1 to disable HTTP/1.0 keep-alive, as well as HTTP/1.1 keep-alive and pipelining. A value of 0 means requests are always rejected. A value of -1 sets no limit to the number of keep-alive connections.

The default of 250 is the initial value set in domain.xml. The internal configuration default is 256.

trace-enabled

true

(optional) If true, enables the TRACE operation. Set this property to false to make the GlassFish Server less susceptible to cross-site scripting attacks.

comet-support-enabled

false

(optional) If true, enables Comet support for the network-listener that references the parent protocol element.

If your servlet or JSP page uses Comet technology, make sure it is initialized when the GlassFish Server starts up by adding the load-on-startup element to your web.xml file. For example:

<servlet>
   <servlet-name>CheckIn</servlet-name>
   <servlet-class>CheckInServlet</servlet-class>
   <load-on-startup>0</load-on-startup>
</servlet>

compression

off

(optional) Specifies use of HTTP/1.1 GZIP compression to save server bandwidth. Allowed values are: 

  • off — Disables compression.

  • on — Compresses data.

  • force — Forces data compression in all cases.

If compression is set to on or force, you must set compression-min-size-bytes as well.

compression-min-size-bytes

none 

(optional) Specifies the minimum size of a file when compression is applied. Required if compression is set to on or force.

compressable-mime-type

text/html,text/xml,text/plain

(optional) Specifies a comma-separated list of MIME types for which HTTP compression is used. 

no-compression-user-agents

empty String (regexp matching disabled)

(optional) Specifies a comma-separated list of regular expressions matching user-agents of HTTP clients for which compression should not be used. 

upload-timeout-enabled

false

(optional) If true, the connection for a servlet that reads bytes slowly is closed after the connection-upload-timeout-millis is reached.

connection-upload-timeout-millis

5

(optional) Specifies the timeout for uploads. Applicable only if upload-timeout-enabled is set to true.

uri-encoding

UTF-8

(optional) Specifies the character set used to decode the request URIs received on the network-listener that references the parent protocol element. Must be a valid IANA character set name.

restricted-user-agents

none 

(optional) Specifies a list of restricted user agents on which HTTP compression is applied. If no user agents are specified (the default), HTTP compression is applied to all user agents. 

chunking-enabled

true

(optional) If true, enables HTTP response chunking.

version

HTTP/1.1

(optional) Specifies the version of the HTTP protocol used. 

forced-response-type

text/html; charset=iso-8859-1

(optional) Specifies the request type used if no MIME mapping is available that matches the file extension. The format is a semicolon-delimited string consisting of the content-type, encoding, language, and charset. 

default-response-type

text/html; charset=iso-8859-1

(optional) Specifies the default response type. The format is a semicolon-delimited string consisting of the content-type, encoding, language, and charset. 

timeout-seconds

30

(optional) Specifies the maximum time for which a keep alive connection is kept open. A value of 0 or less means keep alive connections are kept open indefinitely.

header-buffer-length-bytes

8192

(optional) Specifies the size of the buffer used by the request processing threads to read the request data. 

adapter

com.sun.grizzly.tcp.StaticResourcesAdapter

(Optional) Specifies the class name of the static resources adapter. 

max-post-size-bytes

2097152

(Optional) Specifies the maximum size of the body of a POST request. POST requests greater than this size are rejected. A value of zero means the maximum post size is unlimited. 

request-timeout-seconds

30

(Optional) Specifies the request timeout. If the request is not processed before the timeout is reached, the request is ignored. 

dns-lookup-enabled

false

(optional) If true, looks up the DNS entry for the client.

rcm-support-enabled

false

(optional) If true, enables support for resource consumption management (RCM). A ResourceAllocationFilter is added to the HTTP protocol chain, and a thread pool for request processing is assigned to each HTTP resource (such as a web application).

http-access-log

Defines an access log file for a virtual-server. The access-log subelement of the virtual server’s parent http-service element determines the access log file’s format and rotation settings.

Superelements

virtual-server

Subelements

none

Attributes

The following table describes attributes for the http-access-log element.

Table 1–58 http-access-log Attributes

Attribute 

Default 

Description 

log-directory

${com.sun.aas.instanceRoot}/logs/access

(optional) Specifies the location of the access log file. The ${com.sun.aas.instanceRoot} system property refers to the domain-dir. See system-property.

iponly

true

(optional) If true, specifies that only the IP address of the user agent is listed. If false, performs a DNS lookup.

http-file-cache

This element is not supported. If this element is present in the domain.xml file, its attributes are remapped to other elements and then it is deleted. For remapping details, see the Attributes table for this element.

Superelements

http-service

Subelements

none

Attributes

The following table describes attributes for the http-file-cache element.

Table 1–59 http-file-cache Attributes

Attribute 

Default 

Description 

globally-enabled

false

Not implemented. Do not use. 

file-caching-enabled

false

Remapped to the enabled attribute of the file-cache element.

max-age-in-seconds

30

Remapped to the max-age-seconds attribute of the file-cache element.

medium-file-size-limit-in-bytes

537600

Not implemented. Do not use. 

medium-file-space-in-bytes

1048576

Remapped to the max-cache-size-bytes attribute of the file-cache element.

small-file-size-limit-in-bytes

2048

Not implemented. Do not use. 

small-file-space-in-bytes

1048576

Not implemented. Do not use. 

file-transmission-enabled

false

Not implemented. Do not use. 

max-files-count

1024

Remapped to the max-files-count attribute of the file-cache element.

hash-init-size

0

Not implemented. Do not use. 

http-listener

This element is not supported. If this element is present in the domain.xml file, its attributes and properties are remapped to other elements and then it is deleted. For remapping details, see the Attributes and Properties tables for this element.

Superelements

http-service

Subelements

The following table describes subelements for the http-listener element.

Table 1–60 http-listener Subelements

Element 

Required 

Description 

ssl

zero or one 

Defines Secure Socket Layer (SSL) parameters. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the http-listener element.

Table 1–61 http-listener Attributes

Attribute 

Default 

Description 

id

none 

Remapped to the name attribute of a network-listener element.

address

none 

Remapped to the address attribute of a network-listener element.

port

none 

Remapped to the port attribute of a network-listener element.

external-port

none 

Not implemented. Do not use. 

family

 

Not implemented. Do not use. 

blocking-enabled

false

Not implemented. Do not use. 

acceptor-threads

1

Remapped to the acceptor-threads attribute of a transport element.

security-enabled

false

Remapped to the security-enabled attribute of a protocol element.

default-virtual-server

none 

Remapped to the default-virtual-server attribute of an http element.

server-name

none 

Remapped to the server-name attribute of an http element.

redirect-port

none 

Remapped to the redirect-port attribute of an http element.

xpowered-by

true

Remapped to the xpowered-by attribute of an http element.

enabled

true

Remapped to the enabled attribute of a network-listener element.

Properties

The following table describes property remappings for the http-listener element. A few of these properties can be defined as http-service properties, applying to all network-listener elements.

Table 1–62 http-listener Properties

Property 

Default 

Description 

monitoring-cache-enabled

true

Not implemented. Do not use. 

monitoring-cache-refresh-in-millis

5000

Not implemented. Do not use. 

ssl-cache-entries

10000

Implemented only for http-service.

ssl3-session-timeout

86400

Implemented only for http-service.

ssl-session-timeout

100

Implemented only for http-service.

recycle-objects

true

Not implemented. Do not use. 

reader-threads

0

Not implemented. Do not use. 

acceptor-queue-length

4096

Not implemented. Do not use. 

reader-queue-length

4096

Not implemented. Do not use. 

use-nio-direct-bytebuffer

true

Remapped to the byte-buffer-type attribute of a transport element.

authPassthroughEnabled

false

Remapped to the auth-pass-through-enabled attribute of an http element.

proxyHandler

com.sun.enterprise.web.ProxyHandlerImpl

Implemented only for http-service.

proxiedProtocol

none 

Not implemented. Do not use. 

bufferSize

4096

Remapped to the buffer-size-bytes attribute of a transport element.

connectionTimeout

30

Implemented only for http-service.

maxKeepAliveRequests

250

Remapped to the max-connections attribute of an http element.

traceEnabled

true

Remapped to the trace-enabled attribute of an http element.

cometSupport

false

Remapped to the comet-support-enabled attribute of an http element.

jkEnabled

false

Remapped to the jk-enabled attribute of a network-listener element.

compression

off

Remapped to the compression attribute of an http element.

compressableMimeType

text/html,text/xml,text/plain

Remapped to the compressable-mime-type attribute of an http element.

noCompressionUserAgents

empty String (regexp matching disabled)

Remapped to the no-compression-user-agents attribute of an http element.

minCompressionSize or compressionMinSize

none 

Remapped to the compression-min-size-bytes attribute of an http element.

crlFile

none 

Remapped to the crl-file attribute of an ssl element.

trustAlgorithm

none  

Remapped to the trust-algorithm attribute of an ssl element.

trustMaxCertLength

5

Remapped to the trust-max-cert-length attribute of an ssl element.

disableUploadTimeout

true

Remapped to the upload-timeout-enabled attribute of an http element.

connectionUploadTimeout

5

Remapped to the connection-upload-timeout-millis attribute of an http element.

uriEncoding

UTF-8

Remapped to the uri-encoding attribute of an http element.

http-protocol

This element is not supported. If this element is present in the domain.xml file, its attributes are remapped to other elements and then it is deleted. For remapping details, see the Attributes table for this element.

Superelements

http-service

Subelements

none

Attributes

The following table describes attributes for the http-protocol element.

Table 1–63 http-protocol Attributes

Attribute 

Default 

Description 

version

HTTP/1.1

Remapped to the version attribute of an http element.

dns-lookup-enabled

false

Remapped to the dns-lookup-enabled attribute of an http element.

forced-type

text/html; charset=iso-8859-1

Remapped to the forced-response-type attribute of an http element.

default-type

text/html; charset=iso-8859-1

Remapped to the default-response-type attribute of an http element.

forced-response-type

text/plain; charset=iso-8859-1

Remapped to the forced-response-type attribute of an http element.

default-response-type

text/plain; charset=iso-8859-1

Remapped to the default-response-type attribute of an http element.

ssl-enabled

true

Not implemented. Use ssl subelements of protocol elements.

http-service

Defines the HTTP service.

Superelements

config

Subelements

The following table describes subelements for the http-service element.

Table 1–64 http-service Subelements

Element 

Required 

Description 

access-log

zero or one 

Defines access log settings for each http-access-log subelement of each virtual-server.

http-listener

one or more 

Not implemented. See the element description for attribute and property remapping. 

virtual-server

one or more 

Defines a virtual server. 

request-processing

zero or one 

Not implemented. See the element description for attribute remapping. 

keep-alive

zero or one 

Not implemented. See the element description for attribute remapping. 

connection-pool

zero or one 

Not implemented. See the element description for attribute remapping. 

http-protocol

zero or one 

Not implemented. See the element description for attribute remapping. 

http-file-cache

zero or one 

Not implemented. See the element description for attribute remapping. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the http-service element.

Table 1–65 http-service Attributes

Attribute 

Default 

Description 

access-logging-enabled

false

If true, enables access logging for all virtual-server subelements that specify this attribute as true or inherit. If false, disables access logging for all virtual-server subelements that specify this attribute as false or inherit.

sso-enabled

false

If true, single sign-on is enabled by default for all web applications on all virtual servers on this server instance that are configured for the same realm. If false, single sign-on is disabled by default for all virtual servers, and users must authenticate separately to every application on each virtual server.

A true or false setting of the sso-enabled attribute of the virtual-server element overrides this setting for an individual virtual server. An inherit setting of the sso-enabled attribute of the virtual-server element uses this setting for an individual virtual server.

At the http-service level, you cannot change the sso-max-inactive-seconds and sso-reap-interval-seconds values from their defaults. However, you can change these values at the virtual-server level.

Properties

The following table describes properties for the http-service element that are still supported. These properties apply to all network-listener elements.

Most properties for this element are no longer supported. For information about how other properties have been remapped, see the Properties table for http-listener.

Table 1–66 http-service Properties

Property 

Default 

Description 

ssl-cache-entries

10000

Specifies the number of SSL sessions to be cached. 

ssl3-session-timeout

86400

Specifies the interval at which SSL3 sessions are cached. 

ssl-session-timeout

100

Specifies the interval at which SSL2 sessions are cached. 

proxyHandler

com.sun.enterprise.web.ProxyHandlerImpl

Specifies the fully qualified class name of a custom implementation of the com.sun.appserv.ProxyHandler abstract class, which allows a back-end server instance to retrieve information about the original client request that was intercepted by an SSL-terminating proxy server. An implementation of this abstract class inspects a given request for the custom request headers through which the proxy server communicates the information about the original client request to the GlassFish Server instance, and returns that information to its caller.

The default implementation reads the client IP address from an HTTP request header named Proxy-ip, the SSL keysize from an HTTP request header named Proxy-keysize, and the SSL client certificate chain from an HTTP request header named Proxy-auth-cert. The Proxy-auth-cert value must contain the BASE-64 encoded client certificate chain without the BEGIN CERTIFICATE and END CERTIFICATE boundaries and with \n replaced with % d% a.

Only used if the auth-pass-through-enabled attribute of the network-listener element's grandchild http element is set to true.

connectionTimeout

30

Specifies the number of seconds an HTTP network-listener waits, after accepting a connection, for the request URI line to be presented.

I

iiop-listener

Defines an IIOP listen socket. To enable SSL for this listener, include an ssl subelement.

Superelements

iiop-service

Subelements

The following table describes subelements for the iiop-listener element.

Table 1–67 iiop-listener Subelements

Element 

Required 

Description 

ssl

zero or one 

Defines SSL parameters. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the iiop-listener element.

Table 1–68 iiop-listener Attributes

Attribute 

Default 

Description 

id

none 

The listener name. An iiop-listener name cannot begin with a number.

address

none 

IP address of the listener. Can be in dotted-pair or IPv6 notation, or just a name. 

port

1072

(optional) Port number for the listener. Legal values are 1 - 65535. On UNIX, creating sockets that listen on ports 1 - 1024 requires superuser privileges.

security-enabled

false

(optional) Determines whether the listener runs SSL. To turn SSL2 or SSL3 on or off and set ciphers, use an ssl element.

enabled

true

(optional) Determines whether the listener is active. 

iiop-service

Defines the IIOP service.

Superelements

config

Subelements

The following table describes subelements for the iiop-service element.

Table 1–69 iiop-service Subelements

Element 

Required 

Description 

orb

only one 

Configures the ORB. 

ssl-client-config

zero or one 

Defines SSL parameters for the ORB. 

iiop-listener

zero or more 

Defines an IIOP listen socket. 

Attributes

The following table describes attributes for the iiop-service element.

Table 1–70 iiop-service Attributes

Attribute 

Default 

Description 

client-authentication-required

false

(optional) If true, the server rejects unauthenticated requests and inserts an authentication-required bit in IORs sent to clients.

J

j2ee-application

This element is deprecated. Use an application element instead.

Specifies a deployed Java EE application.

Superelements

applications

Subelements

The following table describes subelements for the j2ee-application element.

Table 1–71 j2ee-application Subelements

Element 

Required 

Description 

description

zero or one 

Contains a text description of this element. 

web-service-endpoint

zero or more 

Configures a web service endpoint. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the j2ee-application element.

Table 1–72 j2ee-application Attributes

Attribute 

Default 

Description 

name

none 

The name of the application. 

location

none 

A fully qualified or relative path to the directory to which the contents of the .ear file have been extracted. If relative, it is relative to the following directory:

domain-dir/applications/

object-type

user

(optional) Defines the type of the resource. For an application, the only allowed value is user.

enabled

true

(optional) Determines whether the application is enabled. 

libraries

none 

(optional) Specifies an absolute or relative path to libraries specific to this module or application. A relative path is relative to domain-dir/lib/applibs. If the path is absolute, the path must be accessible to the domain administration server (DAS), which means it must be under domain-dir. To include more than one path, use a system-specific separator, such as a colon for Solaris or a semicolon for Windows. The libraries are made available to the application in the order in which they are specified.

directory-deployed

false

(optional) Specifies whether the application has been deployed as a directory. 

java-web-start-enabled

true

(optional) Specifies whether Java Web Start access is permitted for application clients in this application. 

jacc-provider

Specifies a Java Authorization Contract for Containers (JACC) provider for pluggable authorization.

Superelements

security-service

Subelements

The following table describes subelements for the jacc-provider element.

Table 1–73 jacc-provider Subelements

Element 

Required 

Description 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the jacc-provider element.

Table 1–74 jacc-provider Attributes

Attribute 

Default 

Description 

name

default

Specifies the name of the JACC provider. 

policy-provider

com.sun.enterprise.security.provider.PolicyWrapper

Specifies the fully qualified class name of the JACC policy provider. Corresponds to and can be overridden by the system property javax.security.jacc.policy.provider .

policy-configuration-factory-provider

com.sun.enterprise.security.provider.PolicyConfigurationFactoryImpl

Specifies the fully qualified class name of the JACC policy configuration factory provider. Corresponds to and can be overridden by the system property javax.security.jacc.PolicyConfigurationFactory.provider .

Properties

The following table describes properties for the jacc-provider element.

Table 1–75 jacc-provider Properties

Property 

Default 

Description 

repository

domain-dir/generated/policy

Specifies the directory containing the policy file. 

java-config

Specifies the Virtual Machine for the Java platform (JVM software) configuration parameters.

Superelements

config

Subelements

The following table describes subelements for the java-config element.

Table 1–76 java-config Subelements

Element 

Required 

Description 

profiler

zero or one 

Configures a profiler for use with the GlassFish Server. 

jvm-options

zero or more 

Contains JVM command line options. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the java-config element.

Table 1–77 java-config Attributes

Attribute 

Default 

Description 

java-home

${com.sun.aas.javaRoot}

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 at http://java.sun.com/javase/technologies/core/toolsapis/jpda/.

For more information about debugging, see the Oracle GlassFish Server 3.0.1 Application Development 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/javase/6/docs/technotes/tools/solaris/rmic.html.

javac-options

-g

(optional) Specifies options passed to the Java compiler at application deployment time. 

classpath-suffix

none 

Not implemented. Do not use. 

system-classpath

none 

Not implemented. Do not use. 

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

Not implemented. Do not use. 

jdbc-connection-pool

Defines the properties that are required for creating a JDBC connection pool.

Superelements

resources

Subelements

The following table describes subelements for the jdbc-connection-pool element.

Table 1–78 jdbc-connection-pool Subelements

Element 

Required 

Description 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the jdbc-connection-pool element. Changing the following attributes requires a server restart: datasource-classname, driver-classname, associate-with-thread, lazy-connection-association, and lazy-connection-enlistment. In addition, when you change a jdbc-connection-pool configuration, you should also redeploy or disable and re-enable the referring modules and applications.

Table 1–79 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.

description

none 

(optional) Specifies a text description of this element. 

datasource-classname

none 

(optional) Specifies the class name of the associated vendor-supplied data source. This class must implement javax.sql.DataSource, javax.sql.XADataSource , javax.sql.ConnectionPoolDatasource, or a combination.

res-type

none 

(optional) Specifies the interface the data source class implements. The value of this attribute can be javax.sql.DataSource, javax.sql.XADataSource , javax.sql.ConnectionPoolDatasource, or java.sql.Driver. To support configuration of JDBC drivers and applications that use java.sql.Driver implementations, set this attribute to java.sql.Driver. This attribute must be specified to avoid ambiguity when a data source class implements two or more of these interfaces or when a driver-classname is specified. An error occurs if this attribute has a legal value and the indicated interface is not implemented by the data source class.

driver-classname

none 

(optional) Specifies the vendor-supplied JDBC driver class name. This driver must implement the java.sql.Driver interface.

ping

false

(optional) Specifies whether to ping the pool during pool creation or reconfiguration to identify and warn of any erroneous attribute values. 

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 idle connections to be destroyed if the existing number of connections is above the steady-pool-size (subject to the max-pool-size limit).

This is enforced periodically at the idle-timeout-in-seconds interval. An idle connection is one that has not been used for a period of idle-timeout-in-seconds. When the pool size reaches steady-pool-size, connection removal stops.

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. 

This timeout value must be kept shorter than the server side (database) timeout value to prevent the accumulation of unusable connections in the application. 

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

table

(optional) Legal values are as follows: 

  • auto-commit, which uses Connection.setAutoCommit(Connection.getAutoCommit())

  • meta-data, which uses Connection.getMetaData()

  • table, which performs a query on a table specified in the validation-table-name attribute

  • custom-validation, which uses a user-defined validation mechanism specified by the custom implementation class in validation-classname.

Because many JDBC drivers cache the results of auto-commit and meta-data calls, they do not always provide reliable validations. Check with the driver vendor to determine whether these calls are cached or not.

The table must exist and be accessible, but it doesn't require any rows. Do not use an existing table that has a large number of rows or a table that is already frequently accessed. More details can be found at Connection Validation in GlassFish JDBC.

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 is enabled and connection-validation-method is set to table.

validation-classname

none 

(optional) Specifies the custom validation implementation class name. This parameter is mandatory if and only if connection-validation is enabled and connection-validation-method is set to custom-validation. The classname provided must be accessible to the GlassFish Server. The specified class must implement the org.glassfish.api.jdbc.ConnectionValidation interface.

Some of the built-in validation classes for commonly used databases are: 


org.glassfish.jdbc.validation.DerbyConnectionValidation,
org.glassfish.jdbc.validation.MySQLConnectionValidation,
org.glassfish.jdbc.validation.OracleConnectionValidation,
org.glassfish.jdbc.validation.PostgresConnectionValidation
org.glassfish.jdbc.validation.JDBC40ConnectionValidation

The last class can apply to any JDBC 4.0 compliant driver. 

init-sql

none 

(optional) Specifies an SQL string to be executed whenever a physical connection to the database is created (not reused) from the pool. This initializes the state of the connection. 

fail-all-connections

false

(optional) If true, closes all connections in the pool if a single validation check fails. This parameter is applicable if and only if is-connection-validation-required is set to true.

non-transactional-connections

false

(optional) If true, non-transactional connections can be made to the JDBC connection pool. These connections are not automatically enlisted with the transaction manager.

allow-non-component-callers

false

(optional) If true, non-Java-EE components, such as servlet filters, lifecycle modules, and third party persistence managers, can use this JDBC connection pool. The returned connection is automatically enlisted with the transaction context obtained from the transaction manager. Standard Java EE components can also use such pools. Connections obtained by non-component callers are not automatically closed at the end of a transaction by the container. They must be explicitly closed by the caller.

validate-atmost-once-period-in-seconds

0

(optional) Specifies the time interval within which a connection is validated at most once. Minimizes the number of validation calls. A value of zero allows unlimited validation calls. 

connection-leak-timeout-in-seconds

0

(optional) Detects potential connection leaks by the application. A connection that is not returned back to the pool by the application within the specified period is assumed to be potentially leaking, and a stack trace of the caller is logged. A zero value disables leak detection. A nonzero value enables leak tracing. 

Use this attribute along with connection-leak-reclaim to avoid potential connection leaks from the application. More details are at Connection Leak Tracing.

connection-leak-reclaim

false

(optional) If true, the pool will reclaim a connection after connection-leak-timeout-in-seconds occurs.

connection-creation-retry-attempts

0

(optional) Specifies the number of attempts to create a new connection in case of a failure. 

connection-creation-retry-interval-in-seconds

10

(optional) Specifies the time interval between attempts to create a connection when connection-creation-retry-attempts is greater than 0.

statement-timeout-in-seconds

-1

(optional) Sets the query timeout property of a statement to enable termination of abnormally long running queries. The default value of -1 disables this feature.

An abnormally long running JDBC query executed by an application may leave it in a hanging state unless a timeout is explicitly set on the statement. This attribute guarantees that all queries automatically time out if not completed within the specified period. When statements are created, the queryTimeout is set according to the value specified in this attribute. This works only when the underlying JDBC driver supports queryTimeout for Statement, PreparedStatement, CallableStatement, and ResultSet.

lazy-connection-enlistment

false

(optional) If true, a connection is not enlisted in a transaction until it is used. If false, any connection object available to a transaction is enlisted in the transaction.

lazy-connection-association

false

(optional) If true, a physical connection is not associated with a logical connection until it is used. If false, a physical connection is associated with a logical connection even before it is used.

associate-with-thread

false

(optional) Specifies whether connectionsare associated with the thread to enable the thread to reuse the connections. If true, allows connections to be saved as ThreadLocal in the calling thread. Connections get reclaimed only when the calling thread dies or when the calling thread is not in use and the pool has run out of connections. If false, the thread must obtain a connection from the pool each time the thread requires a connection.

This attribute associates connections with a thread such that when the same thread is in need of connections, it can reuse the connections already associated with that thread. In this case, the overhead of getting connections from the pool is avoided. However, when this value is set to true, you should verify that the value of the max-pool-size attribute is comparable to the max-thread-pool-size attribute of the thread-pool element. If the max-thread-pool-size value is much higher than the max-pool-size value, a lot of time is spent associating connections with a new thread after dissociating them from an older one. Use this attribute in cases where the thread pool should reuse connections to avoid this overhead.

match-connections

false

(optional) Specifies whether a connection that is selected from the pool should be matched with the connections with certain credentials. If true, enables connection matching. You can set to false if connections are homogeneous.

If the connection pool is used by applications that have multiple user credentials, match-connections must be true. The connection pool matches the request's credential with the connections in the pool and returns a matched connection for use. For new requests with different credentials, unmatched free connections are automatically purged to provide new connections to satisfy the new requests. This attribute need not be true if it is known that there is only one credential used by the applications and therefore the pool has homogeneous connections.

max-connection-usage-count

0

(optional) Specifies the number of times a connections is reused by the pool, after which it is closed. A zero value disables this feature. By limiting the maximum number of times a connection can be reused, you can avoid statement leaks if the application does not close statements. 

sql-trace-listeners

none 

(optional) Specifies that SQL statements executed by applications need to be traced. Helps administrators analyze the statements. Expects as a value a comma-separated list of listener implementation class names. Enables easy filtering of log messages for the SQL statements. SQL trace listeners must implement the org.glassfish.api.jdbc.SQLTraceListener interface.

statement-cache-size

0

(optional) Specifies the number of statements to be cached using the lru (Least Recently Used) caching mechanism. The default value of 0 disables statement caching.

pooling

true

(optional) If false, disables connection pooling.

wrap-jdbc-objects

true

(optional) If true, wrapped JDBC objects are returned for Statement, PreparedStatement, CallableStatement, ResultSet, and DatabaseMetaData.

This option ensures that Statement.getConnection() is the same as DataSource.getConnection(). Therefore, this option should be true when both Statement.getConnection() and DataSource.getConnection() are done.

Properties

Most JDBC drivers allow use of standard property lists to specify the user, password, and other resource configuration information. Although properties are optional with respect to the GlassFish Server, some properties might be necessary for most databases. For details, see the JDBC 4.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.

Changing JDBC driver properties requires a server restart.

Table 1–80 jdbc-connection-pool Properties

Property 

Description 

user

Specifies the user name for connecting to the database. 

password

Specifies the password for connecting to the database. 

databaseName

Specifies the database for this connection pool. 

serverName

Specifies the database server for this connection pool. 

port

Specifies the port on which the database server listens for requests. 

networkProtocol

Specifies the communication protocol. 

roleName

Specifies the initial SQL role name. 

datasourceName

Specifies an underlying XADataSource, or a ConnectionPoolDataSource if connection pooling is done.

description

Specifies a text description. 

url

Specifies the URL for this connection pool. Although this is not a standard property, it is commonly used. 

prefer-validate-over-recreate

Specifies that validating idle connections is preferable to closing them. This property has no effect on non-idle connections. If set to true, idle connections are validated during pool resizing, and only those found to be invalid are destroyed and recreated. If false, all idle connections are destroyed and recreated during pool resizing. The default is false.

LazyConnectionEnlistment

Deprecated. Use the equivalent attribute. 

LazyConnectionAssociation

Deprecated. Use the equivalent attribute. 

AssociateWithThread

Deprecated. Use the equivalent attribute. 

MatchConnections

Deprecated. Use the equivalent attribute. 

jdbc-resource

Defines a JDBC (javax.sql.DataSource) resource.

Superelements

resources

Subelements

The following table describes subelements for the jdbc-resource element.

Table 1–81 jdbc-resource Subelements

Element 

Required 

Description 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the jdbc-resource element.

Table 1–82 jdbc-resource Attributes

Attribute 

Default 

Description 

jndi-name

none 

Specifies the JNDI name for the resource. 

description

none 

(optional) Specifies a text description of this element. 

pool-name

none 

Specifies the name of the associated jdbc-connection-pool.

object-type

user

(optional) Defines the type of the resource. Allowed values are: 

  • system-all - A system resource for all server instances and the domain application server.

  • system-admin - A system resource only for the domain application server.

  • system-instance - A system resource for all server instances only.

  • user - A user resource.

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

Superelements

jms-service

Subelements

The following table describes subelements for the jms-host element.

Table 1–83 jms-host Subelements

Element 

Required 

Description 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the jms-host element.

Table 1–84 jms-host Attributes

Attribute 

Default 

Description 

name

none 

Specifies the name of the JMS host. 

host

machine-name

(optional) Specifies the host name of the JMS host. 

port

7676

(optional) Specifies the port number used by the JMS provider. 

admin-user-name

admin

(optional) Specifies the administrator user name for the JMS provider. 

admin-password

admin

(optional) Specifies the administrator password for the JMS provider. 

jms-service

Configures the built-in Java Message Service (JMS) that is managed by the GlassFish Server.

Superelements

config

Subelements

The following table describes subelements for the jms-service element.

Table 1–85 jms-service Subelements

Element 

Required 

Description 

jms-host

zero or more 

Specifies a host. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the jms-service element.

Table 1–86 jms-service Attributes

Attribute 

Default 

Description 

init-timeout-in-seconds

60

(optional) Specifies the amount of time the server instance waits at startup for its configured default JMS host to respond. If there is no response, startup is aborted. If set to 0, the server instance waits indefinitely.

type

EMBEDDED

Specifies the type of JMS service: 

  • EMBEDDED means the JMS provider is started in the same JVM machine as the GlassFish Server, and the networking stack is bypassed.

    Lazy initialization starts the default embedded broker on the first access of JMS services rather than at GlassFish Server startup.

  • LOCAL means the JMS provider is started along with the GlassFish Server.

    The LOCAL setting implicitly sets up a 1:1 relationship between a GlassFish Server instance and a Message Queue broker.

  • REMOTE means the JMS provider is remote and is not started by the GlassFish Server.

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 GlassFish Server startup.

reconnect-interval-in-seconds

5

(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. The JMS service automatically tries to reconnect to the JMS provider when the connection is broken.

When the connection is broken, depending on the message processing stage, the onMessage method might not be able to complete successfully or the transaction might be rolled back due to a JMS exception. When the JMS service reestablishes the connection, JMS message redelivery semantics apply.

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.

Table 1–87 jms-service Properties

Property 

Default 

Description 

instance-name

imqbroker

Specifies the full GlassFish Message Queue broker instance name.

instance-name-suffix

none 

Specifies a suffix to add to the full Message Queue broker instance name. The suffix is separated from the instance name by an underscore character (_). For example, if the instance name is imqbroker, appending the suffix xyz changes the instance name to imqbroker_xyz.

append-version

false

If true, appends the major and minor version numbers, preceded by underscore characters (_), to the full Message Queue broker instance name. For example, if the instance name is imqbroker , appending the version numbers changes the instance name to imqbroker_8_0.

user-name

guest

Specifies the user name for creating the JMS connection. Needed only if the default username/password of guest/guest is not available in the broker. 

password

guest

Specifies the password for creating the JMS connection. Needed only if the default username/password of guest/guest is not available in the broker. 

jmx-connector

Configures a JSR 160/255 compliant remote JMX connector, which handles the JMX communication between the domain administration server, the node agents, and the remote server instances. This JMX connector also handles JMX communication between an external management client and the domain administration server.

Only the system JMX connector is started by the server processes at startup. Do not configure additional JMX connectors.

Superelements

admin-service

Subelements

The following table describes subelements for the jmx-connector element.

Table 1–88 jmx-connector Subelements

Element 

Required 

Description 

ssl

zero or one 

Defines SSL parameters. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the jmx-connector element.

Table 1–89 jmx-connector Attributes

Attribute 

Default 

Description 

name

none 

Specifies the name of the connector used by the designated system JMX connector for JMX communication between server instances. Do not modify this name. 

protocol

rmi_jrmp

(optional) Specifies the protocol that this JMX connector supports. The only supported protocol is rmi_jrmp. Do not modify this value.

address

0.0.0.0

Specifies the IP address of the naming service where the JMX connector server stub is registered. This is not the port of the server socket that does the actual JMX communication. This is the address of the network interface where the RMI registry is started. If your system has multiple network interfaces, modify this value so that only a particular interface is selected. 

port

8686

Specifies the port number on with the naming service (RMI registry) listens for RMI client connections. The only use of this naming service is to download the RMI stubs. If the default port is occupied, a free port is used. Legal values are 1 - 65535. On UNIX, creating sockets that listen on ports 1 - 1024 requires superuser privileges.

auth-realm-name

admin-realm

Specifies the name of an auth-realm subelement of the security-service element for the server instance that is running this JMX connector's server end. Note that this is a dedicated administration security realm.

security-enabled

false

(optional) Determines whether JMX communication is encrypted.  

enabled

true

(optional) Enables the JMX connector. Do not modify this value. 

jruby-container

Configures the JRuby container. This element is present only if at least one JRuby application is deployed.

Superelements

config

Subelements

The following table describes subelements for the jruby-container element.

Table 1–90 jruby-container Subelements

Element 

Required 

Description 

jruby-runtime-pool

only one 

Configures the JRuby runtime pool. 

Attributes

The following table describes attributes for the jruby-container element.

Table 1–91 jruby-container Attributes

Attribute 

Default 

Description 

jruby-home

as-install/jruby

Specifies the directory where JRuby itself (not the GlassFish Server JRuby container) is installed. Overridden by the jruby.home property of application if defined.

jruby-runtime-pool

Configures the JRuby runtime pool. This element is present only if at least one JRuby application is deployed.

Superelements

jruby-container

Subelements

none

Attributes

The following table describes attributes for the jruby-runtime-pool element.

Table 1–92 jruby-runtime-pool Attributes

Attribute 

Default 

Description 

jruby-runtime

1

Specifies the initial number of JRuby runtimes to start. Must be greater than zero, at least jruby-runtime-min, and jruby-runtime-max or less. Overridden by the jruby.runtime property of application if defined.

jruby-runtime-min

1

Specifies the minimum number of JRuby runtimes in the pool. Must be greater than zero, jruby-runtime or less, and jruby-runtime-max or less. Overridden by the jruby.runtime.min property of application if defined.

jruby-runtime-max

1

Specifies the maximum number of JRuby runtimes in the pool. Must be greater than zero, at least jruby-runtime-min and at least jruby-runtime. Overridden by the jruby.runtime.max property of application if defined.

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/javase/technologies/hotspot/vmoptions.jsp.

Superelements

java-config, profiler

Subelements

none - contains data

K

keep-alive

This element is not supported. If this element is present in the domain.xml file, its attributes are remapped to other elements and then it is deleted. For remapping details, see the Attributes table for this element.

Superelements

http-service

Subelements

none

Attributes

The following table describes attributes for the keep-alive element.

Table 1–93 keep-alive Attributes

Attribute 

Default 

Description 

thread-count

1

Not implemented. Do not use. 

max-connections

250

Remapped to the max-connections attribute of an http element.

timeout-in-seconds

30

Remapped to the timeout-seconds attribute of an http element.

L

lifecycle-module

This element is deprecated. Use an application element instead.

Specifies a deployed lifecycle module. For more information about lifecycle modules, see the Oracle GlassFish Server 3.0.1 Application Development Guide.

Superelements

applications

Subelements

The following table describes subelements for the lifecycle-module element.

Table 1–94 lifecycle-module Subelements

Element 

Required 

Description 

description

zero or one 

Contains a text description of this element. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the lifecycle-module element.

Table 1–95 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 domain 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. 

object-type

user

(optional) Defines the type of the resource. For a lifecycle module, the only allowed value is user.

enabled

true

(optional) Determines whether the lifecycle module is enabled. 

log-service

Configures the server log file, which stores messages from the default virtual server. Messages from other configured virtual servers also go here, unless the log-file or access-log attribute is explicitly specified in the virtual-server element. The default name is server.log.

Other log files are configured by other elements:

Superelements

config

Subelements

The following table describes subelements for the log-service element.

Table 1–96 log-service Subelements

Element 

Required 

Description 

module-log-levels

zero or one 

Specifies log levels. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the log-service element.

Table 1–97 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 to produce and manage logs.

log-handler

java.util.logging.ConsoleHandler

(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) Deprecated and ignored. 

log-rotation-limit-in-bytes

2000000

(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. If the value is greater than zero, log-rotation-timelimit-in-minutes takes precedence over log-rotation-limit-in-bytes .

alarms

false

(optional) If true, displays alarms for module-log-levels values of WARNING or SEVERE.

 

retain-error-statistics-for-hours

0

(optional) Specifies the number of most recent hours for which error statistics are retained in memory. The default and minimum value is 5 hours. The maximum value allowed is 500 hours. Larger values incur additional memory overhead.

Properties

The following table describes properties for the log-service element.

Table 1–98 log-service Properties

Attribute 

Default 

Description 

max-queue-size

5000

Specifies the number of entries the log queue holds. When the log queue is full, the system blocks until a record is written to the log file. Changing this property requires a server restart. 

flush-frequency

1

Specifies the maximum number of messages written from the log queue to the log file at once. 

M

mail-resource

Defines a JavaMail (javax.mail.Session) resource.

Superelements

resources

Subelements

The following table describes subelements for the mail-resource element.

Table 1–99 mail-resource Subelements

Element 

Required 

Description 

description

zero or one 

Contains a text description of this element. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the mail-resource element.

Table 1–100 mail-resource Attributes

Attribute 

Default 

Description 

jndi-name

none 

Specifies the JNDI name for the resource. 

store-protocol

imap

(optional) Specifies the storage protocol service, which connects to a mail server, retrieves messages, and saves messages in folder(s). Allowed values are imap, pop3, imaps, and pop3s .

store-protocol-class

com.sun.mail.imap.IMAPStore

(optional) Specifies the service provider implementation class for storage. Allowed values are: 

com.sun.mail.imap.IMAPStore

com.sun.mail.pop3.POP3Store

com.sun.mail.imap.IMAPSSLStore

com.sun.mail.pop3.POP3SSLStore

transport-protocol

smtp

(optional) Specifies the transport protocol service, which sends messages. Allowed values are smtp and smtps.

transport-protocol-class

com.sun.mail.smtp.SMTPTransport

(optional) Specifies the service provider implementation class for transport. Allowed values are: 

com.sun.mail.smtp.SMTPTransport

com.sun.mail.smtp.SMTPSSLTransport

host

none 

The mail server host name. 

user

none 

The mail server user name. 

from

none 

The email address the mail server uses to indicate the message sender. 

debug

false

(optional) Determines whether debugging for this resource is enabled. 

object-type

user

(optional) Defines the type of the resource. Allowed values are: 

  • system-all - A system resource for all server instances and the domain application server.

  • system-admin - A system resource only for the domain application server.

  • system-instance - A system resource for all server instances only.

  • user - A user resource.

enabled

true

(optional) Determines whether this resource is enabled at runtime. 

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. The GlassFish 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");

For more information about JavaMail properties, see JavaMail API Documentation.

manager-properties

Specifies session manager properties.

Superelements

session-manager

Subelements

The following table describes subelements for the manager-properties element.

Table 1–101 manager-properties Subelements

Element 

Required 

Description 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the manager-properties element.

Table 1–102 manager-properties Attributes

Attribute 

Default 

Description 

session-file-name

none; state is not preserved across restarts 

(optional) Specifies the absolute or relative path to the directory in which the session state is preserved between application restarts, if preserving the state is possible. A relative path is relative to the temporary directory for this web application.  

To disable this behavior and not preserve the session state, specify an empty string as the value of this attribute. 

reap-interval-in-seconds

60

(optional) Specifies the time between checks for expired sessions. 

If the persistence-frequency attribute of the web-container-availability element is set to time-based, active sessions are stored at this interval.

Set this value lower than the frequency at which session data changes. For example, this value should be as low as possible (1 second) for a hit counter servlet on a frequently accessed web site, or you could lose the last few hits each time you restart the server.

max-sessions

-1

(optional) Specifies the maximum number of sessions that can be in cache, or -1 for no limit. After this, an attempt to create a new session causes an IllegalStateException to be thrown.

session-id-generator-classname

internal class generator 

(optional) Not implemented. 

mdb-container

Configures the message-driven bean (MDB) container.

Superelements

config

Subelements

The following table describes subelements for the mdb-container element.

Table 1–103 mdb-container Subelements

Element 

Required 

Description 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the mdb-container element.

Table 1–104 mdb-container Attributes

Attribute 

Default 

Description 

steady-pool-size

10

(optional) Specifies the initial and minimum number of beans maintained in the pool. 

pool-resize-quantity

2

(optional) Specifies the number of beans to be removed when the idle-timeout-in-seconds timer expires. A cleaner thread removes any unused instances.

Must be 0 or greater and less than max-pool-size . The pool is not resized below the steady-pool-size.

max-pool-size

60

(optional) Specifies the maximum number of beans that can be created to satisfy client requests. 

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 bean is destroyed. A value of 0 means a bean can remain idle indefinitely.

Properties

The following table describes properties for the mdb-container element.

Table 1–105 mdb-container Properties

Property 

Default 

Description 

cmt-max-runtime-exceptions

1

Specifies the maximum number of RuntimeException occurrences allowed from a message-driven bean’s onMessage method when container-managed transactions are used. Deprecated.

message-security-config

Specifies configurations for message security providers.

Superelements

security-service

Subelements

The following table describes subelements for the message-security-config element.

Table 1–106 message-security-config Subelements

Element 

Required 

Description 

provider-config

one or more 

Specifies a configuration for one message security provider. 

Attributes

The following table describes attributes for the message-security-config element.

Table 1–107 message-security-config Attributes

Attribute 

Default 

Description 

auth-layer

HttpServlet

Specifies the message layer at which authentication is performed. The value must be SOAP or HttpServlet.

default-provider

none 

(optional) Specifies the server provider that is invoked for any application not bound to a specific server provider. 

default-client-provider

none 

(optional) Specifies the client provider that is invoked for any application not bound to a specific client provider. 

module

Defines a stand-alone module or a component of a Java EE application.

An engine runs a sniffer during deployment, which is responsible for identifying a type of deployment artifact (such as a WAR file) and setting up the associated container (such as the web container). Multiple engines, each with its own sniffer, can be associated with a given module.

Superelements

application

Subelements

The following table describes subelements for the module element.

Table 1–108 module Subelements

Element 

Required 

Description 

engine

one or more 

Specifies an engine. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the module element.

Table 1–109 module Attributes

Attribute 

Default 

Description 

name

none 

The name of the module. 

module-log-levels

Controls the level of messages logged by server subsystems to the server log. Allowed values (levels) 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.

Superelements

log-service

Subelements

The following table describes subelements for the module-log-levels element.

Table 1–110 module-log-levels Subelements

Element 

Required 

Description 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the module-log-levels element. The attribute names are the names of the GlassFish Server system loggers.

Table 1–111 module-log-levels Attributes

Attribute 

Default 

Description 

root

INFO

(optional) Specifies the default level of messages logged by the entire GlassFish Server installation. 

server

INFO

(optional) Specifies the default level of messages logged by the server instance. 

ejb-container

INFO

(optional) Specifies the level of messages logged by the EJB container. 

cmp-container

INFO

(optional) Specifies the level of messages logged by the CMP subsystem of the EJB container. 

mdb-container

INFO

(optional) Specifies the level of messages logged by the MDB container. 

web-container

INFO

(optional) Specifies the level of messages logged by the web container. 

classloader

INFO

(optional) Specifies the level of messages logged by the classloader hierarchy. 

configuration

INFO

(optional) Specifies the level of messages logged by the configuration subsystem. 

naming

INFO

(optional) Specifies the level of messages logged by the naming subsystem. 

security

INFO

(optional) Specifies the level of messages logged by the security subsystem. 

jts

INFO

(optional) Specifies the level of messages logged by the Java Transaction Service. 

jta

INFO

(optional) Specifies the level of messages logged by the Java Transaction API. 

admin

INFO

(optional) Specifies the level of messages logged by the Administration Console subsystem. 

deployment

INFO

(optional) Specifies the level of messages logged by the deployment subsystem. 

verifier

INFO

(optional) Specifies the level of messages logged by the deployment descriptor verifier. 

jaxr

INFO

(optional) Specifies the level of messages logged by the XML registry. 

jaxrpc

INFO

(optional) Specifies the level of messages logged by the XML RPC module. 

saaj

INFO

(optional) Specifies the level of messages logged by the SOAP with Attachments API for Java module. 

corba

INFO

(optional) Specifies the level of messages logged by the ORB. 

javamail

INFO

(optional) Specifies the level of messages logged by the JavaMail subsystem. 

jms

INFO

(optional) Specifies the level of messages logged by the Java Message Service. 

connector

INFO

(optional) Specifies the level of messages logged by the connector subsystem. 

jdo

INFO

(optional) Specifies the level of messages logged by the Java Data Objects module. 

cmp

INFO

(optional) Specifies the level of messages logged by the CMP subsystem. 

util

INFO

(optional) Specifies the level of messages logged by the utility subsystem. 

resource-adapter

INFO

(optional) Specifies the level of messages logged by the resource adapter subsystem. 

synchronization

INFO

(optional) Specifies the level of messages logged by the synchronization subsystem. 

node-agent

INFO

(optional) Specifies the level of messages logged by the node agent subsystem. 

self-management

INFO

(optional) Specifies the level of messages logged by the self-management (management rules) subsystem. 

group-management-service

INFO

(optional) Specifies the level of messages logged by the Group Management Service. 

management-event

INFO

(optional) Specifies the level of messages logged by the self-management event subsystem. 

module-monitoring-levels

Controls the level of monitoring of server subsystems. Allowed values of each subsystem attribute are LOW, HIGH, and OFF.

Superelements

monitoring-service

Subelements

The following table describes subelements for the module-monitoring-levels element.

Table 1–112 module-monitoring-levels Subelements

Element 

Required 

Description 

property

zero or more 

Specifies a property or a variable. 

Attributes

Table 1–113 module-monitoring-levels Attributes

Attribute 

Default 

Description 

thread-pool

OFF

(optional) Specifies the level of monitoring of the thread pool subsystem. 

orb

OFF

(optional) Specifies the level of monitoring of the ORB. 

ejb-container

OFF

(optional) Specifies the level of monitoring of the EJB container. 

web-container

OFF

(optional) Specifies the level of monitoring of the web container. 

transaction-service

OFF

(optional) Specifies the level of monitoring of the transaction service. 

http-service

OFF

(optional) Specifies the level of monitoring of the HTTP service. 

jdbc-connection-pool

OFF

(optional) Specifies the level of monitoring of the JDBC connection pool subsystem. 

connector-connection-pool

OFF

(optional) Specifies the level of monitoring of the connector connection pool subsystem. 

connector-service

OFF

(optional) Specifies the level of monitoring of the connector service. 

jms-service

OFF

(optional) Specifies the level of monitoring of the JMS service. 

jvm

OFF

(optional) Specifies the level of monitoring of the JVM subsystem. 

monitoring-service

Configures the monitoring service.

Superelements

config

Subelements

The following table describes subelements for the monitoring-service element.

Table 1–114 monitoring-service Subelements

Element 

Required 

Description 

module-monitoring-levels

zero or one 

Controls the level of monitoring of server subsystems. 

property

zero or more 

Specifies a property or a variable. 

N

network-config

Configures the communication network for the GlassFish Server. The network configuration includes most of the features that were in the HTTP Service in previous GlassFish Server releases. HTTP Service elements that are no longer supported are converted to network configuration elements. For additional information, see http-service.

Superelements

config

Subelements

The following table describes subelements for the network-config element.

Table 1–115 network-config Subelements

Element 

Required 

Description 

network-listeners

only one 

Contains network listeners. 

protocols

only one 

Contains protocols. 

transports

only one 

Contains transports. 

network-listener

Configures a network listener.

When you first install the GlassFish Server, three network-listener elements exist by default, with name values of admin-listener, http-listener1, and http-listener2. The http-listener2, which is set up with SSL, is disabled by default.


Note –

Network listeners are affected by properties of http-service.


Superelements

network-listeners

Subelements

none

Attributes

The following table describes attributes for the network-listener element.

Table 1–116 network-listener Attributes

Attribute 

Default 

Description 

name

none 

The unique listener name. A network-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.

enabled

true

(optional) Determines whether the listener is active. If set to false, any attempts to connect to the listener result in a socket exception (java.net.ConnectException).

In GlassFish Server versions prior to 9.1, a listener whose enabled attribute was set to false returned a 404 response code for any requests sent to it. To achieve this behavior in the current GlassFish Server version, set the listener's enabled attribute to true, and set every associated virtual server's state to off. A virtual-server lists its associated listeners in its network-listeners attribute.

jk-enabled

false

(optional) If true, enables mod_jk support for this listener.

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.

protocol

none 

Specifies the name of the protocol associated with this network listener. Although this attribute is required, a protocol is automatically created with the same name as the network listener when you use the asadmin create-http-listener command to create a network listener.

thread-pool

none 

(Optional) Specifies the name of the thread-pool associated with this network listener.

transport

none 

Specifies the name of the transport associated with this network listener. Although this attribute is required, the default transport is used when you use the asadmin create-http-listener command to create a network listener.

network-listeners

Contains network listeners.

Superelements

network-config

Subelements

The following table describes subelements for the network-listeners element.

Table 1–117 network-listeners Subelements

Element 

Required 

Description 

network-listener

one or more 

Configures a network listener. 

O

orb

Configures the ORB.

To enable SSL for outbound connections, include an ssl-client-config subelement in the parent iiop-service element.

Superelements

iiop-service

Subelements

The following table describes subelements for the orb element.

Table 1–118 orb Subelements

Element 

Required 

Description 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the orb element.

Table 1–119 orb Attributes

Attribute 

Default 

Description 

use-thread-pool-ids

none 

Specifies a comma-separated list of name 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. 

P

param-name

Contains a context parameter name.

Superelements

context-param

Subelements

none - contains data

param-value

Contains a context parameter value.

Superelements

context-param

Subelements

none - contains data

port-unification

Configures port unification.

Superelements

protocol

Subelements

The following table describes subelements for the port-unification element.

Table 1–120 port-unification Subelements

Element 

Required 

Description 

protocol-finder

zero or one 

Configures the protocol finder. 

Attributes

The following table describes attributes for the port-unification element.

Table 1–121 port-unification Attributes

Attribute 

Default 

Description 

name

none 

Specifies a unique name for the port-unification.

classname

none 

Specifies the class name of the port-unification implementation.

principal

Contains the principal of the servlet or EJB client.

Superelements

security-map

Subelements

none - contains data

principal-map

Maps an EIS principal to a principal defined in the GlassFish Server domain.

Superelements

work-security-map

Subelements

none

Attributes

The following table describes attributes for the principal-map element.

Table 1–122 principal-map Attributes

Attribute 

Default 

Description 

eis-principal

none 

Specifies an EIS principal. 

mapped-principal

none 

Specifies a principal defined in the GlassFish Server domain. 

profiler

Configures a profiler for use with the GlassFish Server. For more information about profilers, see the Oracle GlassFish Server 3.0.1 Application Development Guide.

Superelements

java-config

Subelements

The following table describes subelements for the profiler element.

Table 1–123 profiler Subelements

Element 

Required 

Description 

jvm-options

zero or more 

Contains profiler-specific JVM command line options. 

property

zero or more 

Specifies a property or a variable. 


Note –

Subelements of a profiler element can occur in any order.


Attributes

The following table describes attributes for the profiler element.

Table 1–124 profiler Attributes

Attribute 

Default 

Description 

name

none 

Specifies the name of the profiler. 

classpath

none 

(optional) Specifies the classpath for the profiler. 

native-library-path

none 

(optional) Specifies the native library path for the profiler. 

enabled 

true

(optional) Determines whether the profiler is enabled. 

property

Specifies a property. A property adds configuration information to its parent element that is one or both of the following:

Superelements

admin-object-resource, admin-service, appclient-module, application, audit-module, auth-realm, config, connector-connection-pool, connector-module, connector-resource, custom-resource, das-config, domain, ejb-container, ejb-module, ejb-timer-service, engine, extension-module, external-jndi-resource, http-service, iiop-listener, j2ee-application, jacc-provider, java-config, jdbc-connection-pool, jdbc-resource, jms-host, jms-service, jmx-connector, lifecycle-module, log-service, mail-resource, manager-properties, mdb-container, module-log-levels, module-monitoring-levels, monitoring-service, orb, profiler, provider-config, resource-adapter-config, security-service, server, session-properties, store-properties, thread-pool, transaction-service, virtual-server, web-container, , web-module

Subelements

none

Attributes

The following table describes attributes for the property element.

Table 1–125 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. 

description

none 

(optional) Specifies a text description of this element. 

protocol

Configures a network protocol. A protocol can be defined in one of the following ways according to its subelements:

Superelements

protocols

Subelements

The following table describes subelements for the protocol element.

Table 1–126 protocol Subelements

Element 

Required 

Description 

http

zero or one 

Configures HTTP parameters. 

port-unification

zero or one 

Configures port unification. 

protocol-chain-instance-handler

zero or one 

Configures a protocol chain instance handler. 

protocol-filter

zero or one 

Configures a protocol filter. 

ssl

zero or one 

Defines SSL parameters. 

Attributes

The following table describes attributes for the protocol element.

Table 1–127 protocol Attributes

Attribute 

Default 

Description 

name

none 

Specifies a unique name for the protocol. 

security-enabled

false

(optional) Determines whether the network-listener that references this protocol runs SSL. To turn SSL2 or SSL3 on or off and set ciphers, use an ssl subelement.

protocol-chain

Configures a protocol chain.

Superelements

protocol-chain-instance-handler

Subelements

none

Attributes

The following table describes attributes for the protocol-chain element.

Table 1–128 protocol-chain Attributes

Attribute 

Default 

Description 

name

none 

Specifies a unique name for the protocol chain. 

classname

none 

Specifies the class name of the protocol chain implementation. 

type

STATELESS

Specifies the type of protocol chain. 

protocol-chain-instance-handler

Configures a protocol chain instance handler.

Superelements

protocol

Subelements

The following table describes subelements for the protocol-chain-instance-handler element.

Table 1–129 protocol-chain-instance-handler Subelements

Element 

Required 

Description 

protocol-chain

one or more 

Configures a protocol chain. 

Attributes

The following table describes attributes for the protocol-chain-instance-handler element.

Table 1–130 protocol-chain-instance-handler Attributes

Attribute 

Default 

Description 

name

none 

Specifies a unique name for the protocol chain instance handler. 

classname

none 

Specifies the class name of the protocol chain instance handler implementation. 

protocol-filter

Configures a protocol filter.

Superelements

protocol

Subelements

none

Attributes

The following table describes attributes for the protocol-filter element.

Table 1–131 protocol-filter Attributes

Attribute 

Default 

Description 

name

none 

Specifies a unique name for the protocol filter. 

classname

none 

Specifies the class name of the protocol filter implementation. 

protocol-finder

Configures a protocol finder.

Superelements

port-unification

Subelements

none

Attributes

The following table describes attributes for the protocol-finder element.

Table 1–132 protocol-finder Attributes

Attribute 

Default 

Description 

name

none 

Specifies a unique name for the protocol finder. 

classname

none 

Specifies the class name of the protocol finder implementation. 

protocol

none 

Specifies the name of the protocol associated with this protocol finder.

 

protocols

Contains protocols.

Superelements

network-config

Subelements

The following table describes subelements for the protocols element.

Table 1–133 protocols Subelements

Element 

Required 

Description 

protocol

one or more 

Configures a protocol. 

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.

Superelements

message-security-config

Subelements

The following table describes subelements for the provider-config element.

Table 1–134 provider-config Subelements

Element 

Required 

Description 

request-policy

zero or one 

Defines the authentication policy requirements of the authentication provider’s request processing. 

response-policy

zero or one 

Defines the authentication policy requirements of the authentication provider’s response processing. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the provider-config element.

Table 1–135 provider-config Attributes

Attribute 

Default 

Description 

provider-id

none 

Specifies a unique identifier for this provider-config element.

provider-type

none 

Specifies whether the provider is a client, server, or client-server authentication provider.

class-name

none 

Specifies the Java implementation class of the provider. Client authentication providers must implement the com.sun.enterprise.security.jauth.ClientAuthModule interface. Server authentication providers must implement the com.sun.enterprise.security.jauth.ServerAuthModule interface. Client-server providers must implement both interfaces.

Properties

The following table describes properties for the provider-config element.

Table 1–136 provider-config Properties

Property 

Default 

Description 

security.config

domain-dir/config/wss-server-config-1.0.xml

Specifies the location of the message security configuration file. To point to a configuration file in the domain-dir/config directory, use the system property ${com.sun.aas.instanceRoot}/config/, for example:

${com.sun.aas.instanceRoot}/config/wss-server-config-1.0.xml

See system-property.

debug

false

If true, enables dumping of server provider debug messages to the server log.

dynamic.username.password

false

If true, signals the provider runtime to collect the user name and password from the CallbackHandler for each request. If false, the user name and password for wsse:UsernameToken(s) is collected once, during module initialization. This property is only applicable for a ClientAuthModule.

encryption.key.alias

s1as

Specifies the encryption key used by the provider. The key is identified by its keystore alias.

signature.key.alias

s1as

Specifies the signature key used by the provider. The key is identified by its keystore alias.

R

registry-location

This element is deprecated. Web services are implemented in the engine element.

Specifies the registry where web service endpoint artifacts are published.

Superelements

web-service-endpoint

Subelements

none

Attributes

The following table describes attributes for the registry-location element.

Table 1–137 registry-location Attributes

Attribute 

Default 

Description 

connector-resource-jndi-name

none 

Specifies the jndi-name of the connector-resource used as the registry.

request-policy

Defines the authentication policy requirements of the authentication provider’s request processing.

Superelements

provider-config

Subelements

none

Attributes

The following table describes attributes for the request-policy element.

Table 1–138 request-policy Attributes

Attribute 

Default 

Description 

auth-source

none 

Specifies the type of required authentication, either sender (user name and password) or content (digital signature).

auth-recipient

none 

Specifies whether recipient authentication occurs before or after content authentication. Allowed values are before-content and after-content.

request-processing

This element is not supported. If this element is present in the domain.xml file, its attributes are remapped to other elements and then it is deleted. For remapping details, see the Attributes table for this element.

Superelements

http-service

Subelements

none

Attributes

The following table describes attributes for the request-processing element.

Table 1–139 request-processing Attributes

Attribute 

Default 

Description 

thread-count

20

Remapped to the max-thread-pool-size attribute of a thread-pool element.

initial-thread-count

2

Remapped to the min-thread-pool-size attribute of a thread-pool element.

thread-increment

1

Not implemented. Do not use. 

request-timeout-in-seconds

30

Remapped to the request-timeout-seconds attribute of an http element.

header-buffer-length-in-bytes

8192

Remapped to the header-buffer-length-bytes attribute of an http element.

resource-adapter-config

Defines a connector (resource adapter) configuration. Stores configuration information for the resource adapter JavaBean in property subelements.

Superelements

resources

Subelements

The following table describes subelements for the resource-adapter-config element.

Table 1–140 resource-adapter-config Subelements

Element 

Required 

Description 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the resource-adapter-config element.

Table 1–141 resource-adapter-config Attributes

Attribute 

Default 

Description 

name

none 

(optional) Not used. See resource-adapter-name.

thread-pool-ids

none 

(optional) Specifies a comma-separated list of the name attributes of thread-pool elements.

object-type

user

(optional) Defines the type of the resource. Allowed values are: 

  • system-all - A system resource for all server instances and the domain application server.

  • system-admin - A system resource only for the domain application server.

  • system-instance - A system resource for all server instances only.

  • user - A user resource.

resource-adapter-name

none 

Specifies the name attribute of a deployed connector application element. If the resource adapter is embedded in an application, then it is app_name#rar_name.

Properties

Properties of the resource-adapter-config element are the names of setter methods of the class referenced by the resourceadapter-class element in the ra.xml file, which defines the class name of the resource adapter JavaBean. Any properties defined here override the default values present in ra.xml.

resource-ref

References a resource deployed to the server.

Superelements

server

Subelements

none

Attributes

The following table describes attributes for the resource-ref element.

Table 1–142 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, admin-object-resourceresource-adapter-config, connector-connection-pool, or jdbc-connection-pool element.

resources

Contains configured resources, such as database connections, JavaMailTM sessions, and so on.


Note –

You must specify a Java Naming and Directory InterfaceTM (JNDI) name for each resource. To avoid collisions with names of other enterprise resources in JNDI, and to avoid portability problems, all names in a GlassFish Server application should begin with the string java:comp/env.


Superelements

domain

Subelements

The following table describes subelements for the resources element.

Table 1–143 resources Subelements

Element 

Required 

Description 

custom-resource

zero or more 

Defines a custom resource. 

external-jndi-resource

zero or more 

Defines a resource that resides in an external JNDI repository. 

jdbc-resource

zero or more 

Defines a JDBC (Java Database Connectivity) resource. 

mail-resource

zero or more 

Defines a JavaMail resource. 

admin-object-resource

zero or more 

Defines an administered object for an inbound resource adapter. 

connector-resource

zero or more 

Defines a connector (resource adapter) resource. 

resource-adapter-config

zero or more 

Defines a resource adapter configuration. 

jdbc-connection-pool

zero or more 

Defines the properties that are required for creating a JDBC connection pool. 

connector-connection-pool

zero or more 

Defines the properties that are required for creating a connector connection pool. 

work-security-map

zero or more 

Defines a work security map. 


Note –

Subelements of a resources element can occur in any order.


response-policy

Defines the authentication policy requirements of the authentication provider’s response processing.

Superelements

provider-config

Subelements

none

Attributes

The following table describes attributes for the response-policy element.

Table 1–144 response-policy Attributes

Attribute 

Default 

Description 

auth-source

none 

Specifies the type of required authentication, either sender (user name and password) or content (digital signature).

auth-recipient

none 

Specifies whether recipient authentication occurs before or after content authentication. Allowed values are before-content and after-content.

S

security-map

Maps the principal received during servlet or EJB authentication to the credentials accepted by the EIS. This mapping is optional. It is possible to map multiple GlassFish Server principals to the same back-end principal.

This is different from a work-security-map, which maps a principal associated with an incoming work instance to a principal in the GlassFish Server's security domain.

Superelements

connector-connection-pool

Subelements

The following table describes subelements for the security-map element.

Table 1–145 security-map Subelements

Element 

Required 

Description 

principal

one or more 

Contains the principal of the servlet or EJB client. 

user-group

one or more 

Contains the group to which the principal belongs. 

backend-principal

only one 

Specifies the user name and password required by the EIS. 

Attributes

The following table describes attributes for the security-map element.

Table 1–146 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 Java EE security service. For SSL configuration, see ssl. For connector module security, see security-map.

Superelements

config

Subelements

The following table describes subelements for the security-service element.

Table 1–147 security-service Subelements

Element 

Required 

Description 

auth-realm

one or more 

Defines a realm for authentication. 

jacc-provider

one or more 

Specifies a Java Authorization Contract for Containers (JACC) provider for pluggable authorization. 

audit-module

zero or more 

Specifies an optional plug-in module that implements audit capabilities. 

message-security-config

zero or more 

Specifies configurations for message security providers. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the security-service element.

Table 1–148 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

attribute is deprecated

(optional) Deprecated. Do not use. 

audit-enabled

false

(optional) If true, additional access logging is performed to provide audit information.

Audit information consists of: 

  • Authentication success and failure events

  • Servlet and EJB access grants and denials

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 space-separated list of audit provider modules used by the audit subsystem. The default value refers to the internal log-based audit module. 

activate-default-principal-to-role-mapping

false

(optional) Applies a default principal for role mapping to any application that does not have an application-specific mapping defined. Every role is mapped to an instance of a java.security.Principal implementation class defined by mapped-principal-class. This class has the same name as the role.

mapped-principal-class

none 

(optional) Customizes the java.security.Principal implementation class used when activate-default-principal-to-role-mapping is set to true.

selection-key-handler

Configures a selection key handler.

Superelements

transports

Subelements

none

Attributes

The following table describes attributes for the selection-key-handler element.

Table 1–149 selection-key-handler Attributes

Attribute 

Default 

Description 

name

none 

Specifies a unique name for the selection key handler. 

classname

none 

Specifies the class name of the selection key handler implementation. 

server

Defines a server instance, which is a Java EE compliant container. One server instance is specially designated as a domain administration server (DAS). The admin-service subelement of the config element referenced by a server's config-ref attribute determines whether the server is the DAS.


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.


Superelements

servers

Subelements

The following table describes subelements for the server element.

Table 1–150 server Subelements

Element 

Required 

Description 

application-ref

zero or more 

References an application or module deployed to the server instance. 

resource-ref

zero or more 

References a resource deployed to the server instance. 

system-property

zero or more 

Specifies a system property. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the server element.

Table 1–151 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.

servers

Contains server instances.

Superelements

domain

Subelements

The following table describes subelements for the servers element.

Table 1–152 servers Subelements

Element 

Required 

Description 

server

only one 

Defines a server instance. 

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.

Superelements

web-container

Subelements

The following table describes subelements for the session-config element.

Table 1–153 session-config Subelements

Element 

Required 

Description 

session-manager

zero or one 

Specifies session manager configuration information. 

session-properties

zero or one 

Specifies session properties. 

session-manager

Specifies session manager information.


Note –

The session manager interface is unstable. An unstable interface might be experimental or transitional, and hence might change incompatibly, be removed, or be replaced by a more stable interface in the next release.


Superelements

session-config

Subelements

The following table describes subelements for the session-manager element.

Table 1–154 session-manager Subelements

Element 

Required 

Description 

manager-properties

zero or one 

Specifies session manager properties. 

store-properties

zero or one 

Specifies session persistence (storage) properties. 

session-properties

Specifies session properties.

Superelements

session-config

Subelements

The following table describes subelements for the session-properties element.

Table 1–155 session-properties Subelements

Element 

Required 

Description 

property

zero or more 

Specifies a property or a variable. 

Attributes

Table 1–156 session-properties Attributes

Attribute 

Default 

Description 

timeout-in-seconds

1800

(optional) Specifies the default maximum inactive interval (in seconds) for all sessions created in this web module. If set to 0 or less, sessions in this web module never expire.

If a session-timeout element is specified in the web.xml file, the session-timeout value overrides any timeout-in-seconds value. If neither session-timeout nor timeout-in-seconds is specified, the timeout-in-seconds default is used.

Note that the session-timeout element in web.xml is specified in minutes, not seconds.

Properties

The following table describes properties for the session-properties element.

Table 1–157 session-properties Properties

Property 

Default 

Description 

enableCookies

true

Uses cookies for session tracking if set to true.

enableURLRewriting

true

Enables URL rewriting. This provides session tracking via URL rewriting when the browser does not accept cookies. You must also use an encodeURL or encodeRedirectURL call in the servlet or JavaServer PagesTM (JSPTM) page.

idLengthBytes

128

Specifies the number of bytes in this web module’s session ID. 

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.

The grandparent http-service element has properties that configure global SSL settings.

Superelements

protocol, http-listener, iiop-listener, jmx-connector, ssl-client-config

Subelements

none

Attributes

The following table describes attributes for the ssl element.

Table 1–158 ssl Attributes

Attribute 

Default 

Description 

cert-nickname

s1as

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 +SSL_RSA_WITH_RC4_128_MD5 . Allowed values are SSL_RSA_WITH_RC4_128_MD5, SSL_RSA_WITH_3DES_EDE_CBC_SHA, SSL_RSA_WITH_DES_CBC_SHA, SSL_RSA_EXPORT_WITH_RC4_40_MD5, SSL_RSA_WITH_NULL_MD5, SSL_RSA_WITH_RC4_128_SHA, and SSL_RSA_WITH_NULL_SHA. Values available in previous releases are supported for backward compatibility.

tls-enabled

true

(optional) Determines whether TLS is enabled. 

tls-rollback-enabled

true

(optional) Determines whether TLS rollback is enabled. TLS rollback should be enabled for Microsoft Internet Explorer 5.0 and 5.5. For more information, see theOracle GlassFish Server 3.0.1 Administration Guide.

client-auth-enabled

false

(optional) Determines whether SSL3 client authentication is performed on every request, independent of ACL-based access control.

crl-file

none 

(optional) Specifies the location of the Certificate Revocation List (CRL) file to consult during SSL client authentication. This can be an absolute or relative file path. If relative, it is resolved against domain-dir. If unspecified, CRL checking is disabled.

trust-algorithm

none  

(optional) Specifies the name of the trust management algorithm (for example, PKIX) to use for certification path validation.

trust-max-cert-length

5

(optional) Specifies the maximum number of non-self-issued intermediate certificates that can exist in a certification path. This property is considered only if trustAlgorithm is set to PKIX. A value of zero implies that the path can only contain a single certificate. A value of -1 implies that the path length is unconstrained (there is no maximum). Setting a value less than -1 causes an exception to be thrown.

key-store

none 

(optional) Specifies a key store.  

trust-store

none 

(optional) Specifies a trust store.  

ssl-client-config

Defines SSL parameters for the ORB when it makes outbound SSL connections and behaves as a client.

Superelements

iiop-service

Subelements

The following table describes subelements for the ssl-client-config element.

Table 1–159 ssl-client-config Subelements

Element 

Required 

Description 

ssl

only one 

Defines SSL parameters. 

store-properties

Specifies session persistence (storage) properties.

Superelements

session-manager

Subelements

The following table describes subelements for the store-properties element.

Table 1–160 store-properties Subelements

Element 

Required 

Description 

property

zero or more 

Specifies a property or a variable. 

Attributes

Table 1–161 store-properties Attributes

Attribute 

Default 

Description 

directory

domain-dir/generated/jsp/j2ee-apps/appname/appname_war

(optional) Specifies the absolute or relative pathname of the directory into which individual session files are written. A relative path is relative to the temporary work directory for this web application. 

reap-interval-in-seconds

60

(optional) Not implemented. Use the reap-interval-in-seconds attribute of the manager-properties element instead.

system-applications

Contains system applications. Do not delete or edit these applications.

Superelements

domain

Subelements

The following table describes subelements for the system-applications element.

Table 1–162 system-applications Subelements

Element 

Required 

Description 

application

zero or more 

Specifies an application. 

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 system-property. 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>

Superelements

config, domain, server

Subelements

none

Attributes

The following table describes attributes for the system-property element.

Table 1–163 system-property Attributes

Attribute 

Default 

Description 

name

none 

Specifies the name of the system property. 

value

none 

Specifies the value of the system property. 

description

none 

(optional) Specifies a text description of this element. 

Properties

The following table lists predefined system properties.

Table 1–164 Predefined System Properties

Property 

Default 

Description 

com.sun.aas.installRoot

depends on operating system 

Specifies the directory where the GlassFish 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 installation directory for the Java runtime. 

com.sun.aas.imqLib

depends on operating system 

Specifies the library directory for the GlassFish Message Queue software. 

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. 

com.sun.aas.derbyRoot

as-install/javadb

Specifies the directory where Java DB is installed. 

T

thread-pool

Defines a thread pool.

Superelements

thread-pools

Subelements

The following table describes subelements for the thread-pool element.

Table 1–165 thread-pool Subelements

Element 

Required 

Description 

property

zero or more 

Specifies a property or a variable. 

Attributes

Table 1–166 thread-pool Attributes

Attribute 

Default 

Description 

name

none 

Specifies the thread pool name. 

classname

com.sun.grizzly.http.StatsThreadPool

(Optional) Specifies the class name of the thread pool implementation. 

min-thread-pool-size

2

(optional) Specifies the minimum number of threads in the pool. These are created when the thread pool is instantiated. 

max-thread-pool-size

5

(optional) Specifies the maximum number of threads the pool can contain. To optimize this thread pool for use with an iiop-listener, set this value to 200.

idle-thread-timeout-seconds

900

(optional) Specifies the amount of time after which idle threads are removed from the pool. 

max-queue-size

4096

(optional) Specifies the maximum number of messages that can be queued until threads are available to process them for , network-listener or iiop-listener elements. A value of -1 specifies no limit.

thread-pools

Contains thread pools.

Superelements

config

Subelements

The following table describes subelements for the thread-pools element.

Table 1–167 thread-pools Subelements

Element 

Required 

Description 

thread-pool

one or more 

Defines a thread pool. 

transaction-service

Configures the Java Transaction Service (JTS).

Superelements

config

Subelements

The following table describes subelements for the transaction-service element.

Table 1–168 transaction-service Subelements

Element 

Required 

Description 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the transaction-service element.

Table 1–169 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 domain element

(optional) Specifies the parent directory of the transaction log directory instance-name/tx. The directory in which the transaction logs are kept must be writable by the user account under which the server runs. A relative path is relative to the log-root attribute of the domain element.

heuristic-decision

rollback

(optional) If the outcome of a distributed transaction cannot be determined because other participants are unreachable, 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: 

  • At the transaction recovery time, if resources are unreachable.

  • If there are any transient exceptions in the second phase of a two phase commit protocol.

    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

65536 (64 K)

(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 results in a larger transaction log file, but fewer keypoint operations and potentially better performance. A smaller value 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.

Table 1–170 transaction-service Properties

Property 

Default 

Description 

oracle-xa-recovery-workaround

true

If true, the Oracle XA Resource workaround is used in transaction recovery.

disable-distributed-transaction-logging

false

If true, disables transaction logging, which might improve performance.

If the automatic-recovery attribute is set to true , this property is ignored.

xaresource-txn-timeout

specific to the XAResource used

Changes the XAResource timeout. In some cases, the XAResource default timeout can cause transactions to be aborted, so it is desirable to change it.

pending-txn-cleanup-interval

none if this property is absent, 60 if this property is present but has no value

Specifies the interval, in seconds, at which an asynchronous thread checks for pending transactions and completes them. 

use-last-agent-optimization

true

If true, enables last agent optimization, which improves the throughput of transactions. If one non-XA resource is used with XA resources in the same transaction, the non XA resource is the last agent.

db-logging-resource

none 

Specifies the JNDI name of the JDBC resource for the database to which transactions are logged. For more information, see Chapter 15, Using the Transaction Service, in Oracle GlassFish Server 3.0.1 Application Development Guide.

xa-servername

host name on which the GlassFish Server runs 

Specifies the host name that the transaction service uses to identify transactions being managed by the installed GlassFish Server. This can sometimes be useful for recovering transactions from the log file that was created on a different host running the GlassFish Server. 

transformation-rule

This element is deprecated. Web services are implemented in the engine element.

Configures an eXtensible Stylesheet Language Transformation (XSLT) rule, which transforms a web service message.

Superelements

web-service-endpoint

Subelements

The following table describes subelements for the transformation-rule element.

Table 1–171 transformation-rule Subelements

Element 

Required 

Description 

description

zero or one 

Contains a text description of this element. 

Attributes

The following table describes attributes for the transformation-rule element.

Table 1–172 transformation-rule Attributes

Attribute 

Default 

Description 

name

none 

The name of the rule. 

enabled

true

(optional) Determines whether the rule is enabled. 

apply-to

request

(optional) Specifies whether the rule is applied to the request, the response, or both. Allowed values are: 

  • request - Transformations are applied to the request in the order specified.

  • response - Transformations are applied to the response in the order specified.

  • both - Transformations are applied to both the request and the response. The order is reversed for the response.

rule-file-location

domain-dir/generated/xml/app-or-module/xslt-file

A fully qualified or relative path to the rule file that performs the transformation. Only XSLT files are allowed. 

transport

Configures a transport. You can configure a TCP or UDP transport or provide a custom transport implementation.

Superelements

transports

Subelements

none

Attributes

The following table describes attributes for the transport element.

Table 1–173 transport Attributes

Attribute 

Default 

Description 

name

none 

Specifies a unique name for the transport. 

classname

com.sun.grizzly.TCPSelectorHandler

(Optional) Specifies the class name of the transport implementation. 

selection-key-handler

none 

(optional) Specifies the name of the selection-key-handler associated with this transport.

idle-key-timeout-seconds

30

(Optional) Specifies the idle key timeout. 

read-timeout-millis

30000 (30 seconds)

(optional) Specifies the amount of time the GlassFish Server waits during the header and body parsing phase. 

write-timeout-millis

30000 (30 seconds)

(optional) Specifies the amount of time the GlassFish Server waits before considering the remote client disconnected when writing the response. 

selector-poll-timeout-millis

1000 (1 second)

(optional) Specifies the time a NIO Selector blocks waiting for events (user requests). 

display-configuration

false

(optional) If true, flushes the internal network configuration to the server log. Useful for debugging, but reduces performance.

snoop-enabled

false

(optional) If true, writes request/response information to the server log. Useful for debugging, but reduces performance.

tcp-no-delay

false

(optional) If true, enables TCP_NODELAY (also called Nagle's algorithm).

max-connections-count

4096

(optional) Specifies the maximum number of pending connections on a network-listener that references this transport.

acceptor-threads

1

(optional) Specifies the number of processors in the machine. 

To set the number of request processing threads, use the max-thread-pool-size attribute of the thread-poolelement.

byte-buffer-type

HEAP

(optional) Specifies the type of the buffer to be provided for input streams created by a network-listener. Allowed values are HEAP and DIRECT.

buffer-size-bytes

8192

(optional) Specifies the size, in bytes, of the buffer to be provided for input streams created by a network-listener.

transports

Contains transports.

Superelements

network-config

Subelements

The following table describes subelements for the transports element.

Table 1–174 transports Subelements

Element 

Required 

Description 

selection-key-handler

zero or more 

Configures a selection key handler. 

transport

one or more 

Configures a transport. 

U

user-group

Contains the group to which the principal belongs.

Superelements

security-map

Subelements

none - contains data

V

virtual-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 GlassFish 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 GlassFish 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 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.

Superelements

http-service

Subelements

The following table describes subelements for the virtual-server element.

Table 1–175 virtual-server Subelements

Element 

Required 

Description 

http-access-log

zero or one 

Defines an access log file. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the virtual-server element.

Table 1–176 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) Remapped to the network-listeners attribute of this element.

network-listeners

none 

(optional) In a comma-separated list, references id attributes of network-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 element.

default-web-module

none 

(optional) References the name attribute of the default web application 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

${com.sun.aas.hostName}

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.

docroot

domain-dir/docroot

(optional) Specifies the document root for this virtual server. 

access-log

domain-dir/logs/access

(optional) Specifies the access log location. The file and directory in which the access log is kept must be writable by the user account under which the server runs. See the log-service description for details about logs.

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.

access-logging-enabled

inherit

If true, enables access logging for this virtual server. If false, disables access logging for this virtual server.

A true or false setting overrides the access-logging-enabled attribute setting of the http-service element. An inherit setting uses the access-logging-enabled attribute setting of the http-service element.

sso-enabled

inherit

If true, single sign-on is enabled for web applications on this virtual server that are configured for the same realm. If false, single sign-on is disabled for this virtual server, and users must authenticate separately to every application on the virtual server.

A true or false setting overrides the sso-enabled attribute setting of the http-service element. An inherit setting uses the sso-enabled attribute setting of the http-service element.

sso-cookie-secure

dynamic

Sets the Secure attribute of any JSESSIONIDSSO cookies associated with the web applications deployed to this virtual server. Applicable only if the sso-enabled attribute is set to true. Allowed values are as follows:

  • true — Sets Secure to true.

  • false — Sets Secure to false.

  • dynamic — The JSESSIONIDSSO cookie inherits the Secure setting of the first session participating in SSO.

To set the Secure attribute of a JSESSIONID cookie, use the cookieSecure cookie-properties property in the sun-web.xml file. For details, see cookie-properties in Oracle GlassFish Server 3.0.1 Application Deployment Guide.

Properties

The following table describes properties for the virtual-server element.

Table 1–177 virtual-server Properties

Property 

Default 

Description 

sso-enabled

false

Deprecated. Use the sso-enabled attribute instead.

sso-max-inactive-seconds

300

Specifies the time after which a user’s single sign-on record becomes eligible for purging if no client activity is received. Since single sign-on applies across several applications on the same virtual server, access to any of the applications keeps the single sign-on record active. Higher values provide longer single sign-on persistence for the users at the expense of more memory use on the server. 

sso-reap-interval-seconds

60

Specifies the interval between purges of expired single sign-on records. 

ssoCookieSecure

dynamic

Deprecated. Use the sso-cookie-secure attribute instead.

setCacheControl

none 

Specifies a comma-separated list of Cache-Control response directives. For a list of valid directives, see section 14.9 of the document at http://www.ietf.org/rfc/rfc2616.txt.

accessLoggingEnabled

false

Deprecated. Use the access-logging-enabled attribute instead.

accessLogBufferSize

32768

Specifies the size, in bytes, of the buffer where access log calls are stored. If the value is less than 5120, a warning message is issued, and the value is set to 5120.

accessLogWriteInterval

300

Specifies the number of seconds before the log is written to the disk. The access log is written when the buffer is full or when the interval expires. If the value is 0, the buffer is always written even if it is not full. This means that each time the server is accessed, the log message is stored directly to the file.

allowRemoteAddress

none 

Specifies a comma-separated list of regular expression patterns that the remote client's IP address is compared to. If this property is specified, the remote address must match for this request to be accepted. If this property is not specified, all requests are accepted unless the remote address matches a denyRemoteAddress pattern.

denyRemoteAddress

none 

Specifies a comma-separated list of regular expression patterns that the remote client's IP address is compared to. If this property is specified, the remote address must not match for this request to be accepted. If this property is not specified, request acceptance is governed solely by the allowRemoteAddress property.

allowRemoteHost

none 

Specifies a comma-separated list of regular expression patterns that the remote client's hostname (as returned by [java.net.]Socket.getInetAddress().getHostName()) is compared to. If this property is specified, the remote hostname must match for this request to be accepted. If this property is not specified, all requests are accepted unless the remote hostname matches a denyRemoteHost pattern.

denyRemoteHost

none 

Specifies a comma-separated list of regular expression patterns that the remote client's hostname (as returned by [java.net.]Socket.getInetAddress().getHostName()) is compared to. If this property is specified, the remote hostname must not match for this request to be accepted. If this property is not specified, request acceptance is governed solely by the allowRemoteHost property.

Setting this property has no effect if jk-enabled is set to true for a network-listener.

authRealm

none 

Specifies the name attribute of an auth-realm element, which overrides the server instance's default realm for stand-alone web applications deployed to this virtual server. A realm defined in a stand-alone web application's web.xml file overrides the virtual server's realm.

securePagesWithPragma

true

Set this property to false to ensure that for all web applications on this virtual server file downloads using SSL work properly in Internet Explorer.

You can set this property for a specific web application. For details, see sun-web-app in Oracle GlassFish Server 3.0.1 Application Deployment Guide.

alternatedocroot_n

none 

Specifies an alternate document root (docroot), where n is a positive integer that allows specification of more than one. Alternate docroots allow web applications to serve requests for certain resources from outside their own docroot, based on whether those requests match one (or more) of the URI patterns of the web application's alternate docroots.

If a request matches an alternate docroot's URI pattern, it is mapped to the alternate docroot by appending the request URI (minus the web application's context root) to the alternate docroot's physical location (directory). If a request matches multiple URI patterns, the alternate docroot is determined according to the following precedence order: 

  • Exact match

  • Longest path match

  • Extension match

For example, the following properties specify three alternate docroots. The URI pattern of the first alternate docroot uses an exact match, whereas the URI patterns of the second and third alternate docroots use extension and longest path prefix matches, respectively. 

<property name="alternatedocroot_1" 
   value="from=/my.jpg dir=/srv/images/jpg"/>
<property name="alternatedocroot_2" 
   value="from=*.jpg dir=/srv/images/jpg"/>
<property name="alternatedocroot_3" 
   value="from=/jpg/* dir=/src/images"/>

The value of each alternate docroot has two components: The first component, from, specifies the alternate docroot's URI pattern, and the second component, dir, specifies the alternate docroot's physical location (directory). Spaces are allowed in the dir component.

You can set this property for a specific web application. For details, see sun-web-app in Oracle GlassFish Server 3.0.1 Application Deployment Guide.

contextXmlDefault

none 

Specifies the location, relative to domain-dir, of the context.xml file for this virtual server, if one is used. For more information about the context.xml file, see Using a context.xml File in Oracle GlassFish Server 3.0.1 Application Development Guide and The Context Container. Context parameters, environment entries, and resource definitions in context.xml are supported in the GlassFish Server.

allowLinking

false

If true, resources that are symbolic links in web applications on this virtual server are served. The value of this property in the sun-web.xml file takes precedence if defined. For details, see sun-web-app in Oracle GlassFish Server 3.0.1 Application Deployment Guide.


Caution – Caution –

Setting this property to true on Windows systems exposes JSP source code.


send-error_n

none 

Specifies custom error page mappings for the virtual server, which are inherited by all web applications deployed on the virtual server. A web application can override these custom error page mappings in its web.xml deployment descriptor. The value of each send-error_n property has three components, which may be specified in any order:

The first component, code, specifies the three-digit HTTP response status code for which the custom error page should be returned in the response.

The second component, path, specifies the absolute or relative file system path of the custom error page. A relative file system path is interpreted as relative to the domain-dir/config directory.

The third component, reason, is optional and specifies the text of the reason string (such as Unauthorized or Forbidden) to be returned.

For example: 

<property name="send-error_1"
   value="code=401 path=/myhost/401.html reason=MY-401-REASON"/>

This example property definition causes the contents of /myhost/401.html to be returned with 401 responses, along with this response line:


HTTP/1.1 401 MY-401-REASON

redirect_n

none 

Specifies that a request for an old URL is treated as a request for a new URL. These properties are inherited by all web applications deployed on the virtual server. The value of each redirect_n property has two components, which may be specified in any order:

The first component, from, specifies the prefix of the requested URI to match.

The second component, url-prefix, specifies the new URL prefix to return to the client. The from prefix is simply replaced by this URL prefix.

For example: 

<property name="redirect_1" 
value="from=/dummy url-prefix=http://etude"/>

valve_n

none 

Specifies a fully qualified class name of a custom valve, where n is a positive integer that allows specification of more than one. The valve class must implement the org.apache.catalina.Valve interface from Tomcat or previous GlassFish Server releases, or the org.glassfish.web.valve.GlassFishValve interface from the current GlassFish Server release. For example:

<property name="valve_1" 
   value="org.glassfish.extension.Valve"/>

You can set this property for a specific web application. For details, see sun-web-app in Oracle GlassFish Server 3.0.1 Application Deployment Guide.

listener_n

none 

Specifies a fully qualified class name of a custom Catalina listener, where n is a positive integer that allows specification of more than one. The listener class must implement the org.apache.catalina.ContainerListener or org.apache.catalina.LifecycleListener interface. For example:

<property name="listener_1" 
   value="org.glassfish.extension.MyLifecycleListener"/>

You can set this property for a specific web application. For details, see sun-web-app in Oracle GlassFish Server 3.0.1 Application Deployment Guide.

errorReportValve

org.apache.catalina.valves.ErrorReportValve

Specifies a fully qualified class name of a custom valve that produces default error pages for applications on this virtual server. Specify an empty string to disable the default error page mechanism for this virtual server. 

W

web-container

Configures the web container.

Superelements

config

Subelements

The following table describes subelements for the web-container element.

Table 1–178 web-container Subelements

Element 

Required 

Description 

session-config

zero or one 

Specifies session configuration information for the web container. 

property

zero or more 

Specifies a property or a variable. 

Properties

The following table describes properties for the web-container element.

Table 1–179 web-container Properties

Property 

Default 

Description 

dispatcher-max-depth

20

Prevents recursive include or forward statements from creating an infinite loop by setting a maximum nested dispatch level. If this level is exceeded, the following message is written to the server log:

Exceeded maximum depth for nested request dispatches

web-module

This element is deprecated. Use an application element instead.

Specifies a deployed web module.

Superelements

applications

Subelements

The following table describes subelements for the web-module element.

Table 1–180 web-module Subelements

Element 

Required 

Description 

description

zero or one 

Contains a text description of this element. 

web-service-endpoint

zero or more 

Configures a web service endpoint. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the web-module element.

Table 1–181 web-module Attributes

Attribute 

Default 

Description 

name

none 

The name of the web module. 

context-root

none 

The context root at which the web module is deployed. The context root can be the empty string or just /. The context root can start with the / character, but doesn’t have to.

location

none 

A fully qualified or relative path to the directory to which the contents of the .war file have been extracted. If relative, it is relative to the following directory:

domain-dir/applications/

object-type

user

(optional) Defines the type of the resource. For a web module, the only allowed value is user.

enabled

true

(optional) Determines whether the web module is enabled. 

libraries

none 

(optional) Specifies an absolute or relative path to libraries specific to this module or application. A relative path is relative to domain-dir/lib/applibs. If the path is absolute, the path must be accessible to the domain administration server (DAS), which means it must be under domain-dir. To include more than one path, use a system-specific separator, such as a colon for Solaris or a semicolon for Windows. The libraries are made available to the application in the order in which they are specified.

directory-deployed

false

(optional) Specifies whether the application has been deployed as a directory. 

web-module-config

Configures the grandparent web module. Applicable only if the parent engine element has a sniffer value of web.

Superelements

engine

Subelements

The following table describes subelements for the web-module-config element.

Table 1–182 web-module-config Subelements

Element 

Required 

Description 

env-entry

zero or more 

Configures an environment entry for a web module. 

context-param

zero or more 

Configures a context parameter for a web module. 

web-service-endpoint

This element is deprecated. Web services are implemented in the engine element.

Configures a web service endpoint, which can be a JAX-RPC/JAXWS 2.0 or JSR-109 web service.

Superelements

ejb-module, j2ee-application, web-module

Subelements

The following table describes subelements for the web-service-endpoint element.

Table 1–183 web-service-endpoint Subelements

Element 

Required 

Description 

registry-location

zero or more 

Specifies the registry where web service endpoint artifacts are published.  

transformation-rule

zero or more 

Configures an eXtensible Stylesheet Language Transformation (XSLT) rule.

Attributes

The following table describes attributes for the web-service-endpoint element.

Table 1–184 web-service-endpoint Attributes

Attribute 

Default 

Description 

name

none 

The fully qualified name of the web service. For a web service endpoint within an application, the format is as follows: 

module-name#endpoint-name

For example: 

jaxrpc-simple.war#HelloIF

For a web service endpoint that is a stand-alone module, the name is just the endpoint-name.

monitoring

OFF

(optional) Specifies the monitoring level for this web service. For information about monitoring levels, see module-monitoring-levels.

max-history-size

25

(optional) Specifies the maximum number of monitoring records stored for this endpoint. 

jbi-enabled

false

(optional) Determines whether the visibility of this endpoint as a Java Business Integration service is enabled or disabled.

work-security-map

Defines a work security map, which maps a principal associated with an incoming work instance to a principal in the GlassFish Server's security domain. It is possible to map multiple EIS group or user principals to the same GlassFish Server principal.

This is different from a security-map, which maps the principal received during servlet or EJB authentication to the credentials accepted by the EIS.

Superelements

resources

Subelements

The following table describes subelements for the work-security-map element.

Table 1–185 work-security-map Subelements

Element 

Required 

Description 

principal-map

zero or more 

Maps an EIS principal to a principal defined in the GlassFish Server domain. 

group-map

zero or more 

Maps an EIS group to a group defined in the GlassFish Server domain. 

Attributes

The following table describes attributes for the work-security-map element.

Table 1–186 work-security-map Attributes

Attribute 

Default 

Description 

name

none 

Specifies a unique name for the work security map. 

description

none 

Specifies a text description for this element.