Sun GlassFish Enterprise Server v2.1.1 Administration Reference

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–49 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–50 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-container-availability

Enables availability in the EJB container, including stateful session bean (SFSB) state persistence. If HADB is installed and you have selected the enterprise profile, session state is persisted to the HADB. For additional replicated session persistence properties you can set, see availability-service.

Superelements

availability-service

Subelements

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

Table 1–51 ejb-container-availability Subelements


Element	Required	Description
property	zero or more	Specifies a property or a variable.

Attributes

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

Table 1–52 ejb-container-availability Attributes


Attribute	Default	Description
`availability-enabled`	`true`	(optional) If set to `true`, and if availability is enabled for the server instance (see availability-service), high-availability features apply to all SFSBs deployed to the server instance that do not have availability disabled. All instances in a cluster should have the same availability value to ensure consistent behavior.
`sfsb-ha-persistence-type`	`ha`	(optional) Specifies the session persistence and passivation mechanism for SFSBs that have availability enabled. Allowed values are `file` (the file system) and `replicated` (other servers). If HADB is installed and you have selected the enterprise profile, you can also specify `ha`. For production environments that require session persistence, use `ha`. If set to `file`, the ejb-container element’s `session-store` attribute specifies the file system location where the passivated session bean state is stored. Checkpointing to the file system is useful for internal testing but is not supported for production environments.
`sfsb-persistence-type`	`file`	(optional) Specifies the passivation mechanism for SFSBs that do not have availability enabled. Allowed values are `file` and `replicated`. If HADB is installed and you have selected the enterprise profile, you can also specify `ha`.
`sfsb-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 session persistence. 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 v2.1.1 Reference Manual.

ejb-module

Specifies a deployed EJB module.

Superelements

applications

Subelements

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

Table 1–53 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–54 ejb-module Attributes


Attribute	Default	Description
`name`	none	The name of the EJB module.
`location`	none	The location of the EJB module 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 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.
`availability-enabled`	`false`	(optional) Specifies whether availability is enabled in this EJB module for SFSB checkpointing (and potentially passivation). Availability must also be enabled for the application or stand-alone EJB module during deployment. For more information about availability, see availability-service.
`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–55 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–56 ejb-timer-service Attributes


