Sun GlassFish Enterprise Server 2.1 Administration Reference

J

j2ee-application

Specifies a deployed Java EE application.

Superelements

applications

Subelements

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

Table 1–80 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–81 j2ee-application Attributes

Attribute 

Default 

Description 

name

none 

The name of the application. 

location

none 

The location of the application in the Enterprise Server file system. 

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

availability-enabled

false

(optional) Specifies whether availability is enabled in this Java EE application for HTTP session persistence and SFSB checkpointing (and potentially passivation). Availability must also be enabled for the application during deployment. For more information about availability, see availability-service.

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–82 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–83 jacc-provider Attributes

Attribute 

Default 

Description 

name

default

Specifies the name of the JACC provider. 

policy-provider

com.sun.enterprise.security.provider.PolicyWrapper

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

Corresponds to and can be overridden by the system property javax.security.jacc.PolicyConfigurationFactory.provider .

java-config

Specifies Java Virtual Machine (JVM) configuration parameters.

Superelements

config

Subelements

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

Table 1–84 java-config Subelements

Element 

Required 

Description 

profiler

zero or one 

Configures a profiler for use with the Enterprise 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–85 java-config Attributes

Attribute 

Default 

Description 

java-home

none 

The path to the directory where the JDK is installed. 

debug-enabled

false

(optional) If true, the server starts up in debug mode ready for attachment with a JPDA-based debugger.

debug-options

-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n

(optional) Specifies JPDA (Java Platform Debugger Architecture) options. A list of debugging options is available at http://java.sun.com/products/jpda/doc/conninv.html#Invocation.

For more information about debugging, see the Sun GlassFish Enterprise Server 2.1 Developer’s Guide.

rmic-options

-iiop -poa -alwaysgenerate -keepgenerated -g

(optional) Specifies options passed to the RMI compiler at application deployment time. The -keepgenerated option saves generated source for stubs and ties.

For details about the rmic command, see http://java.sun.com/javase/6/docs/technotes/tools/solaris/rmic.html.

javac-options

-g

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

classpath-prefix

none 

(optional) Specifies a prefix for the server classpath. Only prefix this classpath to override Enterprise Server classes. Use this attribute with caution. 

classpath-suffix

none 

(optional) Specifies a suffix for the server classpath. 

server-classpath

none 

(optional) Specifies additions to the server classpath. Supported for backward compatibility. Use classpath-suffix instead.

system-classpath

JVM classes 

(optional) Specifies additions to the system classpath, which is supplied to the JVM at server startup. These classes are loaded by the System Classloader.


Note –

Do not remove the default path.


native-library-path-prefix

none 

(optional) Specifies a prefix for the native library path. 

The native library path is the automatically constructed concatenation of the Enterprise Server installation relative path for its native shared libraries, the standard JRE native library path, the shell environment setting (LD_LIBRARY_PATH on UNIX), and any path specified in the profiler element. Since this is synthesized, it does not appear explicitly in the server configuration.

native-library-path-suffix

none 

(optional) Specifies a suffix for the native library path. 

bytecode-preprocessors

none 

(optional) A comma separated list of class names, each of which must implement the com.sun.appserv.BytecodePreprocessor interface. Each of the specified preprocessor classes is called in the order specified.

env-classpath-ignored

true

(optional) If false, the CLASSPATH environment variable is read and appended to the Enterprise Server classpath. The CLASSPATH environment variable is added after the classpath-suffix, at the very end.

For a development environment, this value should be set to false. To prevent environment variable side effects in a production environment, set this value to true.

jdbc-connection-pool

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

Superelements

resources

Subelements

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

Table 1–86 jdbc-connection-pool 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 jdbc-connection-pool element. Changing the following attributes requires a server restart: datasource-classname, associate-with-thread, lazy-connection-association, and lazy-connection-enlistment.

Table 1–87 jdbc-connection-pool Attributes

Attribute 

Default 

Description 

name

none 

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

datasource-classname

none 

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

res-type

javax.sql.DataSource

(optional) Specifies the interface the data source class implements. The value of this attribute can be javax.sql.DataSource, javax.sql.XADataSource , or javax.sql.ConnectionPoolDatasource. If the value is not one of these interfaces, the default is used. An error occurs if this attribute has a legal value and the indicated interface is not implemented by the data source class.

steady-pool-size

8

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

max-pool-size

32

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

max-wait-time-in-millis

60000

(optional) Specifies the amount of time, in milliseconds, that the caller is willing to wait for a connection. If 0, the caller is blocked indefinitely until a resource is available or an error occurs.

pool-resize-quantity

2

(optional) Specifies the number of 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. 

transaction-isolation-level

default JDBC driver isolation level 

(optional) Specifies the transaction isolation level on the pooled database connections. Allowed values are read-uncommitted, read-committed , repeatable-read, or serializable.