Attribute	Default	Description
`minimum-delivery-interval-in-millis`	`7000`	(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 cluster or 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.

event

Defines the event that triggers the action associated with a management rule.

Predefined events are provided with the Enterprise Server. You can configure these events by changing event element attributes and properties.

You can create custom events by creating custom MBeans that implement the JMX NotificationEmitter interface. For more information about MBeans, see the Sun GlassFish Enterprise Server v2.1.1 Developer’s Guide and http://java.sun.com/javase/6/docs/api/javax/management/package-summary.html. For information about monitor MBeans, see http://java.sun.com/javase/6/docs/api/javax/management/monitor/package-summary.html.

Note –

If multiple rules are associated with the same event, ordering of action execution is not guaranteed.

Superelements

management-rule

Subelements

The following table describes subelements for the event element.

Table 1–57 event 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 event element.

Table 1–58 event Attributes


Attribute	Default	Description
`type`	none	Specifies the type of event that triggers the management rule's action. Allowed values are as follows. The `cluster`, `lifecycle`, `log`, `monitor`, `timer`, and `trace` types are predefined events provided by the Enterprise Server. 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 v2.1.1 Administration Guide. `cluster` — A Group Management Service (GMS) event. For more information, see group-management-service. `lifecycle` — A lifecycle event. For more information about the server life cycle, see the Sun GlassFish Enterprise Server v2.1.1 Developer’s Guide. `log` — An event in the server log. For more information about the server log, see log-service. `monitor` — A monitoring event, which is a change in the attribute of a monitored mbean. `notification` — A JMX notification event. Any custom mbean that implements the JMX `NotificationEmitter` interface can be a notification event. `timer` — An event that occurs at a specified time. `trace` — A trace event. For descriptions of required and optional properties corresponding to each of these types, see the following table.
`level`	`INFO`	(optional) Specifies the level at which to log the event occurrence. For information about log levels, see module-log-levels. Applicable only if `record-event` is set to `true`.
`record-event`	`true`	(optional) Specifies whether the occurrence of the event is logged. If no action is specified for the parent management-rule, the event is logged regardless of this setting. Note – Setting the `type` to `log` is different from setting `record-event` to `true`. The former specifies what the event is. The latter specifies what happens after the event occurs.

Properties

The following table describes properties for the event element. Property names are case insensitive.

Table 1–59 event Properties


Event Type	Property	Values	Description
`cluster`	`name`	`start`, `stop`, `fail`	Notifies when the GMS starts, stops, or reports failure of a server instance.
`cluster`	`serverName`	A comma-separated list of server instance names, or `*` for all server instances	Specifies the server instances about which GMS notifications are given.
`lifecycle`	`name`	`ready`, `shutdown`, `termination`	Specifies a server life cycle event. Values correspond to events defined in the `com.sun.appserv.server.LifecycleEvent` interface.
`log`	`loggerNames`	A comma-separated list of logger names, or `*` for all loggers, which is the default	(optional) Notifies when the specified loggers write messages to the server log. For a list of logger names, see module-log-levels.
`log`	`level`	A comma-separated list of log levels	(optional) Notifies when messages of the specified level are written to the server log. For information about log levels, see module-log-levels.
`monitor`	`observedMbean`	A `name` attribute of a user-defined mbean, or a JMX `ObjectName` for a system `mbean`	Specifies the name of the monitored MBean. Either this property or `observedObject` must be specified.
`monitor`	`observedObject`	An `object-name` attribute of a user-defined mbean, or a JMX `ObjectName` for a system `mbean`	Specifies the name of the monitored MBean. Either this property or `observedMbean` must be specified.
`monitor`	`observedAttribute`	An mbean `Attribute` name	Specifies the monitored attribute of the monitored MBean.
`monitor`	`monitorType`	`CounterMonitor`, `GaugeMonitor`, `StringMonitor`	The type of monitoring of the attribute.
`monitor`	`granularityPeriod`	Time interval in seconds (`long int`)	(optional) Specifies the granularity at which the monitoring data should be collected.
`monitor`	`notifyMatch`	`true` or `false`	Specifies that the attribute value must match the `stringToCompare` value. Either this property or `notifyDiffer` is required if the monitor type is `StringMonitor`.
`monitor`	`notifyDiffer`	`true` or `false`	Specifies that the attribute value must not match the `stringToCompare` value. Either this property or `notifyMatch` is required if the monitor type is `StringMonitor`.
`monitor`	`stringToCompare`	A `String`	Specifies the value to which the attribute value is compared. Required if the monitor type is `StringMonitor`.
`monitor`	`numberType`	`byte`, `double`, `float`, `int`, `long`, `short`	Specifies the type of the numeric value being monitored. Required if the monitor is of type `CounterMonitor` or `GaugeMonitor`.
`monitor`	`differenceMode`	`true` or `false`	Specifies the difference mode flag value common to all observed MBeans. Required if the monitor is of type `CounterMonitor` or `GaugeMonitor`.
`monitor`	`initThreshold`	A positive number of the type specified by `numberType`	Specifies a value above which notification occurs. Required if the monitor is of type `CounterMonitor`.
`monitor`	`offset`	A positive number of the type specified by `numberType`	(optional) Specifies that the event should be re-triggered when the `initThreshold` value plus this offset value is reached. Applicable if the monitor is of type `CounterMonitor`.
`monitor`	`modulus`	A positive number of the type specified by `numberType`	(optional) Specifies the modulus value common to all observed MBeans. Applicable if the monitor is of type `CounterMonitor`.
`monitor`	`highThreshold`	A positive number of the type specified by `numberType`	Specifies the upper limit of the range within which notification occurs. Required if the monitor is of type `GaugeMonitor`.
`monitor`	`lowThreshold`	A positive number of the type specified by `numberType`	Specifies the lower limit of the range within which notification occurs. Required if the monitor is of type `GaugeMonitor`.
`notification`	`sourceMBean`	`name` of mbean	Specifies a custom MBean that implements the JMX `NotificationEmitter` interface. Either this property or `sourceObjectName` must be specified.
`notification`	`sourceObjectName`	`object-name` of mbean	Specifies a custom MBean that implements the JMX `NotificationEmitter` interface. Either this property or `sourceMBean` must be specified.
`notification`	`type`	The notification type	(optional) Specifies the notification type. If this property is specified, the action of the parent management-rule is performed only if the notification type emitted is same as this property's value.
`timer`	`dateString`	Input format determined by `pattern` property	Begins notification at the specified date and time.
`timer`	`pattern`	`SimpleDateFormat` pattern	(optional) Specifies the date and time input format. The default is `mm/dd/yyyy hh:mm:ss`.
`timer`	`period`	Time interval in milliseconds (`long int`)	(optional) Notification repeats at the specified time interval.
`timer`	`numberOfOccurrences`	A positive number (`long int`)	(optional) Specifies the number of times notification occurs.
`timer`	`message`	A `String`	(optional) Specifies a message that is delivered as part of timer notification.
`trace`	`name`	`web_component_method_entry`, `web_component_method_exit`, `ejb_component_method_entry`, `ejb_component_method_exit`, `request_start`, `request_end`	Notifies at the specified trace point.
`trace`	`ipAddress`	An IP address	Specifies the IP address for which trace notifications are sent.
`trace`	`callerPrincipal`	A `String`	Specifies the caller principal for which trace notifications are sent.
`trace`	`componentName`	A `String`	Specifies the component name for which trace notifications are sent.

extension-module

Specifies a deployed extension module.

Superelements

applications

Subelements

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

Table 1–60 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–61 extension-module Attributes


Attribute	Default	Description
`name`	none	The name of the extension module.
`location`	none	The location of the extension module in the Enterprise Server file system.
`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 Enterprise Server, the Enterprise Server specifies the module type automatically.
`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 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.
`availability-enabled`	`false`	(optional) Specifies whether availability is enabled in this extension module. Availability must also be enabled for the application or stand-alone extension module during deployment. For more information about availability, see availability-service.
`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–62 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–63 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 Sun GlassFish Enterprise Server v2.1.1 Developer’s 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.