Applications that change the isolation level on a pooled connection programmatically risk polluting the pool, which can lead to errors. See is-isolation-level-guaranteed for more details.

is-isolation-level-guaranteed

true

(optional) Applicable only when transaction-isolation-level is explicitly set. If true, every connection obtained from the pool is guaranteed to have the desired isolation level. This might impact performance on some JDBC drivers. Only set this attribute to false if you are certain that the hosted applications do not return connections with altered isolation levels.

is-connection-validation-required

false

(optional) Specifies whether connections have to be validated before being given to the application. If a resource’s validation fails, it is destroyed, and a new resource is created and returned. 

connection-validation-method

auto-commit

(optional) Legal values are as follows: 

  • auto-commit (default), 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

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-method is set to table.

fail-all-connections

false

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

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.

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.

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. 

statement-timeout-in-seconds

-1

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

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 a connection to be saved as a ThreadLocal in the calling thread. This connection gets reclaimed only when the calling thread dies or when the calling thread is not in use and the pool has run out of connections.

match-connections

false

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. 

wrap-jdbc-objects

false

If true, the application returns wrapped JDBC objects for Statement, PreparedStatement, CallableStatement, ResultSet, and DatabaseMetaData.

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 Enterprise 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–88 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. 

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–89 jdbc-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 jdbc-resource element.

Table 1–90 jdbc-resource Attributes

Attribute 

Default 

Description 

jndi-name

none 

Specifies the JNDI name for the resource. 

pool-name

none 

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

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

Enables availability in the Sun GlassFish Message Queue cluster that comprises the Java Message Service (JMS). Messages are saved to the HADB. The HADB must be installed and the enterprise profile must be selected. You must enable availability for Enterprise Server instances before you can enable availability for the corresponding Message Queue brokers.


Note –

Individual applications and modules cannot control or override JMS availability.



Note –

Some topics in the documentation pertain to features that are available only in domains that are configured to support clusters. Examples of domains that support clusters are domains that are created with the cluster profile or the enterprise profile. For information about profiles, see Usage Profiles in Sun GlassFish Enterprise Server 2.1 Administration Guide.


Superelements

availability-service

Subelements

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

Table 1–91 jms-availability Subelements

Element 

Required 

Description 

property

zero or more 

Specifies a property or a variable. 

Attributes

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

Table 1–92 jms-availability Attributes

Attribute 

Default 

Description 

availability-enabled

false

(optional) If set to true, and if availability is enabled for the Enterprise Server instance (see availability-service), high-availability is enabled for the Message Queue cluster associated with the Enterprise Server cluster. All instances in an Enterprise Server cluster should have the same availability settings to ensure consistent behavior.

mq-store-pool-name

availability-service store-pool-name attribute value

(optional) Specifies the jndi-name of the jdbc-resource used for connections to the HADB for the Message Queue cluster. Applicable if HADB is installed and you have selected the enterprise profile.

For more information about setting up a connection pool and JDBC resource for the HADB, see the description of the configure-ha-cluster command in the Sun GlassFish Enterprise Server 2.1 Reference Manual.

jms-host

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

Superelements

jms-service

Subelements

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

Table 1–93 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–94 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 Enterprise Server.

Superelements

config

Subelements

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

Table 1–95 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–96 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 (DAS) or LOCAL (other server instances)

Specifies the type of JMS service: 

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

    Lazy initialization starts the default embedded broker on the first access of JMS services rather than at Enterprise Server startup. EMBEDDED mode is not a supported configuration for a cluster.

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

    The LOCAL setting implicitly sets up a 1:1 relationship between an Enterprise Server instance and a Message Queue broker. When you create an Enterprise Server cluster, a Message Queue cluster is automatically created as well. During cluster creation, each instance in the Enterprise Server cluster is automatically configured with a broker in the Message Queue cluster, and a unique broker port is determined.

  • REMOTE means the JMS provider is remote and is not started by the Enterprise 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 Enterprise Server startup.

reconnect-interval-in-seconds

5 (developer profile)

60 (cluster and enterprise profiles)

(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–97 jms-service Properties

Property 

Default 

Description 

instance-name

imqbroker

Specifies the full Sun 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, node-agent

Subelements

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

Table 1–98 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–99 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 (DAS, all profiles; server instance, developer profile)

38686 (server instances, cluster and enterprise profiles)

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 (developer profile)

true (cluster and enterprise profiles)

(optional) Determines whether JMX communication is encrypted.  

jvm-options

Contains JVM command line options, for example:

<jvm-options>-Xdebug -Xmx128m</jvm-options>

For information about JVM options, see http://java.sun.com/docs/hotspot/VMOptions.html.

Superelements

java-config, profiler

Subelements

none - contains data