docs/application-deployment-guide/src/main/asciidoc/dd-elements.adoc

type=page
status=published
title=Elements of the {productName} Deployment Descriptors
prev=dd-files.html
~~~~~~

= Elements of the {productName} Deployment Descriptors

[[GSDPG00007]][[beaqi]]


[[c-elements-of-the-glassfish-server-deployment-descriptors]]
== C Elements of the {productName} Deployment Descriptors

This appendix describes the elements of the {productName}deployment descriptors.

[[beaqs]][[GSDPG00085]][[activation-config]]

=== `activation-config`

Specifies an activation configuration, which includes the runtime
configuration properties of the message-driven bean in its operational
environment. For example, this can include information about the name of
a physical JMS destination. Matches and overrides the
`activation-config` element in the `ejb-jar.xml` file.

[[fvyoe]][[GSDPG00335]][[superelements]]

==== Superelements

link:#beaus[`mdb-resource-adapter`] (`glassfish-ejb-jar.xml`)

[[fvynj]][[GSDPG00336]][[subelements]]

==== Subelements

The following table describes subelements for the `activation-config`
element.

[[GSDPG838]][[sthref9]][[fvynw]]


Table C-1 `activation-config` subelements

[width="100%",cols="32%,12%,56%",options="header",]
|===
|Element |Required |Description
a|
link:#beaso[`description`]


 |zero or one |Specifies a text description of the activation
configuration.

a|
link:#beaqt[`activation-config-property`]


 |one or more |Specifies an activation configuration property.
|===


[[beaqt]][[GSDPG00086]][[activation-config-property]]

=== `activation-config-property`

Specifies the name and value of an activation configuration property.

[[fvyne]][[GSDPG00337]][[superelements-1]]

==== Superelements

link:#beaqs[`activation-config`] (`glassfish-ejb-jar.xml`)

[[fvyns]][[GSDPG00338]][[subelements-1]]

==== Subelements

The following table describes subelements for the
`activation-config-property` element.

[[GSDPG839]][[sthref10]][[fvynv]]


Table C-2 `activation-config-property` subelements

[width="100%",cols="39%,10%,51%",options="header",]
|===
|Element |Required |Description
a|
link:#beaqu[`activation-config-property-name`]


 |only one |Specifies the name of an activation configuration property.
a|
link:#beaqv[`activation-config-property-value`]


 |only one |Specifies the value of an activation configuration property.
|===


[[beaqu]][[GSDPG00087]][[activation-config-property-name]]

=== `activation-config-property-name`

Specifies the name of an activation configuration property.

[[fvynm]][[GSDPG00339]][[superelements-2]]

==== Superelements

link:#beaqt[`activation-config-property`] (`glassfish-ejb-jar.xml`)

[[fvyok]][[GSDPG00340]][[subelements-2]]

==== Subelements

none - contains data

[[beaqv]][[GSDPG00088]][[activation-config-property-value]]

=== `activation-config-property-value`

Specifies the value of an activation configuration property.

[[fvyou]][[GSDPG00341]][[superelements-3]]

==== Superelements

link:#beaqt[`activation-config-property`] (`glassfish-ejb-jar.xml`)

[[fvyoz]][[GSDPG00342]][[subelements-3]]

==== Subelements

none - contains data

[[giyhw]][[GSDPG00089]][[admin-object-resource]]

=== `admin-object-resource`

Defines an administered object for an inbound resource adapter.

[[GSDPG840]][[sthref11]]


[[superelements-4]]
==== Superelements

link:#giyiy[`resources`] (`glassfish-resources.xml`)

[[GSDPG841]][[sthref12]]


[[subelements-4]]
==== Subelements

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

[[GSDPG842]][[sthref13]][[sthref14]]


Table C-3 `admin-object-resource` Subelements

[width="100%",cols="25%,12%,63%",options="header",]
|===
|Element |Required |Description
a|link:#beaso[`description`]
|zero or one
|Contains a text description of this element.

a|link:#beavx[`property`] (with attributes)
|zero or more
|Specifies a property or a variable.
|===


[[GSDPG843]][[sthref15]]


[[attributes]]
==== Attributes

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

[[GSDPG844]][[sthref16]][[sthref17]]


Table C-4 `admin-object-resource` Attributes

[width="172%",cols="9%,46%,45%",options="header",]
|===
|Attribute |Default |Description
|`jndi-name` |none |Specifies the JNDI name for the resource.

|`res-type` |none |Specifies the fully qualified type of the resource.

|`res-adapter` |none |Specifies the name of the inbound resource
adapter.

|`object-type` |`user` a|
(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.
|===


[[GSDPG845]][[sthref18]]


[[properties]]
==== Properties

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

[[beaqw]][[GSDPG00090]][[as-context]]

=== `as-context`

Specifies the authentication mechanism used to authenticate the client.

[[fvyos]][[GSDPG00343]][[superelements-5]]

==== Superelements

link:#beato[`ior-security-config`] (`glassfish-ejb-jar.xml`)

[[fvyom]][[GSDPG00344]][[subelements-5]]

==== Subelements

The following table describes subelements for the `as-context` element.

[[GSDPG846]][[sthref19]][[fvyov]]


Table C-5 `as-context` Subelements

[width="100%",cols="14%,10%,76%",options="header",]
|===
|Element |Required |Description
a|
link:#beaqx[`auth-method`]


 |only one |Specifies the authentication method. The only supported
value is `USERNAME_PASSWORD`.

a|
link:#beawi[`realm`]


 |only one |Specifies the realm in which the user is authenticated.

a|
link:#beawq[`required`]


 |only one |Specifies whether the authentication method specified in the
`auth-method` element must be used for client authentication.
|===


[[gjizj]][[GSDPG00091]][[archive-name]]

=== `archive-name`

Specifies the name of the archive file. The value of the `archive-name`
element is used to derive the default application name when
`display-name` is not present in the `application.xml` file. The default
application name is the `archive-name` value minus the file extension.
For example, if `archive-name` is `foo.ear`, the default application
name is `foo`.

[[gjizb]][[GSDPG00345]][[superelements-6]]

==== Superelements

link:#beaxw[`glassfish-application`] (`glassfish-application.xml`)

[[gjizg]][[GSDPG00346]][[subelements-6]]

==== Subelements

none - contains data

[[beaqx]][[GSDPG00092]][[auth-method]]

=== `auth-method`

Specifies the authentication method.

If the parent element is link:#beaqw[`as-context`], the only supported
value is `USERNAME_PASSWORD`.

If the parent element is link:#beauk[`login-config`], specifies the
authentication mechanism for the web service endpoint. As a prerequisite
to gaining access to any web resources protected by an authorization
constraint, a user must be authenticated using the configured mechanism.

[[fvyow]][[GSDPG00347]][[superelements-7]]

==== Superelements

link:#beauk[`login-config`] (`glassfish-web.xml`),
link:#beaqw[`as-context`] (`glassfish-ejb-jar.xml`)

[[fvyop]][[GSDPG00348]][[subelements-7]]

==== Subelements

none - contains data

[[beaqy]][[GSDPG00093]][[auth-realm]]

=== `auth-realm`

JAAS is available on the ACC. Defines the optional configuration for a
JAAS authentication realm. Authentication realms require
provider-specific properties, which vary depending on what a particular
implementation needs. For more information about how to define realms,
see "link:application-development-guide/securing-apps.html#GSDVG00118[Realm Configuration]" in {productName} Application Development Guide.

[[fvyot]][[GSDPG00349]][[superelements-8]]

==== Superelements

link:#bearr[`client-container`] (`sun-acc.xml`)

[[fvyor]][[GSDPG00350]][[subelements-8]]

==== Subelements

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

[[GSDPG847]][[sthref20]][[fvyol]]


Table C-6 `auth-realm` subelement

[width="100%",cols="36%,14%,50%",options="header",]
|===
|Element |Required |Description
a|
link:#beavx[`property` (with attributes)]


 |zero or more |Specifies a property, which has a name and a value.
|===


[[fvyoy]][[GSDPG00351]][[attributes-1]]

==== `Attributes`

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

[[GSDPG848]][[sthref21]][[fvypa]]


Table C-7 `auth-realm` attributes

[width="100%",cols="18%,13%,69%",options="header",]
|===
|Attribute |Default |Description
|`name` |none |Defines the name of this realm.
|`classname` |none |Defines the Java class which implements this realm.
|===


[[fvyox]][[GSDPG00352]][[example]]

==== Example

Here is an example of the default file realm:

[source,xml]
----
<auth-realm name="file"
   classname="com.sun.enterprise.security.auth.realm.file.FileRealm">
   <property name="file" value="domain-dir/config/keyfile"/>
   <property name="jaas-context" value="fileRealm"/>
</auth-realm>
----

Which properties an `auth-realm` element uses depends on the value of
the `auth-realm` element's `name` attribute. The file realm uses `file`
and `jaas-context` properties. Other realms use different properties.
See "link:application-development-guide/securing-apps.html#GSDVG00118[Realm Configuration]" in {productName} Application Development Guide.

[[giyjv]][[GSDPG00094]][[backend-principal]]

=== `backend-principal`

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

[[GSDPG849]][[sthref22]]


[[superelements-9]]
==== Superelements

link:#giyhy[`security-map`] (`glassfish-resources.xml`)

[[GSDPG850]][[sthref23]]


[[subelements-9]]
==== Subelements

none

[[GSDPG851]][[sthref24]]


[[attributes-2]]
==== Attributes

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

[[GSDPG852]][[sthref25]][[sthref26]]


Table C-8 `backend-principal` Attributes

[width="100%",cols="26%,17%,57%",options="header",]
|===
|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.
|===


[[beara]][[GSDPG00095]][[bean-cache]]

=== `bean-cache`

Specifies the entity bean cache properties. Used for entity beans and
stateful session beans.

[[fvyoq]][[GSDPG00353]][[superelements-10]]

==== Superelements

link:#beass[`ejb`] (`glassfish-ejb-jar.xml`)

[[fvyon]][[GSDPG00354]][[subelements-10]]

==== Subelements

The following table describes subelements for the `bean-cache` element.

[[GSDPG853]][[sthref27]][[fvypb]]


Table C-9 `bean-cache` Subelements

[width="100%",cols="35%,11%,54%",options="header",]
|===
|Element |Required |Description
a|
link:#beauo[`max-cache-size`]


 |zero or one |Specifies the maximum number of beans allowable in cache.

a|
link:#beatp[`is-cache-overflow-allowed`]


 |zero or one |Deprecated.

a|
link:#bearg[`cache-idle-timeout-in-seconds`]


 |zero or one |Specifies the maximum time that a stateful session bean
or entity bean is allowed to be idle in cache before being passivated.
Default value is 10 minutes (600 seconds).

a|
link:#beawl[`removal-timeout-in-seconds`]


 |zero or one |Specifies the amount of time a bean remains before being
removed. If `removal-timeout-in-seconds` is less than `idle-timeout`,
the bean is removed without being passivated.

a|
link:#beaws[`resize-quantity`]


 |zero or one |Specifies the number of beans to be created if the pool
is empty (subject to the `max-pool-size` limit). Values are from 0 to
MAX_INTEGER.

a|
link:#beayp[`victim-selection-policy`]


 |zero or one |Specifies the algorithm that must be used by the
container to pick victims. Applies only to stateful session beans.
|===


[[fvyoo]][[GSDPG00355]][[example-1]]

==== Example

[source,xml]
----
<bean-cache>
   <max-cache-size>100</max-cache-size>
   <cache-resize-quantity>10</cache-resize-quantity>
   <removal-timeout-in-seconds>3600</removal-timeout-in-seconds>
   <victim-selection-policy>LRU</victim-selection-policy>
      <cache-idle-timeout-in-seconds>600</cache-idle-timeout-in-seconds>
   <removal-timeout-in-seconds>5400</removal-timeout-in-seconds>
</bean-cache>
----

[[bearb]][[GSDPG00096]][[bean-pool]]

=== `bean-pool`

Specifies the pool properties of stateless session beans, entity beans,
and message-driven bean.

[[fvypc]][[GSDPG00356]][[superelements-11]]

==== Superelements

link:#beass[`ejb`] (`glassfish-ejb-jar.xml`)

[[fvypd]][[GSDPG00357]][[subelements-11]]

==== Subelements

The following table describes subelements for the `bean-pool` element.

[[GSDPG854]][[sthref28]][[fvypg]]


Table C-10 `bean-pool` Subelements

[width="100%",cols="34%,11%,55%",options="header",]
|===
|Element |Required |Description
a|
link:#beaxt[`steady-pool-size`]


 |zero or one |Specifies the initial and minimum number of beans
maintained in the pool. Default is 32.

a|
link:#beaws[`resize-quantity`]


 |zero or one |Specifies the number of beans to be created if the pool
is empty (subject to the `max-pool-size` limit). Values are from 0 to
MAX_INTEGER.

a|
link:#beaup[`max-pool-size`]


 |zero or one |Specifies the maximum number of beans in the pool. Values
are from 0 to MAX_INTEGER. Default is to the EJB container value or 60.

a|
link:#beauq[`max-wait-time-in-millis`]


 |zero or one |Deprecated.

a|
link:#beavr[`pool-idle-timeout-in-seconds`]


 |zero or one |Specifies the maximum time that a bean is allowed to be
idle in the pool. After this time, the bean is removed. This is a hint
to the server. Default time is 600 seconds (10 minutes).
|===


[[fvypf]][[GSDPG00358]][[example-2]]

==== Example

[source,xml]
----
<bean-pool>
   <steady-pool-size>10</steady-pool-size>
   <resize-quantity>10</resize-quantity>
   <max-pool-size>100</max-pool-size>
   <pool-idle-timeout-in-seconds>600</pool-idle-timeout-in-seconds>
</bean-pool>
----

[[beard]][[GSDPG00097]][[cache]]

=== `cache`

Configures caching for web application components.

[[fvype]][[GSDPG00359]][[superelements-12]]

==== Superelements

link:#beayb[`glassfish-web-app`] (`glassfish-web.xml`)

[[fvypl]][[GSDPG00360]][[subelements-12]]

==== Subelements

The following table describes subelements for the `cache` element.

[[GSDPG855]][[sthref29]][[fvyrd]]


Table C-11 `cache` Subelements

[width="100%",cols="25%,12%,63%",options="header",]
|===
|Element |Required |Description
a|
link:#beare[`cache-helper`]


 |zero or more |Specifies a custom class that implements the CacheHelper
interface.

a|
link:#beasm[`default-helper`]


 |zero or one |Allows you to change the properties of the default,
built-in link:#beare[`cache-helper`] class.

a|
link:#beavx[`property` (with attributes)]


 |zero or more |Specifies a cache property, which has a name and a
value.

a|
link:#bearh[`cache-mapping`]


 |zero or more |Maps a URL pattern or a servlet name to its cacheability
constraints.
|===


[[fvypj]][[GSDPG00361]][[attributes-3]]

==== Attributes

The following table describes attributes for the `cache` element.

[[GSDPG856]][[sthref30]][[fvyrt]]


Table C-12 `cache` Attributes

[width="172%",cols="14%,46%,40%",options="header",]
|===
|Attribute |Default |Description
|`max-entries` |`4096` |(optional) Specifies the maximum number of
entries the cache can contain. Must be a positive integer.

|`timeout-in-seconds` |`30` |(optional) Specifies the maximum amount of
time in seconds that an entry can remain in the cache after it is
created or refreshed. Can be overridden by a link:#beayg[`timeout`]
element.

|`enabled` |`true` |(optional) Determines whether servlet and JSP
caching is enabled.
|===


[[fvypx]][[GSDPG00362]][[properties-1]]

==== Properties

The following table describes properties for the `cache` element.

[[GSDPG857]][[sthref31]][[fvyqr]]


Table C-13 `cache` Properties

[width="100%",cols="24%,23%,53%",options="header",]
|===
|Property |Default |Description
|`cacheClassName` |`com.sun.appserv.web.cache.LruCache` |Specifies the
fully qualified name of the class that implements the cache
functionality. See link:#fvyrn[Cache Class Names] for possible values.

|`MultiLRUSegmentSize` |`4096` |Specifies the number of entries in a
segment of the cache table that should have its own LRU (least recently
used) list. Applicable only if `cacheClassName` is set to
`com.sun.appserv.web.cache.MultiLruCache`.

|`MaxSize` |unlimited; `Long.MAX_VALUE` |Specifies an upper bound on the
cache memory size in bytes (KB or MB units). Example values are `32 KB`
or `2 MB`. Applicable only if `cacheClassName` is set to
`com.sun.appserv.web.cache.BoundedMultiLruCache`.
|===


[[fvyrn]][[GSDPG00363]][[cache-class-names]]

==== Cache Class Names

The following table lists possible values of the `cacheClassName`
property.

[[GSDPG858]][[sthref32]][[fvyph]]


Table C-14 `cacheClassName` Values

[width="100%",cols="31%,69%",options="header",]
|===
|Value |Description
|`com.sun.appserv.web.cache.LruCache` |A bounded cache with an LRU
(least recently used) cache replacement policy.

|`com.sun.appserv.web.cache.BaseCache` |An unbounded cache suitable if
the maximum number of entries is known.

|`com.sun.appserv.web.cache.MultiLruCache` |A cache suitable for a large
number of entries (>4096). Uses the `MultiLRUSegmentSize` property.

|`com.sun.appserv.web.cache.BoundedMultiLruCache` |A cache suitable for
limiting the cache size by memory rather than number of entries. Uses
the `MaxSize` property.
|===


[[beare]][[GSDPG00098]][[cache-helper]]

=== `cache-helper`

Specifies a class that implements the
com.sun.appserv.web.cache.CacheHelper interface.

[[fvyqy]][[GSDPG00364]][[superelements-13]]

==== Superelements

link:#beard[`cache`] (`glassfish-web.xml`)

[[fvyru]][[GSDPG00365]][[subelements-13]]

==== Subelements

The following table describes subelements for the `cache-helper`
element.

[[GSDPG859]][[sthref33]][[fvyql]]


Table C-15 `cache-helper` Subelements

[width="100%",cols="25%,12%,63%",options="header",]
|===
|Element |Required |Description
a|
link:#beavx[`property` (with attributes)]


 |zero or more |Specifies a property, which has a name and a value.
|===


[[fvyqu]][[GSDPG00366]][[attributes-4]]

==== Attributes

The following table describes attributes for the `cache-helper` element.

[[GSDPG860]][[sthref34]][[fvyrp]]


Table C-16 `cache-helper` Attributes

[width="181%",cols="8%,49%,43%",options="header",]
|===
|Attribute |Default |Description
|`name` |`default` |Specifies a unique name for the helper class, which
is referenced in the link:#bearh[`cache-mapping`] element.

|`class-name` |none |Specifies the fully qualified class name of the
cache helper, which must implement the com.sun.appserv.web.CacheHelper
interface.
|===


[[bearf]][[GSDPG00099]][[cache-helper-ref]]

=== `cache-helper-ref`

Specifies the `name` of the link:#beare[`cache-helper`] used by the
parent link:#bearh[`cache-mapping`] element.

[[fvypq]][[GSDPG00367]][[superelements-14]]

==== Superelements

link:#bearh[`cache-mapping`] (`glassfish-web.xml`)

[[fvyqs]][[GSDPG00368]][[subelements-14]]

==== Subelements

none - contains data

[[bearg]][[GSDPG00100]][[cache-idle-timeout-in-seconds]]

=== `cache-idle-timeout-in-seconds`

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. Default is 600.

Applies to stateful session beans and entity beans.

[[fvyqc]][[GSDPG00369]][[superelements-15]]

==== Superelements

link:#beara[`bean-cache`] (`glassfish-ejb-jar.xml`)

[[fvyqo]][[GSDPG00370]][[subelements-15]]

==== Subelements

none - contains data

[[bearh]][[GSDPG00101]][[cache-mapping]]

=== `cache-mapping`

Maps a URL pattern or a servlet name to its cacheability constraints.

[[fvyqi]][[GSDPG00371]][[superelements-16]]

==== Superelements

link:#beard[`cache`] (`glassfish-web.xml`)

[[fvyqn]][[GSDPG00372]][[subelements-16]]

==== Subelements

The following table describes subelements for the `cache-mapping`
element.

[[GSDPG861]][[sthref35]][[fvypt]]


Table C-17 `cache-mapping` Subelements

[width="100%",cols="20%,30%,50%",options="header",]
|===
|Element |Required |Description
a|
link:#beaxo[`servlet-name`]


 |requires one `servlet-name` or `url-pattern` |Contains the name of a
servlet.

a|
link:#beayl[`url-pattern`]


 |requires one `servlet-name` or `url-pattern` |Contains a servlet URL
pattern for which caching is enabled.

a|
link:#bearf[`cache-helper-ref`]


 |required if `dispatcher`, `timeout`, `refresh-field`, `http-method`,
`key-field`, and `constraint-field` are not used |Contains the `name` of
the link:#beare[`cache-helper`] used by the parent `cache-mapping`
element.

a|
link:#beasp[`dispatcher`]


 |zero or one if `cache-helper-ref` is not used |Contains a
comma-separated list of `RequestDispatcher` methods for which caching is
enabled.

a|
link:#beayg[`timeout`]


 |zero or one if `cache-helper-ref` is not used |Contains the
link:#bearh[`cache-mapping`] specific maximum amount of time in seconds
that an entry can remain in the cache after it is created or refreshed.

a|
link:#beawj[`refresh-field`]


 |zero or one if `cache-helper-ref` is not used |Specifies a field that
gives the application component a programmatic way to refresh a cached
entry.

a|
link:#beatk[`http-method`]


 |zero or more if `cache-helper-ref` is not used |Contains an HTTP
method that is eligible for caching.

a|
link:#beatz[`key-field`]


 |zero or more if `cache-helper-ref` is not used |Specifies a component
of the key used to look up and extract cache entries.

a|
link:#bease[`constraint-field`]


 |zero or more if `cache-helper-ref` is not used |Specifies a
cacheability constraint for the given `url-pattern` or `servlet-name`.
|===


[[beari]][[GSDPG00102]][[call-property]]

=== `call-property`

Specifies JAX-RPC property values that can be set on a
`javax.xml.rpc.Call` object before it is returned to the web service
client. The property names can be any properties supported by the
JAX-RPC `Call` implementation.

[[fvyri]][[GSDPG00373]][[superelements-17]]

==== Superelements

link:#beavt[`port-info`], link:#beaxk[`service-ref`]
(`glassfish-web.xml`, `glassfish-ejb-jar.xml`,
`glassfish-application-client.xml`)

[[fvyqp]][[GSDPG00374]][[subelements-17]]

==== Subelements

The following table describes subelements for the `call-property`
element.

[[GSDPG862]][[sthref36]][[fvyrw]]


Table C-18 `call-property` subelements

[width="100%",cols="24%,12%,64%",options="header",]
|===
|Element |Required |Description
a|
link:#beavf[`name`]


 |only one |Specifies the name of the entity.
a|
link:#beayo[`value`]


 |only one |Specifies the value of the entity.
|===


[[bearj]][[GSDPG00103]][[caller-propagation]]

=== `caller-propagation`

Specifies whether the target accepts propagated caller identities. The
values are `NONE`, `SUPPORTED`, or `REQUIRED`.

[[fvyqj]][[GSDPG00375]][[superelements-18]]

==== Superelements

link:#beaxb[`sas-context`] (`glassfish-ejb-jar.xml`)

[[fvyrb]][[GSDPG00376]][[subelements-18]]

==== Subelements

none - contains data

[[beark]][[GSDPG00104]][[cert-db]]

=== `cert-db`

Not implemented. Included for backward compatibility only. Attribute
values are ignored.

[[fvyqa]][[GSDPG00377]][[superelements-19]]

==== Superelements

link:#beaxf[`security`] (`sun-acc.xml`)

[[fvyre]][[GSDPG00378]][[subelements-19]]

==== Subelements

none

[[fvyrr]][[GSDPG00379]][[attributes-5]]

==== Attributes

The following table describes attributes for the `cert-db` element.

[[GSDPG863]][[sthref37]][[fvypo]]


Table C-19 `cert-db` attributes

[width="100%",cols="14%,11%,75%",options="header",]
|===
|Attribute |Default |Description
|`path` |none |Specifies the absolute path of the certificate database.

|`password` |none |Specifies the password to access the certificate
database.
|===


[[bearl]][[GSDPG00105]][[check-all-at-commit]]

=== `check-all-at-commit`

This element is not implemented. Do not use.

[[fvyrj]][[GSDPG00380]][[superelements-20]]

==== Superelements

link:#beasd[`consistency`] (`sun-cmp-mappings.xml`)

[[bearm]][[GSDPG00106]][[check-modified-at-commit]]

=== `check-modified-at-commit`

Checks concurrent modification of fields in modified beans at commit
time.

[[fvyqf]][[GSDPG00381]][[superelements-21]]

==== Superelements

link:#beasd[`consistency`] (`sun-cmp-mappings.xml`)

[[fvyqz]][[GSDPG00382]][[subelements-20]]

==== Subelements

none - element is present or absent

[[bearn]][[GSDPG00107]][[check-version-of-accessed-instances]]

=== `check-version-of-accessed-instances`

Checks the version column of the modified beans.

Version consistency allows the bean state to be cached between
transactions instead of read from a database. The bean state is verified
by primary key and version column values. This occurs during a custom
query (for dirty instances only) or commit (for both clean and dirty
instances).

The version column must be a numeric type, and must be in the primary
table. You must provide appropriate update triggers for this column.

[[fvyqt]][[GSDPG00383]][[superelements-22]]

==== Superelements

link:#beasd[`consistency`] (`sun-cmp-mappings.xml`)

[[fvypp]][[GSDPG00384]][[subelements-21]]

==== Subelements

The following table describes subelements for the
`check-version-of-accessed-instances` element.

[[GSDPG864]][[sthref38]][[fvyrq]]


Table C-20 `check-version-of-accessed-instances` Subelements

[width="100%",cols="33%,11%,56%",options="header",]
|===
|Element |Required |Description
a|
link:#bearz[`column-name`]


 |only one |Specifies the name of the version column.
|===


[[bearo]][[GSDPG00108]][[checkpoint-at-end-of-method]]

=== `checkpoint-at-end-of-method`

Specifies that the stateful session bean state is checkpointed, or
persisted, after the specified methods are executed. The
`availability-enabled` attribute of the parent link:#beass[`ejb`]
element must be set to `true`.

[[fvypr]][[GSDPG00385]][[superelements-23]]

==== Superelements

link:#beass[`ejb`] (`glassfish-ejb-jar.xml`)

[[fvyqe]][[GSDPG00386]][[subelements-22]]

==== Subelements

The following table describes subelements for the
`checkpoint-at-end-of-method` element.

[[GSDPG865]][[sthref39]][[fvyqx]]


Table C-21 `checkpoint-at-end-of-method` Subelements

[width="100%",cols="25%,13%,62%",options="header",]
|===
|Element |Required |Description
a|
link:#beauz[`method`]


 |one or more |Specifies a bean method.
|===


[[bearp]][[GSDPG00109]][[checkpointed-methods]]

=== `checkpointed-methods`

Deprecated. Supported for backward compatibility. Use
link:#bearo[`checkpoint-at-end-of-method`] instead.

[[fvyrk]][[GSDPG00387]][[superelements-24]]

==== Superelements

link:#beass[`ejb`] (`glassfish-ejb-jar.xml`)

[[bearq]][[GSDPG00110]][[class-loader]]

=== `class-loader`

Configures the class loader for the web module.

[[fvyrv]][[GSDPG00388]][[superelements-25]]

==== Superelements

link:#beayb[`glassfish-web-app`] (`glassfish-web.xml`)

[[fvyrh]][[GSDPG00389]][[subelements-23]]

==== Subelements

The following table describes subelements for the `class-loader`
element.

[[GSDPG866]][[sthref40]][[fvyqg]]


Table C-22 `class-loader` Subelements

[width="100%",cols="25%,12%,63%",options="header",]
|===
|Element |Required |Description
a|
link:#beavx[`property` (with attributes)]


 |zero or more |Specifies a property, which has a name and a value.
|===


[[fvyrl]][[GSDPG00390]][[attributes-6]]

==== Attributes

The following table describes attributes for the `class-loader` element.

[[GSDPG867]][[sthref41]][[fvyrs]]


Table C-23 `class-loader` Attributes

[width="172%",cols="17%,46%,37%",options="header",]
|===
|Attribute |Default |Description
|`extra-class-path` |null a|
(optional) Specifies a colon or semicolon separated list of additional
classpaths for this web module. Paths can be absolute or relative to the
web module's root, for example:

[source]
----
extra-class-path="WEB-INF/lib/extra/extra.jar"
----

|`delegate` |`true` a|
(optional) If `true`, the web module follows the standard class loader
delegation model and delegates to its parent class loader first before
looking in the local class loader. You must set this to `true` for a web
module that accesses EJB components or that acts as a web service client
or endpoint.

If `false`, the web module follows the delegation model specified in the
Servlet specification and looks in its class loader before looking in
the parent class loader. It's safe to set this to `false` only for a web
module that does not interact with any other modules.

For a number of packages, including `java.*` and `javax.*`, symbol
resolution is always delegated to the parent class loader regardless of
the delegate setting. This prevents applications from overriding core
Java runtime classes or changing the API versions of specifications that
are part of the Jakarta EE platform.

|`dynamic-reload-interval` | |(optional) Not implemented. Included
for backward compatibility with previous Oracle Web Server versions.
|===



[NOTE]
====
If the `delegate` attribute is set to `false`, the class loader
delegation behavior complies with the Servlet 2.4 specification, section
9.7.2. If set to its default value of `true`, classes and resources
residing in container-wide library JAR files are loaded in preference to
classes and resources packaged within the WAR file.

Portable programs that use this element should not be packaged with any
classes or interfaces that are a part of the Jakarta EE specification. The
behavior of a program that includes such classes or interfaces in its
WAR file is undefined.
====


[[gcfko]][[GSDPG00391]][[properties-2]]

==== Properties

The following table describes properties for the `class-loader` element.

[[GSDPG868]][[sthref42]][[gcfjs]]


Table C-24 `class-loader` Properties

[width="181%",cols="15%,49%,36%",options="header",]
|===
|Property |Default |Description
|`ignoreHiddenJarFiles` |`false` |If `true`, specifies that all JAR and
ZIP files in the `WEB-INF/lib` directory that start with a period (`.`)
are ignored by the class loader.
|===


[[bearr]][[GSDPG00111]][[client-container]]

=== `client-container`

Defines the {productName} specific configuration for the application
client container. This is the root element; there can only be one
`client-container` element in a `sun-acc.xml` file. See
link:dd-files.html#beaqp[The sun-acc.xml File].

[[fvypv]][[GSDPG00392]][[superelements-26]]

==== Superelements

none

[[fvypk]][[GSDPG00393]][[subelements-24]]

==== Subelements

The following table describes subelements for the `client-container`
element.

[[GSDPG869]][[sthref43]][[fvypm]]


Table C-25 `client-container` Subelements

[width="100%",cols="28%,12%,60%",options="header",]
|===
|Element |Required |Description
a|
link:#beaye[`target-server`]


 |one or more a|
Specifies the IIOP listener for the target server. Also specifies IIOP
endpoints used for load balancing. If the {productName} instance on
which the application client is deployed participates in a cluster,
{productName} finds all currently active IIOP endpoints in the
cluster automatically. However, a client should have at least two
endpoints specified for bootstrapping purposes, in case one of the
endpoints has failed.

A listener or endpoint is in the form host`:`port, where the host is an
IP address or host name, and the port specifies the port number.

a|
link:#beaqy[`auth-realm`]


 |zero or one |Specifies the optional configuration for JAAS
authentication realm.

a|
link:#bears[`client-credential`]


 |zero or one |Specifies the default client credential that is sent to
the server.

a|
link:#beauj[`log-service`]


 |zero or one |Specifies the default log file and the severity level of
the message.

a|
link:#beauy[`message-security-config`]


 |zero or more |Specifies configurations for message security providers.

a|
link:#beavx[`property` (with attributes)]


 |zero or more |Specifies a property, which has a name and a value.
|===


[[fvyqq]][[GSDPG00394]][[attributes-7]]

==== Attributes

The following table describes attributes for the `client-container`
element.

[[GSDPG870]][[sthref44]][[fvyqb]]


Table C-26 `client-container` Attributes

[width="172%",cols="11%,46%,43%",options="header",]
|===
|Attribute |Default |Description
|`send-password` |`true` |If `true`, specifies that client
authentication credentials must be sent to the server. Without
authentication credentials, all access to protected EJB components
results in exceptions.
|===


[[fvyrm]][[GSDPG00395]][[properties-3]]

==== Properties

The following table describes properties for the `client-container`
element.

[[GSDPG871]][[sthref45]][[fvyqm]]


Table C-27 `client-container` Properties

[width="172%",cols="22%,46%,32%",options="header",]
|===
|Property |Default |Description
|`com.sun.appserv.iiop.endpoints` |none |Specifies a comma-separated
list of one or more IIOP endpoints used for load balancing. An IIOP
endpoint is in the form host`:`port, where the host is an IP address or
host name, and the port specifies the port number. Deprecated. Use
link:#beaye[`target-server`] elements instead.
|===


[[bears]][[GSDPG00112]][[client-credential]]

=== `client-credential`

Default client credentials that are sent to the server. If this element
is present, the credentials are automatically sent to the server,
without prompting the user for the user name and password on the client
side.

[[fvyqk]][[GSDPG00396]][[superelements-27]]

==== Superelements

link:#bearr[`client-container`] (`sun-acc.xml`)

[[fvyqd]][[GSDPG00397]][[subelements-25]]

==== Subelements

The following table describes subelements for the `client-credential`
element.

[[GSDPG872]][[sthref46]][[fvyro]]


Table C-28 `client-credential` subelement

[width="100%",cols="37%,14%,49%",options="header",]
|===
|Element |Required |Description
a|
link:#beavx[`property` (with attributes)]


 |zero or more |Specifies a property, which has a name and a value.
|===


[[fvyqv]][[GSDPG00398]][[attributes-8]]

==== Attributes

The following table describes attributes for the `client-credential`
element.

[[GSDPG873]][[sthref47]][[fvypi]]


Table C-29 `client-credential` attributes

[width="100%",cols="12%,14%,74%",options="header",]
|===
|Attribute |Default |Description
|`user-name` |none |The user name used to authenticate the Application
client container.

|`password` |none |The password used to authenticate the Application
client container.

|`realm` |default realm for the domain |(optional) The realm (specified
by name) where credentials are to be resolved.
|===


[[beart]][[GSDPG00113]][[cmp]]

`cmp`
~~~~~

Describes runtime information for a CMP entity bean object for EJB 1.1
and EJB 2.1 beans.

[[fvyrg]][[GSDPG00399]][[superelements-28]]

==== Superelements

link:#beass[`ejb`] (`glassfish-ejb-jar.xml`)

[[fvyqw]][[GSDPG00400]][[subelements-26]]

==== Subelements

The following table describes subelements for the `cmp` element.

[[GSDPG874]][[sthref48]][[fvypw]]


Table C-30 `cmp` Subelements

[width="100%",cols="22%,11%,67%",options="header",]
|===
|Element |Required |Description
a|
link:#beaun[`mapping-properties`]


 |zero or one |This element is not implemented.

a|
link:#beatq[`is-one-one-cmp`]


 |zero or one |This element is not implemented.

a|
link:#beavk[`one-one-finders`]


 |zero or one |Describes the finders for CMP 1.1 beans.

a|
link:#beavu[`prefetch-disabled`]


 |zero or one |Disables prefetching of entity bean states for the
specified query methods.
|===


[[bearu]][[GSDPG00114]][[cmp-field-mapping]]

=== `cmp-field-mapping`

The `cmp-field-mapping` element associates a field with one or more
columns to which it maps. The column can be from a bean's primary table
or any defined secondary table. If a field is mapped to multiple
columns, the column listed first in this element is used as a source for
getting the value from the database. The columns are updated in the
order they appear. There is one `cmp-field-mapping` element for each
`cmp-field` element defined in the `ejb-jar.xml` file.

[[fvypy]][[GSDPG00401]][[superelements-29]]

==== Superelements

link:#beasy[`entity-mapping`] (`sun-cmp-mappings.xml`)

[[fvyra]][[GSDPG00402]][[subelements-27]]

==== Subelements

The following table describes subelements for the `cmp-field-mapping`
element.

[[GSDPG875]][[sthref49]][[fvyqh]]


Table C-31 `cmp-field-mapping` Subelements

[width="100%",cols="15%,12%,73%",options="header",]
|===
|Element |Required |Description
a|
link:#beatd[`field-name`]


 |only one |Specifies the Java identifier of a field. This identifier
must match the value of the `field-name` subelement of the `cmp-field`
that is being mapped.

a|
link:#bearz[`column-name`]


 |one or more |Specifies the name of a column from the primary table, or
the qualified table name (TABLE.COLUMN) of a column from a secondary or
related table.

a|
link:#beawh[`read-only`]


 |zero or one |Specifies that a field is read-only.

a|
link:#beatc[`fetched-with`]


 |zero or one |Specifies the fetch group for this CMP field's mapping.
|===


[[bearv]][[GSDPG00115]][[cmp-resource]]

=== `cmp-resource`

Specifies the database to be used for storing CMP beans. For more
information about this element, see "link:application-development-guide/container_managed-persistence.html#GSDVG00154[Configuring the
CMP Resource]" in {productName} Application
Development Guide.

[[fvypz]][[GSDPG00403]][[superelements-30]]

==== Superelements

link:#beasx[`enterprise-beans`] (`glassfish-ejb-jar.xml`)

[[fvyrf]][[GSDPG00404]][[subelements-28]]

==== Subelements

The following table describes subelements for the `cmp-resource`
element.

[[GSDPG876]][[sthref50]][[fvyps]]


Table C-32 `cmp-resource` Subelements

[width="100%",cols="33%,12%,55%",options="header",]
|===
|Element |Required |Description
a|
link:#beatw[`jndi-name`]


 |only one |Specifies the absolute `jndi-name` of a JDBC resource.

a|
link:#beasn[`default-resource-principal`]


 |zero or one |Specifies the default runtime bindings of a resource
reference.

a|
link:#beavy[`property` (with subelements)]


 |zero or more |Specifies a property name and value. Used to configure
`PersistenceManagerFactory` properties.

a|
link:#beasi[`create-tables-at-deploy`]


 |zero or one |If `true`, specifies that database tables are created for
beans that are automatically mapped by the EJB container.

a|
link:#beasq[`drop-tables-at-undeploy`]


 |zero or one |If `true`, specifies that database tables that were
automatically created when the bean(s) were last deployed are dropped
when the bean(s) are undeployed.

a|
link:#beask[`database-vendor-name`]


 |zero or one |Specifies the name of the database vendor for which
tables can be created.

a|
link:#beaxd[`schema-generator-properties`]


 |zero or one |Specifies field-specific type mappings and allows you to
set the `use-unique-table-names` property.
|===


[[bearw]][[GSDPG00116]][[cmr-field-mapping]]

=== `cmr-field-mapping`

A container-managed relationship field has a name and one or more column
pairs that define the relationship. There is one `cmr-field-mapping`
element for each `cmr-field` element in the `ejb-jar.xml` file. A
relationship can also participate in a fetch group.

[[fvyrc]][[GSDPG00405]][[superelements-31]]

==== Superelements

link:#beasy[`entity-mapping`] (`sun-cmp-mappings.xml`)

[[fvypu]][[GSDPG00406]][[subelements-29]]

==== Subelements

The following table describes subelements for the `cmr-field-mapping`
element.

[[GSDPG877]][[sthref51]][[fvypn]]


Table C-33 `cmr-field-mapping` Subelements

[width="100%",cols="18%,12%,70%",options="header",]
|===
|Element |Required |Description
a|
link:#bearx[`cmr-field-name`]


 |only one |Specifies the Java identifier of a field. Must match the
value of the `cmr-field-name` subelement of the `cmr-field` that is
being mapped.

a|
link:#beasa[`column-pair`]


 |one or more |Specifies the pair of columns that determine the
relationship between two database tables.

a|
link:#beatc[`fetched-with`]


 |zero or one |Specifies the fetch group for this CMR field's
relationship.
|===


[[bearx]][[GSDPG00117]][[cmr-field-name]]

=== `cmr-field-name`

Specifies the Java identifier of a field. Must match the value of the
`cmr-field-name` subelement of the `cmr-field` element in the
`ejb-jar.xml` file.

[[fvyrx]][[GSDPG00407]][[superelements-32]]

==== Superelements

link:#bearw[`cmr-field-mapping`] (`sun-cmp-mappings.xml`)

[[fvyry]][[GSDPG00408]][[subelements-30]]

==== Subelements

none - contains data

[[beary]][[GSDPG00118]][[cmt-timeout-in-seconds]]

=== `cmt-timeout-in-seconds`

Overrides the Transaction Timeout setting of the Transaction Service for
an individual bean. The default value, `0`, specifies that the default
Transaction Service timeout is used. If positive, this value is used for
all methods in the bean that start a new container-managed transaction.
This value is not used if the bean joins a client transaction.

[[fvysf]][[GSDPG00409]][[superelements-33]]

==== Superelements

link:#beass[`ejb`] (`glassfish-ejb-jar.xml`)

[[fvysc]][[GSDPG00410]][[subelements-31]]

==== Subelements

none - contains data

[[bearz]][[GSDPG00119]][[column-name]]

=== `column-name`

Specifies the name of a column from the primary table, or the qualified
table name (TABLE.COLUMN) of a column from a secondary or related table.

[[fvyse]][[GSDPG00411]][[superelements-34]]

==== Superelements

link:#bearn[`check-version-of-accessed-instances`],
link:#bearu[`cmp-field-mapping`], link:#beasa[`column-pair`]
(`sun-cmp-mappings.xml`)

[[fvysb]][[GSDPG00412]][[subelements-32]]

==== Subelements

none - contains data

[[beasa]][[GSDPG00120]][[column-pair]]

=== `column-pair`

Specifies the pair of columns that determine the relationship between
two database tables. Each `column-pair` must contain exactly two
`column-name` subelements, which specify the column's names. The first
`column-name` element names the table that this bean is mapped to, and
the second `column-name` names the column in the related table.

[[fvysa]][[GSDPG00413]][[superelements-35]]

==== Superelements

link:#bearw[`cmr-field-mapping`], link:#beaxe[`secondary-table`]
(`sun-cmp-mappings.xml`)

[[fvysg]][[GSDPG00414]][[subelements-33]]

==== Subelements

The following table describes subelements for the `column-pair` element.

[[GSDPG878]][[sthref52]][[fvysh]]


Table C-34 `column-pair` Subelements

[width="100%",cols="14%,10%,76%",options="header",]
|===
|Element |Required |Description
a|
link:#bearz[`column-name`]


 |two |Specifies the name of a column from the primary table, or the
qualified table name (TABLE.COLUMN) of a column from a secondary or
related table.
|===


[[beasb]][[GSDPG00121]][[commit-option]]

=== `commit-option`

Specifies the commit option used on transaction completion. Valid values
for {productName} are `B` or `C`. Default value is `B`. Applies to
entity beans.


[NOTE]
====
Commit option A is not supported for this {productName} release.
====


[[fvyrz]][[GSDPG00415]][[superelements-36]]

==== Superelements

link:#beass[`ejb`] (`glassfish-ejb-jar.xml`)

[[fvysd]][[GSDPG00416]][[subelements-34]]

==== Subelements

none - contains data

[[gjjak]][[GSDPG00122]][[compatibility]]

=== `compatibility`

Specifies the {productName} release with which to be backward
compatible in terms of JAR visibility requirements for applications. The
current allowed value is `v2`, which refers to {productName} version
2 or {productName} version 9.1 or 9.1.1. Starting in Jakarta EE 6, the
Jakarta EE specification imposes stricter requirements than Jakarta EE 5 did
on which JAR files can be visible to various modules within an EAR file.
Setting this element to `v2` removes these Jakarta EE 6 and later
restrictions.

[[gjjaf]][[GSDPG00417]][[superelements-37]]

==== Superelements

link:#beaxw[`glassfish-application`] (`glassfish-application.xml`),
link:#beaya[`glassfish-ejb-jar`] (`glassfish-ejb-jar.xml`)

[[gjjag]][[GSDPG00418]][[subelements-35]]

==== Subelements

none - contains data

[[beasc]][[GSDPG00123]][[confidentiality]]

=== `confidentiality`

Specifies if the target supports privacy-protected messages. The values
are `NONE`, `SUPPORTED`, or `REQUIRED`.

[[fvysi]][[GSDPG00419]][[superelements-38]]

==== Superelements

link:#beayh[`transport-config`] (`glassfish-ejb-jar.xml`)

[[fvysk]][[GSDPG00420]][[subelements-36]]

==== Subelements

none - contains data

[[giygu]][[GSDPG00124]][[connector-connection-pool]]

=== `connector-connection-pool`

Defines a connector connection pool.

[[GSDPG879]][[sthref53]]


[[superelements-39]]
==== Superelements

link:#giyiy[`resources`] (`glassfish-resources.xml`)

[[GSDPG880]][[sthref54]]


[[subelements-37]]
==== Subelements

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

[[GSDPG881]][[sthref55]][[sthref56]]


Table C-35 `connector-connection-pool` Subelements

[width="100%",cols="25%,12%,63%",options="header",]
|===
|Element |Required |Description
a|
link:#beaso[`description`]


 |zero or one |Contains a text description of this element.

a|
link:#giyhy[`security-map`]


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

a|
link:#beavx[`property` (with attributes)]


 |zero or more |Specifies a property or a variable.
|===


[[GSDPG882]][[sthref57]]


[[attributes-9]]
==== Attributes

The following table describes attributes for the
`connector-connection-pool` element. Changing the following attributes
requires a server restart or the redeployment or disabling and
re-enabling of applications that refer to the resource:
`resource-adapter-name`, `connection-definition-name`,
`transaction-support`, `associate-with-thread`,
`lazy-connection-association`, and `lazy-connection-enlistment`.

[[GSDPG883]][[sthref58]][[sthref59]]


Table C-36 `connector-connection-pool` Attributes

[width="172%",cols="25%,46%,29%",options="header",]
|===
|Attribute |Default |Description
|`name` |none |Specifies the name of the connection pool. A
link:#giyhv[`connector-resource`] element's `pool-name` attribute refers
to this `name`.

|`resource-adapter-name` |none |Specifies the name of the deployed
connector module or application. 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` a|
(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 a|
(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` a|
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 associated thread pool. 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.
|===


[[GSDPG884]][[sthref60]]


[[properties-4]]
==== 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 Open Message Queue software. For a complete
list of the available properties (called administered object attributes
in the Message Queue software), see the link:../openmq/mq-admin-guide.html#GMADG[Open Message Queue
Administration Guide].

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

[[GSDPG885]][[sthref61]][[sthref62]]


Table C-37 `connector-connection-pool` Properties

[width="100%",cols="26%,11%,63%",options="header",]
|===
|Property |Default |Description
|`AddressList` |none |Specifies a list of host/port combinations of the
Message Queue software. For JMS resources of the Type
`jakarta.jms.TopicConnectionFactory` or
`jakarta.jms.QueueConnectionFactory`.

|`ClientId` |none a|
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
`jakarta.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
`jakarta.jms.TopicConnectionFactory` or
`jakarta.jms.QueueConnectionFactory`.

|`Password` |`guest` |Specifies the password for connecting to the
Message Queue software. For JMS resources of the Type
`jakarta.jms.TopicConnectionFactory` or
`jakarta.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.
|===



[NOTE]
====
All JMS administered object resource properties that worked with version
7 of the {productName} are supported for backward compatibility.
====


[[giyhv]][[GSDPG00125]][[connector-resource]]

=== `connector-resource`

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

[[GSDPG886]][[sthref63]]


[[superelements-40]]
==== Superelements

link:#giyiy[`resources`] (`glassfish-resources.xml`)

[[GSDPG887]][[sthref64]]


[[subelements-38]]
==== Subelements

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

[[GSDPG888]][[sthref65]][[sthref66]]


Table C-38 `connector-resource` Subelements

[width="100%",cols="25%,12%,63%",options="header",]
|===
|Element |Required |Description
a|
link:#beaso[`description`]


 |zero or one |Contains a text description of this element.
a|
link:#beavx[`property` (with attributes)]


 |zero or more |Specifies a property or a variable.
|===


[[GSDPG889]][[sthref67]]


[[attributes-10]]
==== Attributes

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

[[GSDPG890]][[sthref68]][[sthref69]]


Table C-39 `connector-resource` Attributes

[width="172%",cols="9%,46%,45%",options="header",]
|===
|Attribute |Default |Description
|`jndi-name` |none |Specifies the JNDI name for the resource.

|`pool-name` |none |Specifies the `name` of the associated
link:#giygu[`connector-connection-pool`].

|`object-type` |`user` a|
(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.
|===


[[beasd]][[GSDPG00126]][[consistency]]

=== `consistency`

Specifies container behavior in guaranteeing transactional consistency
of the data in the bean.

[[fvysj]][[GSDPG00421]][[superelements-41]]

==== Superelements

link:#beasy[`entity-mapping`] (`sun-cmp-mappings.xml`)

[[fvysl]][[GSDPG00422]][[subelements-39]]

==== Subelements

The following table describes subelements for the `consistency` element.

[[GSDPG891]][[sthref70]][[fvysn]]


Table C-40 `consistency` Subelements

[width="100%",cols="31%,21%,48%",options="header",]
|===
|Element |Required |Description
a|
link:#beavi[`none`]


 |exactly one subelement is required |No consistency checking occurs.

a|
link:#bearm[`check-modified-at-commit`]


 |exactly one subelement is required |Checks concurrent modification of
fields in modified beans at commit time.

a|
link:#beauh[`lock-when-loaded`]


 |exactly one subelement is required |Obtains an exclusive lock when the
data is loaded.

a|
link:#bearl[`check-all-at-commit`]


 | + |This element is not implemented. Do not use.

a|
link:#beaui[`lock-when-modified`]


 | + |This element is not implemented. Do not use.

a|
link:#bearn[`check-version-of-accessed-instances`]


 |exactly one subelement is required |Checks the version column of the
modified beans.
|===


[[bease]][[GSDPG00127]][[constraint-field]]

=== `constraint-field`

Specifies a cacheability constraint for the given
link:#beayl[`url-pattern`] or link:#beaxo[`servlet-name`].

All `constraint-field` constraints must pass for a response to be
cached. If there are `value` constraints, at least one of them must
pass.

[[fvysm]][[GSDPG00423]][[superelements-42]]

==== Superelements

link:#bearh[`cache-mapping`] (`glassfish-web.xml`)

[[fvyso]][[GSDPG00424]][[subelements-40]]

==== Subelements

The following table describes subelements for the `constraint-field`
element.

[[GSDPG892]][[sthref71]][[fvysp]]


Table C-41 `constraint-field` Subelements

[width="100%",cols="30%,13%,57%",options="header",]
|===
|Element |Required |Description
a|
link:#beasf[`constraint-field-value`]


 |zero or more |Contains a value to be matched to the input parameter
value.
|===


[[fvysq]][[GSDPG00425]][[attributes-11]]

==== Attributes

The following table describes attributes for the `constraint-field`
element.

[[GSDPG893]][[sthref72]][[fvysr]]


Table C-42 `constraint-field` Attributes

[width="100%",cols="18%,21%,61%",options="header",]
|===
|Attribute |Default |Description
|`name` |none |Specifies the input parameter name.

|`scope` |`request.parameter` |(optional) Specifies the scope from which
the input parameter is retrieved. Allowed values are
`context.attribute`, `request.header`, `request.parameter`,
`request.cookie`, `request.attribute`, and `session.attribute`.

|`cache-on-match` |`true` |(optional) If `true`, caches the response if
matching succeeds. Overrides the same attribute in a
link:#beasf[`constraint-field-value`] subelement.

|`cache-on-match-failure` |`false` |(optional) If `true`, caches the
response if matching fails. Overrides the same attribute in a
link:#beasf[`constraint-field-value`] subelement.
|===


[[beasf]][[GSDPG00128]][[constraint-field-value]]

=== `constraint-field-value`

Specifies a value to be matched to the input parameter value. The
matching is case sensitive. For example:

[source,xml]
----
<value match-expr="in-range">1-60</value>
----

[[fvyss]][[GSDPG00426]][[superelements-43]]

==== Superelements

link:#bease[`constraint-field`] (`glassfish-web.xml`)

[[fvyst]][[GSDPG00427]][[subelements-41]]

==== Subelements

none - contains data

[[fvysu]][[GSDPG00428]][[attributes-12]]

==== Attributes

The following table describes attributes for the
`constraint-field-value` element.

[[GSDPG894]][[sthref73]][[fvysv]]


Table C-43 `constraint-field-value` Attributes

[width="172%",cols="11%,46%,43%",options="header",]
|===
|Attribute |Default |Description
|`match-expr` |`equals` a|
(optional) Specifies the type of comparison performed with the value.
Allowed values are `equals`, `not-equals`, `greater`, `lesser`, and
`in-range`.

If `match-expr` is `greater` or `lesser`, the value must be a number. If
`match-expr` is `in-range`, the value must be of the form n1`-`n2, where
n1 and n2 are numbers.

|`cache-on-match` |`true` |(optional) If `true`, caches the response if
matching succeeds.

|`cache-on-match-failure` |`false` |(optional) If `true`, caches the
response if matching fails.
|===


[[beasg]][[GSDPG00129]][[context-root]]

=== `context-root`

Contains the web context root for the application or web application
that was packaged as a WAR file. Overrides the corresponding element in
the `application.xml` or `web.xml` file.

If the parent element is `java-web-start-access`, this element contains
the context root for the Java Web Start enabled application client
module. If none is specified, a default is generated; see
link:#gauax[`java-web-start-access`].

If you are setting up load balancing, web module context roots must be
unique within a server instance. See the link:ha-administration-guide.html#GSHAG[{productName} High Availability Administration Guide] for more
information about load balancing.

[[fvysx]][[GSDPG00429]][[superelements-44]]

==== Superelements

link:#beayr[`web`] (`glassfish-application.xml`),
link:#beayb[`glassfish-web-app`] (`glassfish-web.xml`),
link:#gauax[`java-web-start-access`]
(`glassfish-application-client.xml`)

[[fvysw]][[GSDPG00430]][[subelements-42]]

==== Subelements

none - contains data

[[beash]][[GSDPG00130]][[cookie-properties]]

=== `cookie-properties`

Specifies session cookie properties.


[NOTE]
====
If cookie settings are defined declaratively in the `web.xml` file, the
cookie properties defined here take precedence. If cookie settings are
defined programmatically using `javax.servlet.SessionCookieConfig`
methods, those cookie settings take precedence over the cookie
properties defined here.
====


[[fvysy]][[GSDPG00431]][[superelements-45]]

==== Superelements

link:#beaxp[`session-config`] (`glassfish-web.xml`)

[[fvysz]][[GSDPG00432]][[subelements-43]]

==== Subelements

The following table describes subelements for the `cookie-properties`
element.

[[GSDPG895]][[sthref74]][[fvytb]]


Table C-44 `cookie-properties` Subelements

[width="100%",cols="36%,14%,50%",options="header",]
|===
|Element |Required |Description
a|
link:#beavx[`property` (with attributes)]


 |zero or more |Specifies a property, which has a name and a value.
|===


[[fvyta]][[GSDPG00433]][[properties-5]]

==== Properties

The following table describes properties for the `cookie-properties`
element.

[[GSDPG896]][[sthref75]][[fvyte]]


Table C-45 `cookie-properties` Properties

[width="100%",cols="24%,13%,63%",options="header",]
|===
|Property |Default |Description
|`cookieName` |none |Specifies the cookie name.

|`cookiePath` |Context path at which the web module is installed.
|Specifies the pathname that is set when the cookie is created. The
browser sends the cookie if the pathname for the request contains this
pathname. If set to `/` (slash), the browser sends cookies to all URLs
served by {productName}. You can set the path to a narrower mapping
to limit the request URLs to which the browser sends cookies.

|`cookieMaxAgeSeconds` |none |Specifies the expiration time (in seconds)
after which the browser expires the cookie. If this is unset, the cookie
doesn't expire.

|`cookieDomain` |(unset) |Specifies the domain for which the cookie is
valid.

|`cookieComment` |none |Specifies the comment that identifies the
session tracking cookie in the cookie file.

|`cookieSecure` |`dynamic` a|
Sets the `Secure` attribute of any `JSESSIONID` cookies associated with
the web application. Allowed values are as follows:

* `true` — Sets `Secure` to `true`.
* `false` — Sets `Secure` to `false`.
* `dynamic` — The `JSESSIONID` cookie inherits the `Secure` setting of
the request that initiated the session.

To set the `Secure` attribute of a `JSESSIONIDSSO` cookie, use the
`ssoCookieSecure` `virtual-server` property. For details, see
link:reference-manual/create-virtual-server.html#GSRFM00062[`create-virtual-server`(1)].

|`cookieHttpOnly` |none |Specifies that the cookie is marked HTTP only.
Allowed values are `true` or `false`.
|===


[[beasi]][[GSDPG00131]][[create-tables-at-deploy]]

=== `create-tables-at-deploy`

Specifies whether database tables are created for beans that are
automatically mapped by the EJB container. If `true`, creates tables in
the database. If `false` (the default if this element is not present),
does not create tables.

This element can be overridden during deployment. See
"link:application-development-guide/container_managed-persistence.html#GSDVG00438[Generation Options for CMP]" in {productName} Application Development Guide.

[[fvytc]][[GSDPG00434]][[superelements-46]]

==== Superelements

link:#bearv[`cmp-resource`] (`glassfish-ejb-jar.xml`)

[[fvytd]][[GSDPG00435]][[subelements-44]]

==== Subelements

none - contains data

[[giyhr]][[GSDPG00132]][[custom-resource]]

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

[[GSDPG897]][[sthref76]]


[[superelements-47]]
==== Superelements

link:#giyiy[`resources`] (`glassfish-resources.xml`)

[[GSDPG898]][[sthref77]]


[[subelements-45]]
==== Subelements

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

[[GSDPG899]][[sthref78]][[sthref79]]


Table C-46 `custom-resource` Subelements

[width="100%",cols="25%,12%,63%",options="header",]
|===
|Element |Required |Description
a|
link:#beaso[`description`]


 |zero or one |Contains a text description of this element.
a|
link:#beavx[`property` (with attributes)]


 |zero or more |Specifies a property or a variable.
|===


[[GSDPG900]][[sthref80]]


[[attributes-13]]
==== Attributes

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

[[GSDPG901]][[sthref81]][[sthref82]]


Table C-47 `custom-resource` Attributes

[width="172%",cols="11%,46%,43%",options="header",]
|===
|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` a|
(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.
|===


[[beask]][[GSDPG00133]][[database-vendor-name]]

=== `database-vendor-name`

Specifies the name of the database vendor for which tables can be
created. Allowed values are `javadb`, `db2`, `mssql`, `mysql`, `oracle`,
`postgresql`, `pointbase`, `derby` (also for CloudScape), and `sybase`,
case-insensitive.

If no value is specified, a connection is made to the resource specified
by the link:#beatw[`jndi-name`] subelement of the
link:#bearv[`cmp-resource`] element, and the database vendor name is
read. If the connection cannot be established, or if the value is not
recognized, SQL-92 compliance is presumed.

This element can be overridden during deployment. See
"link:application-development-guide/container_managed-persistence.html#GSDVG00438[Generation Options for CMP]" in {productName} Application Development Guide.

[[fvytf]][[GSDPG00436]][[superelements-48]]

==== Superelements

link:#bearv[`cmp-resource`] (`glassfish-ejb-jar.xml`)

[[fvyti]][[GSDPG00437]][[subelements-46]]

==== Subelements

none - contains data

[[gaubj]][[GSDPG00134]][[debugging-enabled]]

=== `debugging-enabled`

Specifies whether the debugging servlet is enabled for this web service
endpoint. Allowed values are `true` (the default) and `false`.

[[gaubf]][[GSDPG00438]][[superelements-49]]

==== Superelements

link:#beayv[`webservice-endpoint`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`)

[[gaube]][[GSDPG00439]][[subelements-47]]

==== Subelements

none - contains data

[[beasl]][[GSDPG00135]][[default]]

=== `default`

Specifies that a field belongs to the default hierarchical fetch group,
and enables prefetching for a CMR field. To disable prefetching for
specific query methods, use a link:#beavu[`prefetch-disabled`] element
in the `glassfish-ejb-jar.xml` file.

[[fvytg]][[GSDPG00440]][[superelements-50]]

==== Superelements

link:#beatc[`fetched-with`] (`sun-cmp-mappings.xml`)

[[fvyth]][[GSDPG00441]][[subelements-48]]

==== Subelements

none - element is present or absent

[[beasm]][[GSDPG00136]][[default-helper]]

=== `default-helper`

Passes property values to the built-in `default`
link:#beare[`cache-helper`] class.

[[fvytj]][[GSDPG00442]][[superelements-51]]

==== Superelements

link:#beard[`cache`] (`glassfish-web.xml`)

[[fvytk]][[GSDPG00443]][[subelements-49]]

==== Subelements

The following table describes subelements for the `default-helper`
element.

[[GSDPG902]][[sthref83]][[fvytm]]


Table C-48 `default-helper` Subelements

[width="100%",cols="25%,12%,63%",options="header",]
|===
|Element |Required |Description
a|
link:#beavx[`property` (with attributes)]


 |zero or more |Specifies a property, which has a name and a value.
|===


[[fvytp]][[GSDPG00444]][[properties-6]]

==== Properties

The following table describes properties for the `default-helper`
element.

[[GSDPG903]][[sthref84]][[fvyto]]


Table C-49 `default-helper` Properties

[width="100%",cols="30%,21%,49%",options="header",]
|===
|Property |Default |Description
|`cacheKeyGeneratorAttrName` |Uses the built-in `default`
link:#beare[`cache-helper`] key generation, which concatenates the
servlet path with link:#beatz[`key-field`] values, if any. |The caching
engine looks in the `ServletContext` for an attribute with a name equal
to the value specified for this property to determine whether a
customized CacheKeyGenerator implementation is used. An application can
provide a customized key generator rather than using the `default`
helper. See "link:application-development-guide/webapps.html#GSDVG00254[The CacheKeyGenerator Interface]" in
{productName} Application Development Guide.
|===


[[beasn]][[GSDPG00137]][[default-resource-principal]]

=== `default-resource-principal`

Specifies the default principal (user) for the resource.

If this element is used in conjunction with a JMS Connection Factory
resource, the `name` and `password` subelements must be valid entries in
the Open Message Queue broker user repository. See
"link:../openmq/mq-admin-guide/security-services.html#GMADG00040[Configuring and Managing Security Services]" in Open
Message Queue Administration Guide for details.

[[fvytl]][[GSDPG00445]][[superelements-52]]

==== Superelements

link:#beaww[`resource-ref`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`, `glassfish-application-client.xml`);
link:#bearv[`cmp-resource`], link:#beaur[`mdb-connection-factory`]
(`glassfish-ejb-jar.xml`)

[[fvytn]][[GSDPG00446]][[subelements-50]]

==== Subelements

The following table describes subelements for the
`default-resource-principal` element.

[[GSDPG904]][[sthref85]][[fvytr]]


Table C-50 `default-resource-principal` Subelements

[width="100%",cols="11%,10%,79%",options="header",]
|===
|Element |Required |Description
a|
link:#beavf[`name`]


 |only one |Specifies the default resource principal name used to sign
on to a resource manager.

a|
link:#beavp[`password`]


 |only one |Specifies password of the default resource principal.
|===


[[beaso]][[GSDPG00138]][[description]]

=== `description`

Specifies a text description of the containing element.

[[fvytq]][[GSDPG00447]][[superelements-53]]

==== Superelements

link:#beavx[`property` (with attributes)], link:#gikqk[`valve`]
(`glassfish-web.xml`); link:#beaqs[`activation-config`],
link:#beauz[`method`] (`glassfish-ejb-jar.xml`);
link:#beaye[`target-server`] (`sun-acc.xml`);
link:#giyhw[`admin-object-resource`],
link:#giygu[`connector-connection-pool`],
link:#giyhv[`connector-resource`], link:#giyhr[`custom-resource`],
link:#giyin[`external-jndi-resource`],
link:#giyil[`jdbc-connection-pool`], link:#giyhm[`jdbc-resource`],
link:#giyik[`mail-resource`], link:#beavx[`property` (with attributes)],
link:#giyit[`resource-adapter-config`] (`glassfish-resources.xml`)

[[fvyts]][[GSDPG00448]][[subelements-51]]

==== Subelements

none - contains data

[[gkhtw]][[GSDPG00139]][[disable-nonportable-jndi-names]]

=== `disable-nonportable-jndi-names`

Because the EJB 3.1 specification defines portable EJB JNDI names, there
is less need for {productName} specific JNDI names. By default,
{productName} specific default JNDI names are applied automatically
for backward compatibility. To disable {productName} specific JNDI
names for an EJB module, set the value of this element to `true`. The
default is `false`.

[[gkhum]][[GSDPG00449]][[superelements-54]]

==== Superelements

link:#beaya[`glassfish-ejb-jar`] (`glassfish-ejb-jar.xml`)

[[gkhug]][[GSDPG00450]][[subelements-52]]

==== Subelements

none - contains data

[[beasp]][[GSDPG00140]][[dispatcher]]

=== `dispatcher`

Specifies a comma-separated list of `RequestDispatcher` methods for
which caching is enabled on the target resource. Valid values are
`REQUEST`, `FORWARD`, `INCLUDE`, and `ERROR` . If this element is not
specified, the default is `REQUEST`. See SRV.6.2.5 of the Servlet 2.4
specification for more information.

[[fvytt]][[GSDPG00451]][[superelements-55]]

==== Superelements

link:#bearh[`cache-mapping`] (`glassfish-web.xml`)

[[fvytv]][[GSDPG00452]][[subelements-53]]

==== Subelements

none - contains data

[[beasq]][[GSDPG00141]][[drop-tables-at-undeploy]]

=== `drop-tables-at-undeploy`

Specifies whether database tables that were automatically created when
the bean(s) were last deployed are dropped when the bean(s) are
undeployed. If `true`, drops tables from the database. If `false` (the
default if this element is not present), does not drop tables.

This element can be overridden during deployment. See
"link:application-development-guide/container_managed-persistence.html#GSDVG00438[Generation Options for CMP]" in {productName} Application Development Guide.

[[fvytu]][[GSDPG00453]][[superelements-56]]

==== Superelements

link:#bearv[`cmp-resource`] (`glassfish-ejb-jar.xml`)

[[fvytx]][[GSDPG00454]][[subelements-54]]

==== Subelements

none - contains data

[[beass]][[GSDPG00142]][[ejb]]

`ejb`
~~~~~

Defines runtime properties for a single enterprise bean within the
application. The subelements listed below apply to particular enterprise
beans as follows:

* All types of beans: `ejb-name`, `ejb-ref`, `resource-ref`,
`resource-env-ref`, `ior-security-config`, `gen-classes`, `jndi-name`,
`use-thread-pool-id`, `message-destination-ref`, `pass-by-reference`,
`service-ref`
* Stateless session beans: `bean-pool`, `webservice-endpoint`
* Stateful session beans: `bean-cache`, `webservice-endpoint`,
`checkpoint-at-end-of-method`
* Entity beans: `commit-option`, `bean-cache`, `bean-pool`, `cmp`,
`is-read-only-bean`, `refresh-period-in-seconds`,
`flush-at-end-of-method`
* Message-driven beans: `mdb-resource-adapter`,
`mdb-connection-factory`, `jms-durable-subscription-name`,
`jms-max-messages-load`, `bean-pool`

[[fvyty]][[GSDPG00455]][[superelements-57]]

==== Superelements

link:#beasx[`enterprise-beans`] (`glassfish-ejb-jar.xml`)

[[fvytw]][[GSDPG00456]][[subelements-55]]

==== Subelements

The following table describes subelements for the `ejb` element.

[[GSDPG905]][[sthref86]][[fvyuc]]


Table C-51 `ejb` Subelements

[width="100%",cols="35%,12%,53%",options="header",]
|===
|Element |Required |Description
a|
link:#beast[`ejb-name`]


 |only one |Matches the `ejb-name` in the corresponding `ejb-jar.xml`
file.

a|
link:#beatw[`jndi-name`]


 |zero or more |Specifies the absolute `jndi-name`.

a|
link:#beasu[`ejb-ref`]


 |zero or more |Maps the absolute JNDI name to the `ejb-ref` element in
the corresponding Jakarta EE XML file.

a|
link:#beaww[`resource-ref`]


 |zero or more |Maps the absolute JNDI name to the `resource-ref` in the
corresponding Jakarta EE XML file.

a|
link:#beawu[`resource-env-ref`]


 |zero or more |Maps the absolute JNDI name to the `resource-env-ref` in
the corresponding Jakarta EE XML file.

a|
link:#beaxk[`service-ref`]


 |zero or more |Specifies runtime settings for a web service reference.

a|
link:#gauao[`message-destination-ref`]


 |zero or more |Specifies the name of a physical message destination.

a|
link:#beavo[`pass-by-reference`]


 |zero or one |Specifies the passing method used by an enterprise bean
calling a remote interface method in another bean that is colocated
within the same process.

a|
link:#beart[`cmp`]


 |zero or one |Specifies runtime information for a container-managed
persistence (CMP) entity bean for EJB 1.1 and EJB 2.1 beans.

a|
link:#beavv[`principal`]


 |zero or one |Specifies the principal (user) name in an enterprise bean
that has the `run-as` role specified.

a|
link:#beaur[`mdb-connection-factory`]


 |zero or one |Specifies the connection factory associated with a
message-driven bean.

a|
link:#beatu[`jms-durable-subscription-name`]


 |zero or one |Specifies the durable subscription associated with a
message-driven bean.

a|
link:#beatv[`jms-max-messages-load`]


 |zero or one |Specifies the maximum number of messages to load into a
Java Message Service session at one time for a message-driven bean to
serve. The default is 1.

a|
link:#beato[`ior-security-config`]


 |zero or one |Specifies the security information for the IOR.

a|
link:#beatr[`is-read-only-bean`]


 |zero or one |Specifies that this entity bean is read-only.

a|
link:#beawk[`refresh-period-in-seconds`]


 |zero or one |Specifies the rate at which a read-only-bean must be
refreshed from the data source.

a|
link:#beasb[`commit-option`]


 |zero or one |Has valid values of B or C. Default value is B.

a|
link:#beary[`cmt-timeout-in-seconds`]


 |zero or one |Overrides the Transaction Timeout setting of the
Transaction Service for an individual bean.

a|
link:#beaym[`use-thread-pool-id`]


 |zero or one |Specifies the thread pool from which threads are selected
for remote invocations of this bean.

a|
link:#beath[`gen-classes`]


 |zero or one |Specifies all the generated class names for a bean.

a|
link:#bearb[`bean-pool`]


 |zero or one |Specifies the bean pool properties. Used for stateless
session beans, entity beans, and message-driven beans.

a|
link:#beara[`bean-cache`]


 |zero or one |Specifies the bean cache properties. Used only for
stateful session beans and entity beans.

a|
link:#beaus[`mdb-resource-adapter`]


 |zero or one |Specifies runtime configuration information for a
message-driven bean.

a|
link:#beayv[`webservice-endpoint`]


 |zero or more |Specifies information about a web service endpoint.

a|
link:#beatf[`flush-at-end-of-method`]


 |zero or one |Specifies the methods that force a database flush after
execution. Used for entity beans.

a|
link:#bearp[`checkpointed-methods`]


 |zero or one |Deprecated. Supported for backward compatibility. Use
link:#bearo[`checkpoint-at-end-of-method`] instead.

a|
link:#bearo[`checkpoint-at-end-of-method`]


 |zero or one |Specifies that the stateful session bean state is
checkpointed, or persisted, after the specified methods are executed.
The `availability-enabled` attribute must be set to `true`.

a|
link:#gkkia[`per-request-load-balancing`]


 |zero or one |Specifies the per-request load balancing behavior of EJB
2.x and 3.x remote client invocations on a stateless session bean.
|===


[[fvyuf]][[GSDPG00457]][[attributes-14]]

==== Attributes

The following table describes attributes for the `ejb` element.

[[GSDPG906]][[sthref87]][[fvyud]]


Table C-52 `ejb` Attributes

[width="181%",cols="16%,49%,35%",options="header",]
|===
|Attribute |Default |Description
|`availability-enabled` |`false` |(optional) If set to `true`, and if
availability is enabled in the EJB container, high-availability features
apply to this bean if it is a stateful session bean.
|===


[[fvytz]][[GSDPG00458]][[example-3]]

==== Example

[source,xml]
----
<ejb>
   <ejb-name>CustomerEJB</ejb-name>
   <jndi-name>customer</jndi-name>
   <resource-ref>
      <res-ref-name>jdbc/SimpleBank</res-ref-name>
      <jndi-name>jdbc/__default</jndi-name>
   </resource-ref>
   <is-read-only-bean>false</is-read-only-bean>
   <commit-option>B</commit-option>
   <bean-pool>
      <steady-pool-size>10</steady-pool-size>
      <resize-quantity>10</resize-quantity>
      <max-pool-size>100</max-pool-size>
      <pool-idle-timeout-in-seconds>600</pool-idle-timeout-in-seconds>
   </bean-pool>
   <bean-cache>
      <max-cache-size>100</max-cache-size>
      <resize-quantity>10</resize-quantity>
      <removal-timeout-in-seconds>3600</removal-timeout-in-seconds>
      <victim-selection-policy>LRU</victim-selection-policy>
   </bean-cache>
</ejb>
----

[[beast]][[GSDPG00143]][[ejb-name]]

=== `ejb-name`

In the `glassfish-ejb-jar.xml` file, matches the `ejb-name` in the
corresponding `ejb-jar.xml` file. The name must be unique among the
names of the enterprise beans in the same EJB JAR file.

There is no architected relationship between the `ejb-name` in the
deployment descriptor and the JNDI name that the deployer assigns to the
EJB component's home.

In the `sun-cmp-mappings.xml` file, specifies the `ejb-name` of the
entity bean in the `ejb-jar.xml` file to which the container-managed
persistence (CMP) bean corresponds.

[[fvyug]][[GSDPG00459]][[superelements-58]]

==== Superelements

link:#beass[`ejb`], link:#beauz[`method`] (`glassfish-ejb-jar.xml`);
link:#beasy[`entity-mapping`] (`sun-cmp-mappings.xml`)

[[fvyue]][[GSDPG00460]][[subelements-56]]

==== Subelements

none - contains data

[[beasu]][[GSDPG00144]][[ejb-ref]]

=== `ejb-ref`

Maps the `ejb-ref-name` in the corresponding Jakarta EE deployment
descriptor file `ejb-ref` entry to the absolute `jndi-name` of a
resource.

The `ejb-ref` element is used for the declaration of a reference to an
EJB's home. Applies to session beans or entity beans.

[[fvyub]][[GSDPG00461]][[superelements-59]]

==== Superelements

link:#beayb[`glassfish-web-app`] (`glassfish-web.xml`),
link:#beass[`ejb`] (`glassfish-ejb-jar.xml`),
link:#beaxx[`glassfish-application-client`]
(`glassfish-application-client.xml`)

[[fvyua]][[GSDPG00462]][[subelements-57]]

==== Subelements

The following table describes subelements for the `ejb-ref` element.

[[GSDPG907]][[sthref88]][[fvyui]]


Table C-53 `ejb-ref` Subelements

[width="100%",cols="26%,11%,63%",options="header",]
|===
|Element |Required |Description
a|
link:#beasv[`ejb-ref-name`]


 |only one |Specifies the `ejb-ref-name` in the corresponding Jakarta EE
deployment descriptor file `ejb-ref` entry.

a|
link:#beatw[`jndi-name`]


 |only one |Specifies the absolute `jndi-name` of a resource.
|===


[[beasv]][[GSDPG00145]][[ejb-ref-name]]

=== `ejb-ref-name`

Specifies the `ejb-ref-name` in the corresponding Jakarta EE deployment
descriptor file `ejb-ref` entry.

[[fvyuh]][[GSDPG00463]][[superelements-60]]

==== Superelements

link:#beasu[`ejb-ref`] (`glassfish-web.xml`, `glassfish-ejb-jar.xml`,
`glassfish-application-client.xml`)

[[fvyuj]][[GSDPG00464]][[subelements-58]]

==== Subelements

none - contains data

[[gaubh]][[GSDPG00146]][[eligible]]

=== `eligible`

Specifies whether the application client module is eligible to be Java
Web Start enabled. Allowed values are `true` (the default) and `false`.

[[gaubg]][[GSDPG00465]][[superelements-61]]

==== Superelements

link:#gauax[`java-web-start-access`]
(`glassfish-application-client.xml`)

[[gauaz]][[GSDPG00466]][[subelements-59]]

==== Subelements

none - contains data

[[beasw]][[GSDPG00147]][[endpoint-address-uri]]

=== `endpoint-address-uri`

Specifies the relative path combined with the web server root to form
the fully qualified endpoint address for a web service endpoint. This is
a required element for EJB endpoints and an optional element for servlet
endpoints.

For servlet endpoints, this value is relative to the web application
context root. For EJB endpoints, the URI is relative to root of the web
server (the first portion of the URI is a context root). The context
root portion must not conflict with the context root of any web
application deployed to the same web server.

In all cases, this value must be a fixed pattern (no "`*`' allowed).

If the web service endpoint is a servlet that implements only a single
endpoint and has only one `url-pattern`, it is not necessary to set this
value, because the web container derives it from the `web.xml` file.

[[fvyul]][[GSDPG00467]][[superelements-62]]

==== Superelements

link:#beayv[`webservice-endpoint`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`)

[[fvyum]][[GSDPG00468]][[subelements-60]]

==== Subelements

none - contains data

[[fvyuk]][[GSDPG00469]][[example-4]]

==== Example

If the web server is listening at `http://localhost:8080`, the following
`endpoint-address-uri`:

[source,xml]
----
<endpoint-address-uri>StockQuoteService/StockQuotePort</endpoint-address-uri>
----

results in the following target endpoint address:

[source]
----
http://localhost:8080/StockQuoteService/StockQuotePort
----

[[beasx]][[GSDPG00148]][[enterprise-beans]]

=== `enterprise-beans`

Specifies all the runtime properties for an EJB JAR file in the
application.

[[fvyun]][[GSDPG00470]][[superelements-63]]

==== Superelements

link:#beaya[`glassfish-ejb-jar`] (`glassfish-ejb-jar.xml`)

[[fvyuo]][[GSDPG00471]][[subelements-61]]

==== Subelements

The following table describes subelements for the `enterprise-beans`
element.

[[GSDPG908]][[sthref89]][[fvyut]]


Table C-54 `enterprise-beans` Subelements

[width="100%",cols="27%,12%,61%",options="header",]
|===
|Element |Required |Description
a|
link:#beavf[`name`]


 |zero or one |Specifies the name string.

a|
link:#beayk[`unique-id`]


 |zero or one |Specifies a unique system identifier. This data is
automatically generated and updated at deployment/redeployment. Do not
specify or edit this value.

a|
link:#beass[`ejb`]


 |zero or more |Defines runtime properties for a single enterprise bean
within the application.

a|
link:#beavq[`pm-descriptors`]


 |zero or one |Deprecated.

a|
link:#bearv[`cmp-resource`]


 |zero or one |Specifies the database to be used for storing
container-managed persistence (CMP) beans in an EJB JAR file.

a|
link:#beauu[`message-destination`]


 |zero or more |Specifies the name of a logical message destination.

a|
link:#beayt[`webservice-description`]


 |zero or more |Specifies a name and optional publish location for a web
service.

a|
link:#beavy[`property` (with subelements)]


 |zero or more |Specifies a property or a variable.
|===


[[fvyux]][[GSDPG00472]][[example-5]]

==== Example

[source,xml]
----
<enterprise-beans>
 <ejb>
     <ejb-name>CustomerEJB</ejb-name>
     <jndi-name>customer</jndi-name>
     <resource-ref>
         <res-ref-name>jdbc/SimpleBank</res-ref-name>
         <jndi-name>jdbc/__default</jndi-name>
     </resource-ref>
     <is-read-only-bean>false</is-read-only-bean>
     <commit-option>B</commit-option>
     <bean-pool>
         <steady-pool-size>10</steady-pool-size>
        <resize-quantity>10</resize-quantity>
         <max-pool-size>100</max-pool-size>
         <pool-idle-timeout-in-seconds>600</pool-idle-timeout-in-seconds>
     </bean-pool>
     <bean-cache>
         <max-cache-size>100</max-cache-size>
         <resize-quantity>10</resize-quantity>
         <removal-timeout-in-seconds>3600</removal-timeout-in-seconds>
         <victim-selection-policy>LRU</victim-selection-policy>
     </bean-cache>
 </ejb>
</enterprise-beans>
----

[[beasy]][[GSDPG00149]][[entity-mapping]]

=== `entity-mapping`

Specifies the mapping a bean to database columns.

[[fvyus]][[GSDPG00473]][[superelements-64]]

==== Superelements

link:#beaxy[`sun-cmp-mapping`] (`sun-cmp-mappings.xml`)

[[fvyur]][[GSDPG00474]][[subelements-62]]

==== Subelements

The following table describes subelements for the `entity-mapping`
element.

[[GSDPG909]][[sthref90]][[fvyuz]]


Table C-55 `entity-mapping` Subelements

[width="100%",cols="21%,12%,67%",options="header",]
|===
|Element |Required |Description
a|
link:#beast[`ejb-name`]


 |only one |Specifies the name of the entity bean in the `ejb-jar.xml`
file to which the CMP bean corresponds.

a|
link:#beayd[`table-name`]


 |only one |Specifies the name of a database table. The table must be
present in the database schema file.

a|
link:#bearu[`cmp-field-mapping`]


 |one or more |Associates a field with one or more columns to which it
maps.

a|
link:#bearw[`cmr-field-mapping`]


 |zero or more |A container-managed relationship field has a name and
one or more column pairs that define the relationship.

a|
link:#beaxe[`secondary-table`]


 |zero or more |Describes the relationship between a bean's primary and
secondary table.

a|
link:#beasd[`consistency`]


 |zero or one |Specifies container behavior in guaranteeing
transactional consistency of the data in the bean.
|===


[[beasz]][[GSDPG00150]][[establish-trust-in-client]]

=== `establish-trust-in-client`

Specifies if the target is capable of authenticating a client. The
values are `NONE`, `SUPPORTED`, or `REQUIRED`.

[[fvyuq]][[GSDPG00475]][[superelements-65]]

==== Superelements

link:#beayh[`transport-config`] (`glassfish-ejb-jar.xml`)

[[fvyuy]][[GSDPG00476]][[subelements-63]]

==== Subelements

none - contains data

[[beata]][[GSDPG00151]][[establish-trust-in-target]]

=== `establish-trust-in-target`

Specifies if the target is capable of authenticating to a client. The
values are `NONE`, `SUPPORTED`, or `REQUIRED`.

[[fvyuu]][[GSDPG00477]][[superelements-66]]

==== Superelements

link:#beayh[`transport-config`] (`glassfish-ejb-jar.xml`)

[[fvyuv]][[GSDPG00478]][[subelements-64]]

==== Subelements

none - contains data

[[giyin]][[GSDPG00152]][[external-jndi-resource]]

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

[[GSDPG910]][[sthref91]]


[[superelements-67]]
==== Superelements

link:#giyiy[`resources`] (`glassfish-resources.xml`)

[[GSDPG911]][[sthref92]]


[[subelements-65]]
==== Subelements

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

[[GSDPG912]][[sthref93]][[sthref94]]


Table C-56 `external-jndi-resource` Subelements

[width="100%",cols="25%,12%,63%",options="header",]
|===
|Element |Required |Description
a|
link:#beaso[`description`]


 |zero or one |Contains a text description of this element.
a|
link:#beavx[`property` (with attributes)]


 |zero or more |Specifies a property or a variable.
|===


[[GSDPG913]][[sthref95]]


[[attributes-15]]
==== Attributes

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

[[GSDPG914]][[sthref96]][[sthref97]]


Table C-57 `external-jndi-resource` Attributes

[width="172%",cols="13%,46%,41%",options="header",]
|===
|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 a|
Specifies the fully qualified name of the factory class, which
implements javax.naming.spi.InitialContextFactory .

For more information about JNDI, see the link:application-development-guide.html#GSDVG[{productName} Application Development Guide].

|`object-type` |`user` a|
(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.
|===


[[beatc]][[GSDPG00153]][[fetched-with]]

=== `fetched-with`

Specifies the fetch group configuration for fields and relationships.
The `fetched-with` element has different allowed and default subelements
based on its parent element and the data types of the fields.

* If there is no `fetched-with` subelement of a
link:#bearu[`cmp-field-mapping`], and the data type is not BLOB, CLOB,
VARBINARY, LONGVARBINARY, or OTHER, `fetched-with` can have any valid
subelement. The default subelement is as follows:
+
[source,xml]
----
<fetched-with><default/></fetched-with>
----
* If there is no `fetched-with` subelement of a
link:#bearu[`cmp-field-mapping`], and the data type is BLOB, CLOB,
VARBINARY, LONGVARBINARY, or OTHER, `fetched-with` can have any valid
subelement except `<default/>`. The default subelement is as follows:
+
[source,xml]
----
<fetched-with><none/></fetched-with>
----
* If there is no `fetched-with` subelement of a
link:#bearw[`cmr-field-mapping`], `fetched-with` can have any valid
subelement. The default subelement is as follows:
+
[source,xml]
----
<fetched-with><none/></fetched-with>
----

Managed fields are multiple CMP or CMR fields that are mapped to the
same column. A managed field can have any `fetched-with` subelement
except `<default/>`. For additional information, see
"link:application-development-guide/container_managed-persistence.html#GSDVG00306[Managed Fields]" in {productName} Application Development Guide.

[[fvyuw]][[GSDPG00479]][[superelements-68]]

==== Superelements

link:#bearu[`cmp-field-mapping`], link:#bearw[`cmr-field-mapping`]
(`sun-cmp-mappings.xml`)

[[fvyup]][[GSDPG00480]][[subelements-66]]

==== Subelements

The following table describes subelements for the `fetched-with`
element.

[[GSDPG915]][[sthref98]][[fvzcz]]


Table C-58 `fetched-with` Subelements

[width="100%",cols="14%,21%,65%",options="header",]
|===
|Element |Required |Description
a|
link:#beasl[`default`]


 |exactly one subelement is required |Specifies that a CMP field belongs
to the default hierarchical fetch group, which means it is fetched any
time the bean is loaded from a database. Enables prefetching of a CMR
field.

a|
link:#beaub[`level`]


 |exactly one subelement is required |Specifies the level number of a
hierarchical fetch group.

a|
link:#beavg[`named-group`]


 |exactly one subelement is required |Specifies the name of an
independent fetch group.

a|
link:#beavi[`none`]


 |exactly one subelement is required |Specifies that this field or
relationship is placed into its own individual fetch group, which means
it is loaded from a database the first time it is accessed in this
transaction.
|===


[[beatd]][[GSDPG00154]][[field-name]]

=== `field-name`

Specifies the Java identifier of a field. This identifier must match the
value of the `field-name` subelement of the `cmp-field` element in the
`ejb-jar.xml` file.

[[fvzcm]][[GSDPG00481]][[superelements-69]]

==== Superelements

link:#bearu[`cmp-field-mapping`] (`sun-cmp-mappings.xml`)

[[fvyxs]][[GSDPG00482]][[subelements-67]]

==== Subelements

none - contains data

[[beate]][[GSDPG00155]][[finder]]

=== `finder`

Describes the finders for CMP 1.1 with a method name and query.

[[fvzao]][[GSDPG00483]][[superelements-70]]

==== Superelements

link:#beavk[`one-one-finders`] (`glassfish-ejb-jar.xml`)

[[fvzdc]][[GSDPG00484]][[subelements-68]]

==== Subelements

The following table describes subelements for the `finder` element.

[[GSDPG916]][[sthref99]][[fvyzu]]


Table C-59 `finder` Subelements

[width="100%",cols="31%,13%,56%",options="header",]
|===
|Element |Required |Description
a|
link:#beavb[`method-name`]


 |only one |Specifies the method name for the finder.

a|
link:#beawe[`query-params`]


 |zero or one |Specifies the query parameters for the CMP 1.1 finder.

a|
link:#beawb[`query-filter`]


 |zero or one |Specifies the query filter for the CMP 1.1 finder.

a|
link:#beawf[`query-variables`]


 |zero or one |Specifies variables in query expression for the CMP 1.1
finder.

a|
link:#beawd[`query-ordering`]


 |zero or one |Specifies the query ordering for the CMP 1.1 finder.
|===


[[beatf]][[GSDPG00156]][[flush-at-end-of-method]]

=== `flush-at-end-of-method`

Specifies the methods that force a database flush after execution.
Applicable to entity beans.

[[fvzcw]][[GSDPG00485]][[superelements-71]]

==== Superelements

link:#beass[`ejb`] (`glassfish-ejb-jar.xml`)

[[fvyza]][[GSDPG00486]][[subelements-69]]

==== Subelements

The following table describes subelements for the
`flush-at-end-of-method` element.

[[GSDPG917]][[sthref100]][[fvzba]]


Table C-60 `flush-at-end-of-method` Subelements

[width="100%",cols="26%,18%,56%",options="header",]
|===
|Element |Required |Description
a|
link:#beauz[`method`]


 |one or more |Specifies a bean method.
|===


[[beath]][[GSDPG00157]][[gen-classes]]

=== `gen-classes`

Specifies all the generated class names for a bean.


[NOTE]
====
This value is automatically generated by the server at deployment or
redeployment time. Do not specify it or change it after deployment.
====


[[fvyyh]][[GSDPG00487]][[superelements-72]]

==== Superelements

link:#beass[`ejb`] (`glassfish-ejb-jar.xml`)

[[fvzee]][[GSDPG00488]][[subelements-70]]

==== Subelements

The following table describes subelements for the `gen-classes` element.

[[GSDPG918]][[sthref101]][[fvzdo]]


Table C-61 `gen-classes` Subelements

[width="100%",cols="20%,11%,69%",options="header",]
|===
|Element |Required |Description
a|
link:#beawn[`remote-impl`]


 |zero or one |Specifies the fully-qualified class name of the generated
`EJBObject` impl class.

a|
link:#beaud[`local-impl`]


 |zero or one |Specifies the fully-qualified class name of the generated
`EJBLocalObject` impl class.

a|
link:#beawm[`remote-home-impl`]


 |zero or one |Specifies the fully-qualified class name of the generated
`EJBHome` impl class.

a|
link:#beauc[`local-home-impl`]


 |zero or one |Specifies the fully-qualified class name of the generated
`EJBLocalHome` impl class.
|===


[[beaxw]][[GSDPG00158]][[glassfish-application]]

=== `glassfish-application`

Defines the {productName} specific configuration for an application.
This is the root element; there can only be one `glassfish-application`
element in a `glassfish-application.xml` file. See
link:dd-files.html#beaqk[The glassfish-application.xml File].

[[fvzhn]][[GSDPG00489]][[superelements-73]]

==== Superelements

none

[[fvzgn]][[GSDPG00490]][[subelements-71]]

==== Subelements

The following table describes subelements for the
`glassfish-application` element.

[[GSDPG919]][[sthref102]][[fvzhl]]


Table C-62 `glassfish-application` Subelements

[width="100%",cols="28%,12%,60%",options="header",]
|===
|Element |Required |Description
a|
link:#beayr[`web`]


 |zero or more |Specifies the application's web tier configuration.

a|
link:#beavo[`pass-by-reference`]


 |zero or one |Determines whether EJB modules use pass-by-value or
pass-by-reference semantics.

a|
link:#beayk[`unique-id`]


 |zero or one |Contains the unique ID for the application.

a|
link:#beaxg[`security-role-mapping`]


 |zero or more |Maps a role in the corresponding Jakarta EE XML file to a
user or group.

a|
link:#beawi[`realm`]


 |zero or one |Specifies an authentication realm.

a|
link:#beasu[`ejb-ref`]


 |zero or more |Maps the absolute JNDI name to the `ejb-ref` in the
corresponding Jakarta EE XML file.

a|
link:#beaww[`resource-ref`]


 |zero or more |Maps the absolute JNDI name to the `resource-ref` in the
corresponding Jakarta EE XML file.

a|
link:#beawu[`resource-env-ref`]


 |zero or more |Maps the absolute JNDI name to the `resource-env-ref` in
the corresponding Jakarta EE XML file.

a|
link:#beaxk[`service-ref`]


 |zero or more |Specifies runtime settings for a web service reference.

a|
link:#gauao[`message-destination-ref`]


 |zero or more |Specifies the name of a physical message destination.

a|
link:#beauu[`message-destination`]


 |zero or more |Specifies the name of a logical message destination.

a|
link:#gjizj[`archive-name`]


 |zero or one |Specifies the name of the archive file.

a|
link:#gjjak[`compatibility`]


 |zero or one |Specifies the {productName} release with which to be
backward compatible in terms of JAR visibility requirements for
applications.

a|
link:#gkhtr[`keep-state`]


 |zero or one |Retains web sessions, stateful session bean instances,
and persistently created EJB timers across redeployments.

a|
link:#gkkfd[`version-identifier`]


 |zero or one |Contains version information for an application.
|===


[[beaxx]][[GSDPG00159]][[glassfish-application-client]]

=== `glassfish-application-client`

Defines the {productName} specific configuration for an application
client. This is the root element; there can only be one
`glassfish-application-client` element in a
`glassfish-application-client.xml` file. See link:dd-files.html#beaqo[The
glassfish-application-client.xml file].

[[fvzgq]][[GSDPG00491]][[superelements-74]]

==== Superelements

none

[[fvzja]][[GSDPG00492]][[subelements-72]]

==== Subelements

The following table describes subelements for the
`glassfish-application-client` element.

[[GSDPG920]][[sthref103]][[fvzjh]]


Table C-63 `glassfish-application-client` subelements

[width="100%",cols="28%,12%,60%",options="header",]
|===
|Element |Required |Description
a|
link:#beasu[`ejb-ref`]


 |zero or more |Maps the absolute JNDI name to the `ejb-ref` in the
corresponding Jakarta EE XML file.

a|
link:#beaww[`resource-ref`]


 |zero or more |Maps the absolute JNDI name to the `resource-ref` in the
corresponding Jakarta EE XML file.

a|
link:#beawu[`resource-env-ref`]


 |zero or more |Maps the absolute JNDI name to the `resource-env-ref` in
the corresponding Jakarta EE XML file.

a|
link:#beaxk[`service-ref`]


 |zero or more |Specifies runtime settings for a web service reference.

a|
link:#gauao[`message-destination-ref`]


 |zero or more |Specifies the name of a physical message destination.

a|
link:#beauu[`message-destination`]


 |zero or more |Specifies the name of a logical message destination.

a|
link:#gauax[`java-web-start-access`]


 |zero or one |Specifies changes to default Java Web Start parameters.

a|
link:#gkkfd[`version-identifier`]


 |zero or one |Contains version information for an application client.
|===


[[beaya]][[GSDPG00160]][[glassfish-ejb-jar]]

=== `glassfish-ejb-jar`

Defines the {productName} specific configuration for an EJB JAR file.
This is the root element; there can only be one `glassfish-ejb-jar`
element in a `glassfish-ejb-jar.xml` file. See
link:dd-files.html#beaqm[The glassfish-ejb-jar.xml File].

[[fvzhw]][[GSDPG00493]][[superelements-75]]

==== Superelements

none

[[fvzfv]][[GSDPG00494]][[subelements-73]]

==== Subelements

The following table describes subelements for the `glassfish-ejb-jar`
element.

[[GSDPG921]][[sthref104]][[fvzfu]]


Table C-64 `glassfish-ejb-jar` Subelements

[width="100%",cols="36%,12%,52%",options="header",]
|===
|Element |Required |Description
a|
link:#beaxg[`security-role-mapping`]


 |zero or more |Maps a role in the corresponding Jakarta EE XML file to a
user or group.

a|
link:#beasx[`enterprise-beans`]


 |only one |Describes all the runtime properties for an EJB JAR file in
the application.

a|
link:#gjjak[`compatibility`]


 |zero or one |Specifies the {productName} release with which to be
backward compatible in terms of JAR visibility requirements for
applications.

a|
link:#gkhtw[`disable-nonportable-jndi-names`]


 |zero or one |Disables {productName} specific JNDI names.

a|
link:#gkhtr[`keep-state`]


 |zero or one |Retains stateful session bean instances and persistently
created EJB timers across redeployments.

a|
link:#gkkfd[`version-identifier`]


 |zero or one |Contains version information for an EJB module.
|===


[[beayb]][[GSDPG00161]][[glassfish-web-app]]

=== `glassfish-web-app`

Defines {productName} specific configuration for a web module. This
is the root element; there can only be one `glassfish-web-app` element
in a `glassfish-web.xml` file. See link:dd-files.html#beaql[The
glassfish-web.xml File].

[[fvzgj]][[GSDPG00495]][[superelements-76]]

==== Superelements

none

[[fvzhr]][[GSDPG00496]][[subelements-74]]

==== Subelements

The following table describes subelements for the `glassfish-web-app`
element.

[[GSDPG922]][[sthref105]][[fvzgf]]


Table C-65 `glassfish-web-app` Subelements

[width="100%",cols="28%,12%,60%",options="header",]
|===
|Element |Required |Description
a|
link:#beasg[`context-root`]


 |zero or one |Contains the web context root for the web module.

a|
link:#beaxg[`security-role-mapping`]


 |zero or more |Maps roles to users or groups in the currently active
realm.

a|
link:#beaxm[`servlet`]


 |zero or more |Specifies a principal name for a servlet, which is used
for the `run-as` role defined in `web.xml`.

a|
link:#beatm[`idempotent-url-pattern`]


 |zero or more |Specifies a URL pattern for idempotent requests.

a|
link:#beaxp[`session-config`]


 |zero or one |Specifies session manager, session cookie, and other
session-related information.

a|
link:#beasu[`ejb-ref`]


 |zero or more |Maps the absolute JNDI name to the `ejb-ref` in the
corresponding Jakarta EE XML file.

a|
link:#beaww[`resource-ref`]


 |zero or more |Maps the absolute JNDI name to the `resource-ref` in the
corresponding Jakarta EE XML file.

a|
link:#beawu[`resource-env-ref`]


 |zero or more |Maps the absolute JNDI name to the `resource-env-ref` in
the corresponding Jakarta EE XML file.

a|
link:#beaxk[`service-ref`]


 |zero or more |Specifies runtime settings for a web service reference.

a|
link:#gauao[`message-destination-ref`]


 |zero or more |Specifies the name of a physical message destination.

a|
link:#beard[`cache`]


 |zero or one |Configures caching for web application components.

a|
link:#bearq[`class-loader`]


 |zero or one |Specifies class loader configuration information.

a|
link:#beatx[`jsp-config`]


 |zero or one |Specifies JSP configuration information.

a|
link:#beaue[`locale-charset-info`]


 |zero or one |Deprecated. Use the `parameter-encoding` subelement of
`glassfish-web-app` instead.

a|
link:#beavn[`parameter-encoding`]


 |zero or one |Determines the default request character encoding and how
the web container decodes parameters from forms according to a hidden
field value.

a|
link:#beavx[`property` (with attributes)]


 |zero or more |Specifies a property, which has a name and a value.

a|
link:#gikqk[`valve`]


 |zero or more |Specifies a custom valve.

a|
link:#beauu[`message-destination`]


 |zero or more |Specifies the name of a logical message destination.

a|
link:#beayt[`webservice-description`]


 |zero or more |Specifies a name and optional publish location for a web
service.

a|
link:#gkhtr[`keep-state`]


 |zero or one |Retains web sessions across redeployments.

a|
link:#gkkfd[`version-identifier`]


 |zero or one |Contains version information for a web application.
|===


[[fvzia]][[GSDPG00497]][[attributes-16]]

==== Attributes

The following table describes attributes for the `glassfish-web-app`
element.

[[GSDPG923]][[sthref106]][[fvzjf]]


Table C-66 `glassfish-web-app` Attributes

[width="172%",cols="17%,46%,37%",options="header",]
|===
|Attribute |Default |Description
|`error-url` |(blank) |(optional) Not implemented. Do not use.

|`httpservlet-``security-``provider` |none |(optional) Specifies the
`HttpServlet` message layer provider that the web container's servlet
`auth-constraint` processing calls.
|===


[[fvzgt]][[GSDPG00498]][[properties-7]]

==== Properties

The following table describes properties for the `glassfish-web-app`
element.

[[GSDPG924]][[sthref107]][[fvzim]]


Table C-67 `glassfish-web-app` Properties

[width="100%",cols="35%,23%,42%",options="header",]
|===
|Property |Default |Description
|`allowLinking` |`false` a|
If `true`, resources in this web application that are symbolic links are
served. You can also define this property for a virtual server. Web
applications on the virtual server that do not define this property use
the virtual server's value. For details, see
link:reference-manual/create-virtual-server.html#GSRFM00062[`create-virtual-server`(1)].

Caution: Setting this property to `true` on Windows systems exposes JSP
source code.

|`alternatedocroot_n` |none a|
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.

[source,xml]
----
<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 all the web applications on a specific
virtual server. For details, see
link:reference-manual/create-virtual-server.html#GSRFM00062[`create-virtual-server`(1)].

|`valve_n` |none a|
This property is deprecated. Use the link:#gikqk[`valve`] subelement
instead.

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 {productName} releases, or the
org.glassfish.web.valve.GlassFishValve interface from the current
{productName} release. For example:

[source,xml]
----
<property name="valve_1"
   value="org.glassfish.extension.Valve"/>
----

You can set this property for all the web applications on a specific
virtual server. For details, see
link:reference-manual/create-virtual-server.html#GSRFM00062[`create-virtual-server`(1)].

|`listener_n` |none a|
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,
org.apache.catalina.LifecycleListener, or
org.apache.catalina.InstanceListener interface. For example:

[source,xml]
----
<property name="listener_1"
   value="org.glassfish.extension.MyLifecycleListener"/>
----

You can set this property for all the web applications on a specific
virtual server. For details, see
link:reference-manual/create-virtual-server.html#GSRFM00062[`create-virtual-server`(1)].

|`crossContextAllowed` |`true` |If `true`, allows this web application
to access the contexts of other web applications using the
`ServletContext.``getContext()`method.

|`relativeRedirectAllowed` |`false` |If `true`, allows this web
application to send a relative URL to the client using
`HttpServletResponse.``sendRedirect()`, and instructs the web container
not to translate any relative URLs to fully qualified ones.

|`reuseSessionID` |`false` |If `true`, sessions generated for this web
application use the session ID specified in the request.

|`securePagesWithPragma` |`true` a|
Set this property to `false` to ensure that for this web application
file downloads using SSL work properly in Internet Explorer.

You can set this property for all the web applications on a specific
virtual server. For details, see
link:reference-manual/create-virtual-server.html#GSRFM00062[`create-virtual-server`(1)].

|`singleThreadedServletPoolSize` |`5` |Specifies the maximum number of
servlet instances allocated for each `SingleThreadModel` servlet in the
web application.

|`tempdir` a|
domain-dir`/generated/`app-name

or

domain-dir`/generated/`module-name

 |Specifies a temporary directory for use by this web module. This value
is used to construct the value of the `javax.servlet.context.``tempdir`
context attribute. Compiled JSP files are also placed in this directory.

|`useResponseCTForHeaders` |`false` |If `true`, response headers are
encoded using the response's charset instead of the default (UTF-8).
|===


[[giygy]][[GSDPG00162]][[group-map]]

=== `group-map`

Maps an EIS group to a group defined in the {productName} domain.

[[GSDPG925]][[sthref108]]


[[superelements-77]]
==== Superelements

link:#giyht[`work-security-map`] (`glassfish-resources.xml`)

[[giyid]][[GSDPG00499]][[subelements-75]]

==== Subelements

none

[[GSDPG926]][[sthref109]]


[[attributes-17]]
==== Attributes

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

[[GSDPG927]][[sthref110]][[sthref111]]


Table C-68 `group-map` Attributes

[width="181%",cols="13%,49%,38%",options="header",]
|===
|Attribute |Default |Description
|`eis-group` |none |Specifies an EIS group.

|`mapped-group` |none |Specifies a group defined in the {productName}
domain.
|===


[[beati]][[GSDPG00163]][[group-name]]

=== `group-name`

Specifies a group name in the current realm.

[[fvzak]][[GSDPG00500]][[superelements-78]]

==== Superelements

link:#beaxg[`security-role-mapping`] (`glassfish-application.xml`,
`glassfish-web.xml`, `glassfish-ejb-jar.xml`)

[[fvywm]][[GSDPG00501]][[subelements-76]]

==== Subelements

none - contains data

[[beatk]][[GSDPG00502]][[http-method]]

==== `http-method`

Specifies an HTTP method that is eligible for caching. The default is
`GET`.

[[fvzbq]][[GSDPG00317]][[superelements-79]]

===== Superelements

link:#bearh[`cache-mapping`] (`glassfish-web.xml`)

[[fvyyj]][[GSDPG00318]][[subelements-77]]

===== Subelements

none - contains data

[[beatm]][[GSDPG00164]][[idempotent-url-pattern]]

=== `idempotent-url-pattern`

Specifies a URL pattern for idempotent requests.

[[fvzaj]][[GSDPG00503]][[superelements-80]]

==== Superelements

link:#beayb[`glassfish-web-app`] (`glassfish-web.xml`)

[[fvzea]][[GSDPG00504]][[subelements-78]]

==== Subelements

none

[[fvyxx]][[GSDPG00505]][[attributes-18]]

==== Attributes

The following table describes attributes for the
`idempotent-url-pattern` element.

[[GSDPG928]][[sthref112]][[fvzca]]


Table C-69 `idempotent-url-pattern` Attributes

[width="181%",cols="12%,49%,39%",options="header",]
|===
|Attribute |Default |Description
|`url-pattern`
|none
|Specifies a URL pattern, which can contain wildcards.
The URL pattern must conform to the mappings specified in section SRV 11.2 of the Servlet 2.4 specification.

|`no-of-retries`
|`-1`
|(optional) Specifies the number of times the load balancer retries an idempotent request.
A value of `-1` indicates infinite retries.
|===


[[fvyxy]][[GSDPG00506]][[example-6]]

==== Example

The following example specifies that all requests for the URI
`sun-java/*` are idempotent.

[source,xml]
----
<idempotent-url-pattern url-pattern="sun_java/*" no-of-retries="10"/>
----

[[beatn]][[GSDPG00165]][[integrity]]

=== `integrity`

Specifies if the target supports integrity-protected messages. The
values are `NONE`, `SUPPORTED`, or `REQUIRED`.

[[fvzdj]][[GSDPG00507]][[superelements-81]]

==== Superelements

link:#beayh[`transport-config`] (`glassfish-ejb-jar.xml`)

[[fvzdv]][[GSDPG00508]][[subelements-79]]

==== Subelements

none - contains data

[[beato]][[GSDPG00166]][[ior-security-config]]

=== `ior-security-config`

Specifies the security information for the interoperable object
reference (IOR).

[[fvzbe]][[GSDPG00509]][[superelements-82]]

==== Superelements

link:#beass[`ejb`] (`glassfish-ejb-jar.xml`)

[[fvzbv]][[GSDPG00510]][[subelements-80]]

==== Subelements

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

[[GSDPG929]][[sthref113]][[fvyyk]]


Table C-70 `ior-security-config` Subelements

[width="100%",cols="20%,11%,69%",options="header",]
|===
|Element |Required |Description
a|
link:#beayh[`transport-config`]


 |zero or one |Specifies the security information for transport.

a|
link:#beaqw[`as-context`]


 |zero or one |Specifies the authentication mechanism used to
authenticate the client. If specified, it is `USERNAME_PASSWORD`.

a|
link:#beaxb[`sas-context`]


 |zero or one |Describes the sas-context fields.
|===


[[beatp]][[GSDPG00167]][[is-cache-overflow-allowed]]

=== `is-cache-overflow-allowed`

This element is deprecated. Do not use.

[[fvzcu]][[GSDPG00511]][[superelements-83]]

==== Superelements

link:#beara[`bean-cache`] (`glassfish-ejb-jar.xml`)

[[beatq]][[GSDPG00168]][[is-one-one-cmp]]

=== `is-one-one-cmp`

This element is not used.

[[fvyww]][[GSDPG00512]][[superelements-84]]

==== Superelements

link:#beart[`cmp`] (`glassfish-ejb-jar.xml`)

[[beatr]][[GSDPG00169]][[is-read-only-bean]]

=== `is-read-only-bean`

Specifies that this entity bean is a read-only bean if `true`. If this
element is absent, the default value of `false` is used.

[[fvzan]][[GSDPG00513]][[superelements-85]]

==== Superelements

link:#beass[`ejb`] (`glassfish-ejb-jar.xml`)

[[fvyvx]][[GSDPG00514]][[subelements-81]]

==== Subelements

none - contains data

[[beatt]][[GSDPG00170]][[java-method]]

=== `java-method`

Specifies a method.

[[fvyyw]][[GSDPG00515]][[superelements-86]]

==== Superelements

link:#beaut[`message`] (`glassfish-web.xml`, `glassfish-ejb-jar.xml`,
`glassfish-application-client.xml`)

[[fvyvo]][[GSDPG00516]][[subelements-82]]

==== Subelements

The following table describes subelements for the `java-method` element.

[[GSDPG930]][[sthref114]][[fvzdu]]


Table C-71 `java-method` Subelements

[width="100%",cols="30%,14%,56%",options="header",]
|===
|Element |Required |Description
a|
link:#beavb[`method-name`]


 |only one |Specifies a method name.

a|
link:#beavd[`method-params`]


 |zero or one |Specifies fully qualified Java type names of method
parameters.
|===


[[gauax]][[GSDPG00171]][[java-web-start-access]]

=== `java-web-start-access`

Specifies changes to default Java Web Start parameters for an embedded
or stand-alone application client module.

[[gauba]][[GSDPG00517]][[superelements-87]]

==== Superelements

link:#beaxx[`glassfish-application-client`]
(`glassfish-application-client.xml`)

[[gauav]][[GSDPG00518]][[subelements-83]]

==== Subelements

The following table describes subelements for the
`java-web-start-access` element.

[[GSDPG931]][[sthref115]][[gauaw]]


Table C-72 `java-web-start-access` subelements

[width="100%",cols="15%,11%,74%",options="header",]
|===
|Element |Required |Description
a|
link:#beasg[`context-root`]


 |zero or one a|
Contains the context root for the Java Web Start enabled application
client module. If none is specified, a default is generated.

The default for a web module is as follows:

[source]
----
http://host:port/app-name/relative-URI-to-appclient-jar
----

The default for a stand-alone application client module is as follows:

[source]
----
http://host:port/module-name
----

If the `module-name` is not specified during deployment, the name of the
EAR or JAR file without the extension is used. If the web module is not
in EAR or JAR file format, a name is generated and written to the server
log.

a|
link:#gaubh[`eligible`]


 |zero or one |Specifies whether the application client module is
eligible to be Java Web Start enabled. Allowed values are `true` (the
default) and `false`.

a|
link:#gbgdw[`vendor`]


 |zero or one |Specifies the name of the vendor as it appears in Java
Web Start download and launch screens. The default value is
`Application Client`.

a|
link:#gkhun[`jnlp-doc`]


 |zero or one |Specifies the name of a custom JNLP file. If none is
specified, a default JNLP file is generated.
|===


[[giyil]][[GSDPG00172]][[jdbc-connection-pool]]

=== `jdbc-connection-pool`

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

[[GSDPG932]][[sthref116]]


[[superelements-88]]
==== Superelements

link:#giyiy[`resources`] (`glassfish-resources.xml`)

[[GSDPG933]][[sthref117]]


[[subelements-84]]
==== Subelements

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

[[GSDPG934]][[sthref118]][[sthref119]]


Table C-73 `jdbc-connection-pool` Subelements

[width="100%",cols="25%,12%,63%",options="header",]
|===
|Element |Required |Description
a|
link:#beaso[`description`]


 |zero or one |Contains a text description of this element.
a|
link:#beavx[`property` (with attributes)]


 |zero or more |Specifies a property or a variable.
|===


[[GSDPG935]][[sthref120]]


[[attributes-19]]
==== Attributes

The following table describes attributes for the `jdbc-connection-pool`
element. Changing the following attributes requires a server restart or
the redeployment or disabling and re-enabling of applications that refer
to the resource: `datasource-classname`, `associate-with-thread`,
`lazy-connection-association`, and `lazy-connection-enlistment`.

[[GSDPG936]][[sthref121]][[sthref122]]


Table C-74 `jdbc-connection-pool` Attributes

[width="181%",cols="24%,49%,27%",options="header",]
|===
|Attribute |Default |Description
|`name` |none |Specifies the name of the connection pool. A
link:#giyhm[`jdbc-resource`] element's `pool-name` attribute refers to
this `name`.

|`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` a|
(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` a|
(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 a|
(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` a|
(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.

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

|`validation-classname` |none a|
(optional) Specifies the custom validation implementation class name.
This parameter is mandatory if `connection-validation-method` is set to
`custom-validation`. The classname provided must be accessible to the
{productName}. The specified class must implement the
org.glassfish.api.jdbc.ConnectionValidation interface.

{productName} provides the following custom validation class
templates for MSSQL, DB2, and Sybase databases. All of them implement
the org.glassfish.api.jdbc.ConnectionValidation interface.

* `org.glassfish.api.jdbc.MSSQLConnectionValidation`
* `org.glassfish.api.jdbc.DB2ConnectionValidation`
* `org.glassfish.api.jdbc.SybaseConnectionValidation`

|`init-sql` |none |(optional) Specifies an SQL string to be executed
whenever a connection is created (not reused) in 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 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 Jakarta 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` a|
(optional) Specifies the time interval within which a connection is
validated at most once. Minimizes the number of validation calls.

A value of zero implies that {productName} does not attempt to
minimize the number of validation requests by a connection. That is, a
value of zero disables this attribute. As a result, the same connection
is validated every time the application acquires the connection.

|`connection-leak-timeout-in-seconds` |`0` a|
(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.

|`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-leak-timeout-in-seconds` |`0` a|
(optional) Detects potential statement leaks by the application. A
statement that is not closed 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 `statement-leak-reclaim` to avoid
potential statement leaks from the application.

|`statement-leak-reclaim` |`false` |(optional) If `true`, the reclaim
of a statement after `statement-leak-timeout-in-seconds` occurs.

|`statement-timeout-in-seconds` |`-1` a|
(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` a|
(optional) Specifies whether connections are 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 associated thread pool. 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` a|
(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` a|
(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. The default is `false` to avoid breaking existing
applications.

|===


[[GSDPG937]][[sthref123]]


[[glassfish-server-properties]]
==== {productName} Properties

The following table describes properties for the `jdbc-connection-pool`
element that are specific to {productName}.

[[GSDPG938]][[sthref124]][[sthref125]]


Table C-75 `jdbc-connection-pool` Database Properties

[width="172%",cols="18%,46%,36%",options="header",]
|===
|Property |Default |Description
|`dynamic-reconfiguration-wait-timeout-in-seconds` |none a|
Specifies the timeout for dynamic reconfiguration of the pool.
In-progress connection requests must complete before this timeout
expires or they must be retried. New connection requests wait for this
timeout to expire before acquiring connections to the reconfigured pool.
If this property exists and has a positive value, it is enabled.

If this property is not set and pool reconfiguration results in pool
recreation, in-progress connection requests must be retried.

|`number-of-top-queries-to-report` |`10` a|
Specifies the number of most frequently used queries to display. For
example, the default value of `10` displays the top ten queries.

This property is disabled when `jdbc-connection-pool` monitoring is set
to `LOW` or `OFF`. It is enabled when `jdbc-connection-pool` monitoring
is set to `HIGH` and the `sql-trace-listeners` attribute is set.

|`time-to-keep-queries-in-minutes` |`5` a|
Specifies the time to retain queries in a cache before they are purged.

This property is disabled when `jdbc-connection-pool` monitoring is set
to `LOW` or `OFF`. It is enabled when `jdbc-connection-pool` monitoring
is set to `HIGH` and the `sql-trace-listeners` attribute is set.

|===


[[GSDPG939]][[sthref126]]


[[database-properties]]
==== Database 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 {productName}, 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.

[[GSDPG940]][[sthref127]][[sthref128]]


Table C-76 `jdbc-connection-pool` Database Properties

[width="100%",cols="19%,81%",options="header",]
|===
|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.
|===


[[giyhm]][[GSDPG00173]][[jdbc-resource]]

=== `jdbc-resource`

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

[[GSDPG941]][[sthref129]]


[[superelements-89]]
==== Superelements

link:#giyiy[`resources`] (`glassfish-resources.xml`)

[[GSDPG942]][[sthref130]]


[[subelements-85]]
==== Subelements

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

[[GSDPG943]][[sthref131]][[sthref132]]


Table C-77 `jdbc-resource` Subelements

[width="100%",cols="25%,12%,63%",options="header",]
|===
|Element |Required |Description
a|
link:#beaso[`description`]


 |zero or one |Contains a text description of this element.
a|
link:#beavx[`property` (with attributes)]


 |zero or more |Specifies a property or a variable.
|===


[[GSDPG944]][[sthref133]]


[[attributes-20]]
==== Attributes

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

[[GSDPG945]][[sthref134]][[sthref135]]


Table C-78 `jdbc-resource` Attributes

[width="172%",cols="9%,46%,45%",options="header",]
|===
|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
link:#giyil[`jdbc-connection-pool`].

|`object-type` |`user` a|
(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.
|===


[[beatu]][[GSDPG00174]][[jms-durable-subscription-name]]

=== `jms-durable-subscription-name`

Specifies the durable subscription associated with a message-driven bean
class. Only applies to the Java Message Service Topic Destination type,
and only when the message-driven bean deployment descriptor subscription
durability is Durable.

[[fvzdb]][[GSDPG00519]][[superelements-90]]

==== Superelements

link:#beass[`ejb`] (`glassfish-ejb-jar.xml`)

[[fvzdp]][[GSDPG00520]][[subelements-86]]

==== Subelements

none - contains data

[[beatv]][[GSDPG00175]][[jms-max-messages-load]]

=== `jms-max-messages-load`

Specifies the maximum number of messages to load into a Java Message
Service session at one time for a message-driven bean to serve. The
default is 1.

[[fvyzx]][[GSDPG00521]][[superelements-91]]

==== Superelements

link:#beass[`ejb`] (`glassfish-ejb-jar.xml`)

[[fvyxq]][[GSDPG00522]][[subelements-87]]

==== Subelements

none - contains data

[[beatw]][[GSDPG00176]][[jndi-name]]

=== `jndi-name`

Specifies the absolute `jndi-name` of a URL resource or a resource.

For entity beans and session beans, this value specifies the global JNDI
name of the `EJBHome` object. It is only needed if the entity or session
bean exposes a remote view.

For JMS message-driven beans, this is the JNDI name of the JMS resource
from which the message-driven bean consumes JMS messages. This
information is alternatively specified within the
link:#beaqs[`activation-config`] subelement of the
link:#beaus[`mdb-resource-adapter`] element. For more information about
JMS resources, see "link:application-development-guide/jms.html#GSDVG00020[Using the Java Message Service]" in
{productName} Application Development Guide.

[[fvyyy]][[GSDPG00523]][[superelements-92]]

==== Superelements

link:#beasu[`ejb-ref`], link:#beauu[`message-destination`],
link:#beawu[`resource-env-ref`], link:#beaww[`resource-ref`]
(`glassfish-web.xml`, `glassfish-ejb-jar.xml`,
`glassfish-application-client.xml`); link:#bearv[`cmp-resource`],
link:#beass[`ejb`], link:#beaur[`mdb-connection-factory`]
(`glassfish-ejb-jar.xml`)

[[fvywz]][[GSDPG00524]][[subelements-88]]

==== Subelements

none - contains data

[[gkhun]][[GSDPG00177]][[jnlp-doc]]

=== `jnlp-doc`

Contains the name of a custom JNLP file, which modifies the behavior of
a Java Web Start enabled application client module. If none is
specified, a default JNLP file is generated.

The value of this element is a relative path with the following format:

[source]
----
[path-to-JAR-in-EAR!]path-to-JNLP-in-JAR
----

The default path-to-JAR-in-EAR is the current application client JAR
file. For example, if the JNLP file is in the application client JAR
file at `custom/myInfo.jnlp`, the element value would look like this:

[source,xml]
----
<java-web-start-access>
   <jnlp-doc>custom/myInfo.jnlp</jnlp-doc>
</java-web-start-access>
----

If the application client is inside an EAR file, you can place the
custom JNLP file inside another JAR file in the EAR. For example, if the
JNLP file is in a JAR file at `other/myLib.jar`, the element value would
look like this, with an exclamation point (`!`) separating the path to
the JAR from the path in the JAR:

[source,xml]
----
<java-web-start-access>
   <jnlp-doc>other/myLib.jar!custom/myInfo.jnlp</jnlp-doc>
</java-web-start-access>
----

For information about the allowed contents of a custom JNLP file, see
"link:application-development-guide/java-clients.html#GSDVG00012[Developing Java Clients]" in {productName} Application Development Guide.

[[gkhuj]][[GSDPG00525]][[superelements-93]]

==== Superelements

link:#gauax[`java-web-start-access`]
(`glassfish-application-client.xml`)

[[gkhtm]][[GSDPG00526]][[subelements-89]]

==== Subelements

none - contains data

[[beatx]][[GSDPG00178]][[jsp-config]]

=== `jsp-config`

Specifies JSP configuration information.

[[fvywi]][[GSDPG00527]][[superelements-94]]

==== Superelements

link:#beayb[`glassfish-web-app`] (`glassfish-web.xml`)

[[fvzcs]][[GSDPG00528]][[subelements-90]]

==== Subelements

The following table describes subelements for the `jsp-config` element.

[[GSDPG946]][[sthref136]][[fvyzp]]


Table C-79 `jsp-config` Subelements

[width="100%",cols="37%,14%,49%",options="header",]
|===
|Element |Required |Description
a|
link:#beavx[`property` (with attributes)]


 |zero or more |Specifies a property, which has a name and a value.
|===


[[fvyzf]][[GSDPG00529]][[properties-8]]

==== Properties

The default property values are tuned for development of JSP files at
the cost of performance. To maximize performance, set `jsp-config`
properties to these non-default values:

* `development` - `false` (as an alternative, set to `true` and give
`modificationTestInterval` a large value)
* `mappedfile` - `false`
* `trimSpaces` - `true`
* `suppressSmap` - `true`
* `fork` - `false` (on Solaris)
* `classdebuginfo` - `false`

The following table describes properties for the `jsp-config` element.

[[GSDPG947]][[sthref137]][[fvzde]]


Table C-80 `jsp-config` Properties

[width="100%",cols="29%,11%,60%",options="header",]
|===
|Property |Default |Description
|`checkInterval` |`0` |If `development` is set to `false` and
`checkInterval` is greater than zero, background compilations are
enabled. The `checkInterval` is the time in seconds between checks to
see if a JSP file needs to be recompiled.

|`classdebuginfo` |`true` |Specifies whether the generated Java servlets
are compiled with the debug option set (`-g` for `javac`).

|`classpath` |created dynamically based on the current web application
|Specifies the classpath to use when compiling generated servlets.

|`compiler` |`javac` a|
Specifies the compiler Ant uses to compile JSP files. See the Ant
documentation for more information:

`http://antinstaller.sourceforge.net/manual/manual/`

|`compilerSourceVM` |Depends on {productName}'s Java runtime a|
Specifies the JDK release with which source compatibility of the
generated servlets is provided. Same as the `-source` release option of
`javac`.

For more information, see
`http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/javac.html#options`.

|`compilerTargetVM` |Depends on {productName}'s Java runtime a|
Specifies the Virtual Machine for the Java platform (JVM software)
version for which the servlet class files are generated. Same as the
`-target` release option of `javac`.

For more information, see
`http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/javac.html#options`.

|`defaultBufferNone` |`false` |If `true`, the default for the `buffer`
attribute of the `page` directive is `none`.

|`development` |`true` |If set to `true`, enables development mode,
which allows JSP files to be checked for modification. Specify the
frequency at which JSPs are checked using the `modificationTestInterval`
property.

|`dumpSmap` |`false` |If set to `true`, dumps SMAP information for JSR
45 debugging to a file. Set to `false` if `suppressSmap` is `true`.

|`enablePooling` |`true` |If set to `true`, tag handler pooling is
enabled.

|`enableTldValidation` |`false` |If set to `true`, all Tag Library
Descriptor (TLD) files referenced by the web application are validated
against their underlying schema or DTD file.

|`errorOnUseBeanInvalidClassAttribute` |`false` |If set to `true`,
issues an error when the value of the `class` attribute in a `useBean`
action is not a valid bean class.

|`fork` |`true` |Specifies that Ant forks the compiling of JSP files,
using a JVM machine separate from the one in which Tomcat is running.

|`genStrAsByteArray` |`true` |If `true`, text strings are generated as
bytes (encoded with the page encoding), if the page is not buffered.

|`genStrAsCharArray` |`false` |If set to `true`, generates text strings
as `char` arrays, which improves performance in some cases.

|`httpMethods` |`*` for all methods |Specifies a comma separated list of
HTTP methods supported by the `JspServlet`.

|`ieClassId` |`clsid:8AD9C840-``044E-11D1-B3E9-``00805F499D93`
|Specifies the Java plug-in COM class ID for Internet Explorer. Used by
the `<jsp:plugin>` tags.

|`ignoreJspFragmentErrors` |`false` |If set to `true`, instructs the
compiler to ignore any JSP precompilation errors pertaining to
statically included JSP segments that, despite not being top level JSP
files, use the `.jsp` or `.jspx` extension (instead of the recommended
`.jspf`).

|`initialCapacity` |`32` |Specifies the initial capacity of the
`HashMap` that maps JSP files to their corresponding servlets.

|`javaEncoding` |`UTF8` a|
Specifies the encoding for the generated Java servlet. This encoding is
passed to the Java compiler that is used to compile the servlet as well.
By default, the web container tries to use `UTF8`. If that fails, it
tries to use the `javaEncoding` value.

For encodings, see:

`http://docs.oracle.com/javase/7/docs/technotes/guides/intl/encoding.doc.html`

|`keepgenerated` |`true` with JDK 5 and before and for `jspc`, otherwise
`false` |If set to `true`, keeps the generated Java files. If `false`,
deletes the Java files.

|`mappedfile` |`true` |If set to `true`, generates static content with
one print statement per input line, to ease debugging.

|`modificationTestInterval` |`0` |Specifies the frequency in seconds at
which JSPs are checked for modification. A value of `0` causes the JSP
to be checked on every access. Used only if `development` is set to
`true`.

|`reload-interval` |`0` |Specifies the frequency in seconds at which JSP
files are checked for modifications. Setting this value to `0` checks
JSP files for modifications on every request. Setting this value to `-1`
disables checks for JSP modifications and JSP recompilation.

|`saveBytecode` |`true` for `jspc`, otherwise `false` |If `true`,
generated byte code is saved to `.class` files? This option is
meaningful only when the Java compiler API, JSR 199 (available with and
used as the default on Java 6) is used for `javac` compilations.

|`scratchdir` |The default work directory for the web application
|Specifies the working directory created for storing all the generated
code.

|`suppressSmap` |`false` |If set to `true`, generation of SMAP
information for JSR 45 debugging is suppressed.

|`trimSpaces` |`false` |If set to `true`, trims white spaces in template
text between actions or directives.

|`usePrecompiled` |`false` a|
If set to `true`, an accessed JSP file is not compiled. Its precompiled
servlet class is used instead.

It is assumed that JSP files have been precompiled, and their
corresponding servlet classes have been bundled in the web application's
`WEB-INF/lib` or `WEB-INF/classes` directory.

|`xpoweredBy` |`true` |If set to `true`, the X-Powered-By response
header is added by the generated servlet.
|===


[[gkhtr]][[GSDPG00179]][[keep-state]]

=== `keep-state`

If set to `true`, retains web sessions, stateful session bean instances,
and persistently created EJB timers across redeployments. The
`--keepstate` option of the link:reference-manual/redeploy.html#GSRFM00217[`redeploy`] subcommand
takes precedence. The default for both is `false`.

Some changes to an application between redeployments prevent this
feature from working properly. For example, do not change the set of
instance variables in the SFSB bean class.

For web applications, this feature is applicable only if in the
`glassfish-web-app.xml` file the `persistence-type` attribute of the
link:#beaxq[`session-manager`] element is `file`.

For stateful session bean instances, the persistence type without high
availability is set in the server (the `sfsb-persistence-type`
attribute) and must be set to `file`, which is the default and
recommended value.

If any active web session, SFSB instance, or EJB timer fails to be
preserved or restored, none of these will be available when the
redeployment is complete. However, the redeployment continues and a
warning is logged.

To preserve active state data, {productName} serializes the data and
saves it in memory. To restore the data, the class loader of the newly
redeployed application deserializes the data that was previously saved.

[[gkhto]][[GSDPG00530]][[superelements-95]]

==== Superelements

link:#beaxw[`glassfish-application`] (`glassfish-application.xml`),
link:#beayb[`glassfish-web-app`] (`glassfish-web-app.xml`),
link:#beaya[`glassfish-ejb-jar`] (`glassfish-ejb-jar.xml`)

[[gkhuk]][[GSDPG00531]][[subelements-91]]

==== Subelements

none - contains data

[[beatz]][[GSDPG00180]][[key-field]]

=== `key-field`

Specifies a component of the key used to look up and extract cache
entries. The web container looks for the named parameter, or field, in
the specified scope.

If this element is not present, the web container uses the Servlet Path
(the path section that corresponds to the servlet mapping that activated
the current request). See the Servlet 2.4 specification, section SRV
4.4, for details on the Servlet Path.

[[fvyvb]][[GSDPG00532]][[superelements-96]]

==== Superelements

link:#bearh[`cache-mapping`] (`glassfish-web.xml`)

[[fvzal]][[GSDPG00533]][[subelements-92]]

==== Subelements

none

[[fvzdn]][[GSDPG00534]][[attributes-21]]

==== Attributes

The following table describes attributes for the `key-field` element.

[[GSDPG948]][[sthref138]][[fvyyi]]


Table C-81 `key-field` Attributes

[width="181%",cols="51%,11%,38%",options="header",]
|===
|Attribute |Default |Description
|`name` |none |Specifies the input parameter name.

|`scope` |`request.parameter` |(optional) Specifies the scope from which
the input parameter is retrieved. Allowed values are
`context.attribute`, `request.header`, `request.parameter`,
`request.cookie`, `session.id`, and `session.attribute`.
|===


[[beaub]][[GSDPG00181]][[level]]

=== `level`

Specifies the name of a hierarchical fetch group. The name must be an
integer. Fields and relationships that belong to a hierarchical fetch
group of equal (or lesser) value are fetched at the same time. The value
of level must be greater than zero. Only one is allowed.

[[fvyvf]][[GSDPG00535]][[superelements-97]]

==== Superelements

link:#beatc[`fetched-with`] (`sun-cmp-mappings.xml`)

[[fvywq]][[GSDPG00536]][[subelements-93]]

==== Subelements

none - contains data

[[beauc]][[GSDPG00182]][[local-home-impl]]

=== `local-home-impl`

Specifies the fully-qualified class name of the generated `EJBLocalHome`
`impl` class.


[NOTE]
====
This value is automatically generated by the server at deployment or
redeployment time. Do not specify it or change it after deployment.
====


[[fvyzo]][[GSDPG00537]][[superelements-98]]

==== Superelements

link:#beath[`gen-classes`] (`glassfish-ejb-jar.xml`)

[[fvzah]][[GSDPG00538]][[subelements-94]]

==== Subelements

none - contains data

[[beaud]][[GSDPG00183]][[local-impl]]

=== `local-impl`

Specifies the fully-qualified class name of the generated
`EJBLocalObject` `impl` class.


[NOTE]
====
This value is automatically generated by the server at deployment or
redeployment time. Do not specify it or change it after deployment.
====


[[fvzcr]][[GSDPG00539]][[superelements-99]]

==== Superelements

link:#beath[`gen-classes`] (`glassfish-ejb-jar.xml`)

[[fvzai]][[GSDPG00540]][[subelements-95]]

==== Subelements

none - contains data

[[beaue]][[GSDPG00184]][[locale-charset-info]]

=== `locale-charset-info`

Deprecated. For backward compatibility only. Use the
link:#beavn[`parameter-encoding`] subelement of
link:#beayb[`glassfish-web-app`] instead. Specifies information about
the application's internationalization settings.

[[fvyvm]][[GSDPG00541]][[superelements-100]]

==== Superelements

link:#beayb[`glassfish-web-app`] (`glassfish-web.xml`)

[[fvzbi]][[GSDPG00542]][[subelements-96]]

==== Subelements

The following table describes subelements for the `locale-charset-info`
element.

[[GSDPG949]][[sthref139]][[fvyzd]]


Table C-82 `locale-charset-info` Subelements

[width="100%",cols="22%,12%,66%",options="header",]
|===
|Element |Required |Description
a|
link:#beauf[`locale-charset-map`]


 |one or more |Maps a locale and an agent to a character encoding.
Provided for backward compatibility. Used only for request processing,
and only if no `parameter-encoding` is defined.

a|
link:#beavn[`parameter-encoding`]


 |zero or one |Determines the default request character encoding and how
the web container decodes parameters from forms according to a hidden
field value.
|===


[[fvywh]][[GSDPG00543]][[attributes-22]]

==== Attributes

The following table describes attributes for the `locale-charset-info`
element.

[[GSDPG950]][[sthref140]][[fvzcd]]


Table C-83 `locale-charset-info` Attributes

[width="181%",cols="13%,49%,38%",options="header",]
|===
|Attribute |Default |Description
|`default-locale` |none |Although a value is required, the value is
ignored. Use the `default-charset` attribute of the
link:#beavn[`parameter-encoding`] element.
|===


[[beauf]][[GSDPG00185]][[locale-charset-map]]

=== `locale-charset-map`

Maps locales and agents to character encodings. Provided for backward
compatibility. Used only for request processing. Used only if the
character encoding is not specified in the request and cannot be derived
from the optional link:#beavn[`parameter-encoding`] element. For
encodings, see
`http://docs.oracle.com/javase/7/docs/technotes/guides/intl/encoding.doc.html`.

[[fvzbg]][[GSDPG00544]][[superelements-101]]

==== Superelements

link:#beaue[`locale-charset-info`] (`glassfish-web.xml`)

[[fvywg]][[GSDPG00545]][[subelements-97]]

==== Subelements

The following table describes subelements for the `locale-charset-map`
element.

[[GSDPG951]][[sthref141]][[fvyvl]]


Table C-84 `locale-charset-map` Subelements

[width="100%",cols="25%,14%,61%",options="header",]
|===
|Element |Required |Description
a|
link:#beaso[`description`]


 |zero or one |Specifies an optional text description of a mapping.
|===


[[fvyzn]][[GSDPG00546]][[attributes-23]]

==== Attributes

The following table describes attributes for the `locale-charset-map`
element.

[[GSDPG952]][[sthref142]][[fvzbk]]


Table C-85 `locale-charset-map` Attributes

[width="100%",cols="10%,10%,80%",options="header",]
|===
|Attribute |Default |Description
|`locale` |none |Specifies the locale name.

|`agent` |none |(optional) Specifies the type of client that interacts
with the {productName}. For a given locale, different agents can have
different preferred character encodings. The value of this attribute
must exactly match the value of the `user-agent` HTTP request header
sent by the client. See link:#fvzbb[Table C-86] for more information.

|`charset` |none |Specifies the character encoding to which the locale
maps.
|===


[[fvzct]][[GSDPG00547]][[example-agents]]

==== Example Agents

The following table specifies example `agent` attribute values.

[[GSDPG953]][[sthref143]][[fvzbb]]


Table C-86 Example `agent` Attribute Values

[width="100%",cols="38%,62%",options="header",]
|===
|Agent |`user-agent` Header and `agent` Attribute Value
|Internet Explorer 5.00 for Windows 2000
|`Mozilla/4.0 (compatible; MSIE 5.01; Windows NT 5.0)`

|Netscape 4.7.7 for Windows 2000
|`Mozilla/4.77 [en] (Windows NT 5.0; U)`

|Netscape 4.7 for Solaris |`Mozilla/4.7 [en] (X11; u; Sun OS 5.6 sun4u)`
|===


[[beaug]][[GSDPG00186]][[localpart]]

=== `localpart`

Specifies the local part of a QNAME.

[[fvzad]][[GSDPG00548]][[superelements-102]]

==== Superelements

link:#beaxj[`service-qname`], link:#beayx[`wsdl-port`]
(`glassfish-web.xml`, `glassfish-ejb-jar.xml`,
`glassfish-application-client.xml`)

[[fvyzb]][[GSDPG00549]][[subelements-98]]

==== Subelements

none - contains data

[[beauh]][[GSDPG00187]][[lock-when-loaded]]

=== `lock-when-loaded`

Places a database update lock on the rows corresponding to the bean
whenever the bean is loaded. How the lock is placed is
database-dependent. The lock is released when the transaction finishes
(commit or rollback). While the lock is in place, other database users
have read access to the bean.

[[fvyze]][[GSDPG00550]][[superelements-103]]

==== Superelements

link:#beasd[`consistency`] (`sun-cmp-mappings.xml`)

[[fvyyl]][[GSDPG00551]][[subelements-99]]

==== Subelements

none - element is present or absent

[[beaui]][[GSDPG00188]][[lock-when-modified]]

=== `lock-when-modified`

This element is not implemented. Do not use.

[[fvyyc]][[GSDPG00552]][[superelements-104]]

==== Superelements

link:#beasd[`consistency`] (`sun-cmp-mappings.xml`)

[[beauj]][[GSDPG00189]][[log-service]]

=== `log-service`

Specifies configuration settings for the log file.

[[fvyyv]][[GSDPG00553]][[superelements-105]]

==== Superelements

link:#bearr[`client-container`] (`sun-acc.xml`)

[[fvywo]][[GSDPG00554]][[subelements-100]]

==== Subelements

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

[[GSDPG954]][[sthref144]][[fvzdx]]


Table C-87 `log-service` subelement

[width="100%",cols="37%,15%,48%",options="header",]
|===
|Element |Required |Description
a|
link:#beavx[`property` (with attributes)]


 |zero or more |Specifies a property, which has a name and a value.
|===


[[fvyzl]][[GSDPG00555]][[attributes-24]]

==== Attributes

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

[[GSDPG955]][[sthref145]][[fvzbn]]


Table C-88 `log-service` attributes

[width="100%",cols="12%,32%,56%",options="header",]
|===
|Attribute |Default |Description
|`log-file` |your-ACC-dir`/logs/client.log` |(optional) Specifies the
file where the application client container logging information is
stored.

|`level` |`SEVERE` |(optional) Sets the base level of severity. Messages
at or above this setting get logged to the log file.
|===


[[beauk]][[GSDPG00190]][[login-config]]

=== `login-config`

Specifies the authentication configuration for an EJB web service
endpoint. Not needed for servlet web service endpoints. A servlet's
security configuration is contained in the `web.xml` file.

[[fvywb]][[GSDPG00556]][[superelements-106]]

==== Superelements

link:#beayv[`webservice-endpoint`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`)

[[fvyxg]][[GSDPG00557]][[subelements-101]]

==== Subelements

The following table describes subelements for the `login-config`
element.

[[GSDPG956]][[sthref146]][[fvzap]]


Table C-89 `login-config` subelements

[width="100%",cols="30%,15%,55%",options="header",]
|===
|Element |Required |Description
a|
link:#beaqx[`auth-method`]


 |only one |Specifies the authentication method.

a|
link:#beawi[`realm`]


 |zero or one |Specifies the name of the realm used to process all
authentication requests.
|===


[[giyik]][[GSDPG00191]][[mail-resource]]

=== `mail-resource`

Defines a Jakarta Mail (`jakarta.mail.Session`) resource.

[[GSDPG957]][[sthref147]]


[[superelements-107]]
==== Superelements

link:#giyiy[`resources`] (`glassfish-resources.xml`)

[[GSDPG958]][[sthref148]]


[[subelements-102]]
==== Subelements

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

[[GSDPG959]][[sthref149]][[sthref150]]


Table C-90 `mail-resource` Subelements

[width="100%",cols="25%,12%,63%",options="header",]
|===
|Element |Required |Description
a|
link:#beaso[`description`]


 |zero or one |Contains a text description of this element.
a|
link:#beavx[`property` (with attributes)]


 |zero or more |Specifies a property or a variable.
|===


[[GSDPG960]][[sthref151]]


[[attributes-25]]
==== Attributes

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

[[GSDPG961]][[sthref152]][[sthref153]]


Table C-91 `mail-resource` Attributes

[width="100%",cols="23%,21%,56%",options="header",]
|===
|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` a|
(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` a|
(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` a|
(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.
|===


[[GSDPG962]][[sthref154]]


[[properties-9]]
==== Properties

You can set properties for the `mail-resource` element and then get
these properties in a Jakarta Mail `Session` object later. Every property
name must start with a `mail-` prefix. The {productName} changes the
dash (`-`) character to a period (`.`) in the name of the property, then
saves the property to the `MailConfiguration` and Jakarta Mail `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 Jakarta Mail
Session object, first edit `glassfish-resources.xml` as follows:

[source,xml]
----
...
 <mail-resource jndi-name="mail/Session" ...>
     <property name="mail-password" value="adminadmin"/>
 </mail-resource>
 ...
----

After getting the Jakarta Mail `Session` object, get the `mail.password`
property to retrieve the value `adminadmin`, as follows:

[source,java]
----
String password = session.getProperty("mail.password");
----

For more information about Jakarta Mail properties, see
https://jakarta.ee/specifications/mail[Jakarta Mail API
Documentation] (`https://jakarta.ee/specifications/mail`).

[[beaum]][[GSDPG00192]][[manager-properties]]

=== `manager-properties`

Specifies session manager properties.

[[fvyyu]][[GSDPG00558]][[superelements-108]]

==== Superelements

link:#beaxq[`session-manager`] (`glassfish-web.xml`)

[[fvzcq]][[GSDPG00559]][[subelements-103]]

==== Subelements

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

[[GSDPG963]][[sthref155]][[fvyvh]]


Table C-92 `manager-properties` Subelements

[width="100%",cols="37%,14%,49%",options="header",]
|===
|Element |Required |Description
a|
link:#beavx[`property` (with attributes)]


 |zero or more |Specifies a property, which has a name and a value.
|===


[[fvzdg]][[GSDPG00560]][[properties-10]]

==== Properties

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

[[GSDPG964]][[sthref156]][[fvywk]]


Table C-93 `manager-properties` Properties

[width="100%",cols="25%,13%,62%",options="header",]
|===
|Property |Default |Description
|`reapIntervalSeconds` |`60` a|
Specifies the number of seconds between checks for expired sessions.
This is also the interval at which sessions are passivated if
`maxSessions` is exceeded.

If `persistenceFrequency` is set to `time-based`, active sessions are
stored at this interval.

To prevent data inconsistency, 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 the last few hits might be lost each time the
server is restarted.

Applicable only if the `persistence-type` attribute of the parent
link:#beaxq[`session-manager`] element is `file` or `replicated`.

|`maxSessions` |`-1` a|
Specifies the maximum number of sessions that are permitted in the
cache, or `-1` for no limit. After this, an attempt to create a new
session causes an `IllegalStateException` to be thrown.

If the `persistence-type` attribute of the parent
link:#beaxq[`session-manager`] element is `file` or `replicated`, the
session manager passivates sessions to the persistent store when this
maximum is reached.

|`sessionFilename` |empty string a|
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 module, one of the following:

domain-dir``/generated/jsp/``module-name

domain-dir``/generated/jsp/``app-name`/``module-name

By default, this property's value is set to an empty string, which
disables this property and does not preserve the session state.

Applicable only if the `persistence-type` attribute of the parent
link:#beaxq[`session-manager`] element is `memory`.

|`persistenceFrequency` |`web-method` a|
Specifies how often the session state is stored. Allowed values are as
follows:

* `web-method` - The session state is stored at the end of each web
request prior to sending a response back to the client. This mode
provides the best guarantee that the session state is fully updated in
case of failure.
* `time-based` - The session state is stored in the background at the
frequency set by `reapIntervalSeconds`. This mode provides less of a
guarantee that the session state is fully updated. However, it can
provide a significant performance improvement because the state is not
stored after each request.

Applicable only if the `persistence-type` attribute of the parent
link:#beaxq[`session-manager`] element is `replicated`.

|===


[[beaun]][[GSDPG00193]][[mapping-properties]]

=== `mapping-properties`

This element is not implemented.

[[fvywv]][[GSDPG00561]][[superelements-109]]

==== Superelements

link:#beart[`cmp`] (`glassfish-ejb-jar.xml`)

[[beauo]][[GSDPG00194]][[max-cache-size]]

=== `max-cache-size`

Specifies the maximum number of beans allowable in cache. A value of
zero indicates an unbounded cache. In reality, there is no hard limit.
The max-cache-size limit is just a hint to the cache implementation.
Default is 512.

Applies to stateful session beans and entity beans.

[[fvyyo]][[GSDPG00562]][[superelements-110]]

==== Superelements

link:#beara[`bean-cache`] (`glassfish-ejb-jar.xml`)

[[fvzbx]][[GSDPG00563]][[subelements-104]]

==== Subelements

none - contains data

[[beaup]][[GSDPG00195]][[max-pool-size]]

=== `max-pool-size`

Specifies the maximum number of bean instances in the pool. Values are
from 0 (1 for message-driven bean) to MAX_INTEGER. A value of 0 means
the pool is unbounded. Default is 64.

Applies to all beans.

[[fvzdw]][[GSDPG00564]][[superelements-111]]

==== Superelements

link:#bearb[`bean-pool`] (`glassfish-ejb-jar.xml`)

[[fvyxa]][[GSDPG00565]][[subelements-105]]

==== Subelements

none - contains data

[[beauq]][[GSDPG00196]][[max-wait-time-in-millis]]

=== `max-wait-time-in-millis`

This element is deprecated. Do not use.

[[fvyzg]][[GSDPG00566]][[superelements-112]]

==== Superelements

link:#bearb[`bean-pool`] (`glassfish-ejb-jar.xml`)

[[beaur]][[GSDPG00197]][[mdb-connection-factory]]

=== `mdb-connection-factory`

Specifies the connection factory associated with a message-driven bean.
Queue or Topic type must be consistent with the Java Message Service
Destination type associated with the message-driven bean class.

[[fvyzj]][[GSDPG00567]][[superelements-113]]

==== Superelements

link:#beass[`ejb`] (`glassfish-ejb-jar.xml`)

[[fvyxt]][[GSDPG00568]][[subelements-106]]

==== Subelements

The following table describes subelements for the
`mdb-connection-factory` element.

[[GSDPG965]][[sthref157]][[fvyxi]]


Table C-94 `mdb-connection-factory` Subelements

[width="100%",cols="38%,14%,48%",options="header",]
|===
|Element |Required |Description
a|
link:#beatw[`jndi-name`]


 |only one |Specifies the absolute `jndi-name`.

a|
link:#beasn[`default-resource-principal`]


 |zero or one |Specifies the default sign-on (name/password) to the
resource manager.
|===


[[beaus]][[GSDPG00198]][[mdb-resource-adapter]]

=== `mdb-resource-adapter`

Specifies runtime configuration information for a message-driven bean.

[[fvzdd]][[GSDPG00569]][[superelements-114]]

==== Superelements

link:#beass[`ejb`] (`glassfish-ejb-jar.xml`)

[[fvyyx]][[GSDPG00570]][[subelements-107]]

==== Subelements

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

[[GSDPG966]][[sthref158]][[fvyzh]]


Table C-95 `mdb-resource-adapter` subelements

[width="100%",cols="35%,14%,51%",options="header",]
|===
|Element |Required |Description
a|
link:#beawt[`resource-adapter-mid`]


 |zero or one |Specifies a resource adapter module ID.
a|
link:#beaqs[`activation-config`]


 |one or more |Specifies an activation configuration.
|===


[[beaut]][[GSDPG00199]][[message]]

=== `message`

Specifies the methods or operations to which message security
requirements apply.

[[fvzci]][[GSDPG00571]][[superelements-115]]

==== Superelements

link:#beauw[`message-security`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`, `glassfish-application-client.xml`)

[[fvyxc]][[GSDPG00572]][[subelements-108]]

==== Subelements

The following table describes subelements for the `message` element.

[[GSDPG967]][[sthref159]][[fvyyd]]


Table C-96 `message` Subelements

[width="100%",cols="30%,16%,54%",options="header",]
|===
|Element |Required |Description
a|
link:#beatt[`java-method`]


 |zero or one |Specifies the methods or operations to which message
security requirements apply.

a|
link:#beavl[`operation-name`]


 |zero or one |Specifies the WSDL name of an operation of a web service.
|===


[[beauu]][[GSDPG00200]][[message-destination]]

=== `message-destination`

Specifies the name of a logical `message-destination` defined within an
application. The `message-destination-name` matches the corresponding
`message-destination-name` in the corresponding Jakarta EE deployment
descriptor file. Use when the message destination reference in the
corresponding Jakarta EE deployment descriptor file specifies a
`message-destination-link` to a logical `message-destination`.

[[fvzaz]][[GSDPG00573]][[superelements-116]]

==== Superelements

link:#beayb[`glassfish-web-app`] (`glassfish-web.xml`),
link:#beasx[`enterprise-beans`] (`glassfish-ejb-jar.xml`),
link:#beaxx[`glassfish-application-client`]
(`glassfish-application-client.xml`)

[[fvyxn]][[GSDPG00574]][[subelements-109]]

==== Subelements

The following table describes subelements for the `message-destination`
element.

[[GSDPG968]][[sthref160]][[fvyzy]]


Table C-97 `message-destination` subelements

[width="100%",cols="29%,10%,61%",options="header",]
|===
|Element |Required |Description
a|
link:#beauv[`message-destination-name`]


 |only one |Specifies the name of a logical message destination defined
within the corresponding Jakarta EE deployment descriptor file.

a|
link:#beatw[`jndi-name`]


 |only one |Specifies the `jndi-name` of the associated entity.
|===


[[beauv]][[GSDPG00201]][[message-destination-name]]

=== `message-destination-name`

Specifies the name of a logical message destination defined within the
corresponding Jakarta EE deployment descriptor file.

[[fvzcj]][[GSDPG00575]][[superelements-117]]

==== Superelements

link:#beauu[`message-destination`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`, `glassfish-application-client.xml`)

[[fvzbo]][[GSDPG00576]][[subelements-110]]

==== Subelements

none - contains data

[[gauao]][[GSDPG00202]][[message-destination-ref]]

=== `message-destination-ref`

Directly binds a message destination reference to the JNDI name of a
`Queue`, `Topic`, or other physical destination. Use only when the
message destination reference in the corresponding Jakarta EE deployment
descriptor file does not specify a `message-destination-link` to a
logical `message-destination`.

[[gauam]][[GSDPG00577]][[superelements-118]]

==== Superelements

link:#beayb[`glassfish-web-app`] (`glassfish-web.xml`),
link:#beass[`ejb`] (`glassfish-ejb-jar.xml`),
link:#beaxx[`glassfish-application-client`]
(`glassfish-application-client.xml`)

[[gaual]][[GSDPG00578]][[subelements-111]]

==== Subelements

The following table describes subelements for the
`message-destination-ref` element.

[[GSDPG969]][[sthref161]][[gauar]]


Table C-98 `message-destination-ref` subelements

[width="100%",cols="34%,10%,56%",options="header",]
|===
|Element |Required |Description
a|
link:#gauat[`message-destination-ref-name`]


 |only one |Specifies the name of a physical message destination defined
within the corresponding Jakarta EE deployment descriptor file.

a|
link:#beatw[`jndi-name`]


 |only one |Specifies the `jndi-name` of the associated entity.
|===


[[gauat]][[GSDPG00203]][[message-destination-ref-name]]

=== `message-destination-ref-name`

Specifies the name of a physical message destination defined within the
corresponding Jakarta EE deployment descriptor file.

[[gauaj]][[GSDPG00579]][[superelements-119]]

==== Superelements

link:#gauao[`message-destination-ref`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`, `glassfish-application-client.xml`)

[[gauas]][[GSDPG00580]][[subelements-112]]

==== Subelements

none - contains data

[[beauw]][[GSDPG00204]][[message-security]]

=== `message-security`

Specifies message security requirements.

* If the grandparent element is link:#beayv[`webservice-endpoint`],
these requirements pertain to request and response messages of the
endpoint.
* If the grandparent element is link:#beavt[`port-info`], these
requirements pertain to the port of the referenced service.

[[fvzac]][[GSDPG00581]][[superelements-120]]

==== Superelements

link:#beaux[`message-security-binding`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`, `glassfish-application-client.xml`)

[[fvyve]][[GSDPG00582]][[subelements-113]]

==== Subelements

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

[[GSDPG970]][[sthref162]][[fvywy]]


Table C-99 `message-security` Subelements

[width="100%",cols="24%,12%,64%",options="header",]
|===
|Element |Required |Description
a|
link:#beaut[`message`]


 |one or more |Specifies the methods or operations to which message
security requirements apply.

a|
link:#beawp[`request-protection`]


 |zero or one |Defines the authentication policy requirements of the
application's request processing.

a|
link:#beawy[`response-protection`]


 |zero or one |Defines the authentication policy requirements of the
application's response processing.
|===


[[beaux]][[GSDPG00205]][[message-security-binding]]

=== `message-security-binding`

Specifies a custom authentication provider binding for a parent
link:#beayv[`webservice-endpoint`] or link:#beavt[`port-info`] element
in one or both of these ways:

* By binding to a specific provider
* By specifying the message security requirements enforced by the
provider

[[fvzbc]][[GSDPG00583]][[superelements-121]]

==== Superelements

link:#beayv[`webservice-endpoint`], link:#beavt[`port-info`]
(`glassfish-web.xml`, `glassfish-ejb-jar.xml`,
`glassfish-application-client.xml`)

[[fvyxv]][[GSDPG00584]][[subelements-114]]

==== Subelements

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

[[GSDPG971]][[sthref163]][[fvzcx]]


Table C-100 `message-security-binding` Subelements

[width="100%",cols="34%,15%,51%",options="header",]
|===
|Element |Required |Description
a|
link:#beauw[`message-security`]


 |zero or more |Specifies message security requirements.
|===


[[fvzbj]][[GSDPG00585]][[attributes-26]]

==== Attributes

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

[[GSDPG972]][[sthref164]][[fvzda]]


Table C-101 `message-security-binding` Attributes

[width="172%",cols="9%,46%,45%",options="header",]
|===
|Attribute |Default |Description
|`auth-layer` |none |Specifies the message layer at which authentication
is performed. The value must be `SOAP`.

|`provider-id` |none a|
(optional) Specifies the authentication provider used to satisfy
application-specific message security requirements.

If this attribute is not specified, a default provider is used, if it is
defined for the message layer.

if no default provider is defined, authentication requirements defined
in the `message-security-binding` are not enforced.

|===


[[beauy]][[GSDPG00206]][[message-security-config]]

=== `message-security-config`

Specifies configurations for message security providers.

[[fvyya]][[GSDPG00586]][[superelements-122]]

==== Superelements

link:#bearr[`client-container`] (`sun-acc.xml`)

[[fvzck]][[GSDPG00587]][[subelements-115]]

==== Subelements

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

[[GSDPG973]][[sthref165]][[fvyym]]


Table C-102 `message-security-config` Subelements

[width="100%",cols="31%,15%,54%",options="header",]
|===
|Element |Required |Description
a|
link:#beavz[`provider-config`]


 |one or more |Specifies a configuration for one message security
provider.
|===


[[fvyvw]][[GSDPG00588]][[attributes-27]]

==== Attributes

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

[[GSDPG974]][[sthref166]][[fvzam]]


Table C-103 `message-security-config` Attributes

[width="172%",cols="17%,46%,37%",options="header",]
|===
|Attribute |Default |Description
|`auth-layer` |none |Specifies the message layer at which authentication
is performed. The value must be `SOAP`.

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


[[beauz]][[GSDPG00207]][[method]]

=== `method`

Specifies a bean method.

[[fvzae]][[GSDPG00589]][[superelements-123]]

==== Superelements

link:#bearo[`checkpoint-at-end-of-method`],
link:#beatf[`flush-at-end-of-method`] (`glassfish-ejb-jar.xml`)

[[fvzay]][[GSDPG00590]][[subelements-116]]

==== Subelements

The following table describes subelements for the `method` element.

[[GSDPG975]][[sthref167]][[fvzch]]


Table C-104 `method` Subelements

[width="100%",cols="17%,11%,72%",options="header",]
|===
|Element |Required |Description
a|
link:#beaso[`description`]


 |zero or one |Specifies an optional text description.

a|
link:#beast[`ejb-name`]


 |zero or one |Matches the `ejb-name` in the corresponding `ejb-jar.xml`
file.

a|
link:#beavb[`method-name`]


 |only one |Specifies a method name.

a|
link:#beava[`method-intf`]


 |zero or one |Specifies the method interface to distinguish between
methods with the same name in different interfaces.

a|
link:#beavd[`method-params`]


 |zero or one |Specifies fully qualified Java type names of method
parameters.
|===


[[beava]][[GSDPG00208]][[method-intf]]

=== `method-intf`

Specifies the method interface to distinguish between methods with the
same name in different interfaces. Allowed values are `Home`, `Remote`,
`LocalHome`, and `Local`.

[[fvywj]][[GSDPG00591]][[superelements-124]]

==== Superelements

link:#beauz[`method`] (`glassfish-ejb-jar.xml`)

[[fvyyz]][[GSDPG00592]][[subelements-117]]

==== Subelements

none - contains data

[[beavb]][[GSDPG00209]][[method-name]]

=== `method-name`

Specifies a method name or `*` (an asterisk) for all methods. If a
method is overloaded, specifies all methods with the same name.

[[fvyvp]][[GSDPG00593]][[superelements-125]]

==== Superelements

link:#beatt[`java-method`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`, `glassfish-application-client.xml`);
link:#beate[`finder`], link:#beawc[`query-method`] ,
link:#beauz[`method`] (`glassfish-ejb-jar.xml`)

[[fvzcp]][[GSDPG00594]][[subelements-118]]

==== Subelements

none - contains data

[[fvzdr]][[GSDPG00595]][[examples]]

==== Examples

`<method-name>findTeammates</method-name>`

`<method-name>*</method-name>`

[[beavc]][[GSDPG00210]][[method-param]]

=== `method-param`

Specifies the fully qualified Java type name of a method parameter.

[[fvzdl]][[GSDPG00596]][[superelements-126]]

==== Superelements

link:#beavd[`method-params`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`, `glassfish-application-client.xml`)

[[fvyvj]][[GSDPG00597]][[subelements-119]]

==== Subelements

none - contains data

[[beavd]][[GSDPG00211]][[method-params]]

=== `method-params`

Specifies fully qualified Java type names of method parameters.

[[fvzdt]][[GSDPG00598]][[superelements-127]]

==== Superelements

link:#beatt[`java-method`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`, `glassfish-application-client.xml`);
link:#beawc[`query-method`], link:#beauz[`method`]
(`glassfish-ejb-jar.xml`)

[[fvyzw]][[GSDPG00599]][[subelements-120]]

==== Subelements

The following table describes subelements for the `method-params`
element.

[[GSDPG976]][[sthref168]][[fvyzq]]


Table C-105 `method-params` Subelements

[width="100%",cols="18%,14%,68%",options="header",]
|===
|Element |Required |Description
a|
link:#beavc[`method-param`]


 |zero or more |Specifies the fully qualified Java type name of a method
parameter.
|===


[[beavf]][[GSDPG00212]][[name]]

`name`
~~~~~~

Specifies the name of the entity.

[[fvyyf]][[GSDPG00600]][[superelements-128]]

==== Superelements

link:#beari[`call-property`], link:#beasn[`default-resource-principal`],
link:#beaxv[`stub-property`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`, `glassfish-application-client.xml`);
link:#beasx[`enterprise-beans`], link:#beavv[`principal`],
link:#beavy[`property` (with subelements)] (`glassfish-ejb-jar.xml`)

[[fvyxe]][[GSDPG00601]][[subelements-121]]

==== Subelements

none - contains data

[[beavg]][[GSDPG00213]][[named-group]]

=== `named-group`

Specifies the name of one independent fetch group. All the fields and
relationships that are part of a named group are fetched at the same
time. A field belongs to only one fetch group, regardless of what type
of fetch group is used.

[[fvzds]][[GSDPG00602]][[superelements-129]]

==== Superelements

link:#beatc[`fetched-with`] (`sun-cmp-mappings.xml`)

[[fvyxr]][[GSDPG00603]][[subelements-122]]

==== Subelements

none - contains data

[[beavh]][[GSDPG00214]][[namespaceuri]]

=== `namespaceURI`

Specifies the namespace URI.

[[fvywa]][[GSDPG00604]][[superelements-130]]

==== Superelements

link:#beaxj[`service-qname`], link:#beayx[`wsdl-port`]
(`glassfish-web.xml`, `glassfish-ejb-jar.xml`,
`glassfish-application-client.xml`)

[[fvyzc]][[GSDPG00605]][[subelements-123]]

==== Subelements

none - contains data

[[beavi]][[GSDPG00215]][[none]]

`none`
~~~~~~

Specifies that this field or relationship is fetched by itself, with no
other fields or relationships.

[[fvyvv]][[GSDPG00606]][[superelements-131]]

==== Superelements

link:#beasd[`consistency`], link:#beatc[`fetched-with`]
(`sun-cmp-mappings.xml`)

[[fvzaw]][[GSDPG00607]][[subelements-124]]

==== Subelements

none - element is present or absent

[[beavk]][[GSDPG00216]][[one-one-finders]]

=== `one-one-finders`

Describes the finders for CMP 1.1 beans.

[[fvyvg]][[GSDPG00608]][[superelements-132]]

==== Superelements

link:#beart[`cmp`] (`glassfish-ejb-jar.xml`)

[[fvywp]][[GSDPG00609]][[subelements-125]]

==== Subelements

The following table describes subelements for the `one-one-finders`
element.

[[GSDPG977]][[sthref169]][[fvyxu]]


Table C-106 `one-one-finders` Subelements

[width="100%",cols="23%,15%,62%",options="header",]
|===
|Element |Required |Description
a|
link:#beate[`finder`]


 |one or more |Describes the finders for CMP 1.1 with a method name and
query.
|===


[[beavl]][[GSDPG00217]][[operation-name]]

=== `operation-name`

Specifies the WSDL name of an operation of a web service.

[[fvzas]][[GSDPG00610]][[superelements-133]]

==== Superelements

link:#beaut[`message`] (`glassfish-web.xml`, `glassfish-ejb-jar.xml`,
`glassfish-application-client.xml`)

[[fvyvt]][[GSDPG00611]][[subelements-126]]

==== Subelements

none - contains data

[[beavn]][[GSDPG00218]][[parameter-encoding]]

=== `parameter-encoding`

Specifies the default request character encoding and how the web
container decodes parameters from forms according to a hidden field
value.

If both the link:#beayb[`glassfish-web-app`] and
link:#beaue[`locale-charset-info`] elements have `parameter-encoding`
subelements, the subelement of `glassfish-web-app` takes precedence. For
encodings, see
`http://docs.oracle.com/javase/7/docs/technotes/guides/intl/encoding.doc.html`.

[[fvyzr]][[GSDPG00612]][[superelements-134]]

==== Superelements

link:#beaue[`locale-charset-info`], link:#beayb[`glassfish-web-app`]
(`glassfish-web.xml`)

[[fvzbf]][[GSDPG00613]][[subelements-127]]

==== Subelements

none

[[fvyxk]][[GSDPG00614]][[attributes-28]]

==== Attributes

The following table describes attributes for the `parameter-encoding`
element.

[[GSDPG978]][[sthref170]][[fvywn]]


Table C-107 `parameter-encoding` Attributes

[width="100%",cols="19%,13%,68%",options="header",]
|===
|Attribute |Default |Description
|`form-hint-field` |none |(optional) The name of the hidden field in the
form. This field specifies the character encoding the web container uses
for `request.getParameter` and `request.getReader` calls when the
charset is not set in the request's `content-type` header.

|`default-charset` |`ISO-8859-1` |(optional) The default request
character encoding.
|===


[[beavo]][[GSDPG00219]][[pass-by-reference]]

=== `pass-by-reference`

Specifies the passing method used by a servlet or enterprise bean
calling a remote interface method in another bean that is colocated
within the same process.

* If `false` (the default if this element is not present), this
application uses pass-by-value semantics.
* If `true`, this application uses pass-by-reference semantics.


[NOTE]
====
The `pass-by-reference` element only applies to remote calls. As defined
in the EJB 2.1 specification, section 5.4, calls to local interfaces use
pass-by-reference semantics.

If the `pass-by-reference` element is set to its default value of
`false`, the passing semantics for calls to remote interfaces comply
with the EJB 2.1 specification, section 5.4. If set to `true`, remote
calls involve pass-by-reference semantics instead of pass-by-value
semantics, contrary to this specification.

Portable programs cannot assume that a copy of the object is made during
such a call, and thus that it's safe to modify the original. Nor can
they assume that a copy is not made, and thus that changes to the object
are visible to both caller and callee. When this element is set to
`true`, parameters and return values should be considered read-only. The
behavior of a program that modifies such parameters or return values is
undefined.
====


When a servlet or enterprise bean calls a remote interface method in
another bean that is colocated within the same process, by default
{productName} makes copies of all the call parameters in order to
preserve the pass-by-value semantics. This increases the call overhead
and decreases performance.

However, if the calling method does not change the object being passed
as a parameter, it is safe to pass the object itself without making a
copy of it. To do this, set the pass-by-reference value to `true`.

The setting of this element in the `glassfish-application.xml` file
applies to all EJB modules in the application. For an individually
deployed EJB module, you can set the same element in the
`glassfish-ejb-jar.xml` file. If `pass-by-reference` is used at both the
bean and application level, the bean level takes precedence.

[[fvzec]][[GSDPG00615]][[superelements-135]]

==== Superelements

link:#beaxw[`glassfish-application`] (`glassfish-application.xml`),
link:#beass[`ejb`] (`glassfish-ejb-jar.xml`)

[[fvywx]][[GSDPG00616]][[subelements-128]]

==== Subelements

none - contains data

[[beavp]][[GSDPG00220]][[password]]

=== `password`

Specifies the password for the principal.

[[fvyvn]][[GSDPG00617]][[superelements-136]]

==== Superelements

link:#beasn[`default-resource-principal`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`, `glassfish-application-client.xml`)

[[fvyvs]][[GSDPG00618]][[subelements-129]]

==== Subelements

none - contains data

[[gkkia]][[GSDPG00221]][[per-request-load-balancing]]

=== `per-request-load-balancing`

Specifies the per-request load balancing behavior of EJB 2.x and 3.x
remote client invocations on a stateless session bean. If set to `true`,
per-request load balancing is enabled for the associated stateless
session bean. If set to `false` or not set, per-request load balancing
is not enabled. The default is `false`.

[[gkklx]][[GSDPG00619]][[superelements-137]]

==== Superelements

link:#beass[`ejb`] (`glassfish-ejb-jar.xml`)

[[gkkmq]][[GSDPG00620]][[subelements-130]]

==== Subelements

none - contains data

[[beavq]][[GSDPG00222]][[pm-descriptors]]

=== `pm-descriptors`

This element and its subelements are deprecated. Do not use.

[[fvzbh]][[GSDPG00621]][[superelements-138]]

==== Superelements

link:#beasx[`enterprise-beans`] (`glassfish-ejb-jar.xml`)

[[beavr]][[GSDPG00223]][[pool-idle-timeout-in-seconds]]

=== `pool-idle-timeout-in-seconds`

Specifies the maximum time, in seconds, that a bean instance is allowed
to remain idle in the pool. When this timeout expires, the bean instance
in a pool becomes a candidate for passivation or deletion. This is a
hint to the server. A value of 0 specifies that idle beans remain in the
pool indefinitely. Default value is 600.

Applies to stateless session beans, entity beans, and message-driven
beans.


[NOTE]
====
For a stateless session bean or a message-driven bean, the bean is
removed (garbage collected) when the timeout expires.
====


[[fvzbm]][[GSDPG00622]][[superelements-139]]

==== Superelements

link:#bearb[`bean-pool`] (`glassfish-ejb-jar.xml`)

[[fvzbs]][[GSDPG00623]][[subelements-131]]

==== Subelements

none - contains data

[[beavs]][[GSDPG00224]][[port-component-name]]

=== `port-component-name`

Specifies a unique name for a port component within a web or EJB module.

[[fvzbl]][[GSDPG00624]][[superelements-140]]

==== Superelements

link:#beayv[`webservice-endpoint`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`)

[[fvyys]][[GSDPG00625]][[subelements-132]]

==== Subelements

none - contains data

[[beavt]][[GSDPG00225]][[port-info]]

=== `port-info`

Specifies information for a port within a web service reference.

Either a `service-endpoint-interface` or a `wsdl-port` or both must be
specified. If both are specified, `wsdl-port` specifies the port that
the container chooses for container-managed port selection.

The same `wsdl-port` value must not appear in more than one `port-info`
element within the same `service-ref`.

If a `service-endpoint-interface` is using container-managed port
selection, its value must not appear in more than one `port-info`
element within the same `service-ref`.

[[fvzdh]][[GSDPG00626]][[superelements-141]]

==== Superelements

link:#beaxk[`service-ref`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`, `glassfish-application-client.xml`)

[[fvyva]][[GSDPG00627]][[subelements-133]]

==== Subelements

The following table describes subelements for the `port-info` element.

[[GSDPG979]][[sthref171]][[fvzbr]]


Table C-108 `port-info` subelements

[width="100%",cols="32%,12%,56%",options="header",]
|===
|Element |Required |Description
a|
link:#beaxh[`service-endpoint-interface`]


 |zero or one |Specifies the web service reference name relative to
`java:comp/env`.

a|
link:#beayx[`wsdl-port`]


 |zero or one |Specifies the WSDL port.

a|
link:#beaxv[`stub-property`]


 |zero or more |Specifies JAX-RPC property values that are set on a
`javax.xml.rpc.Stub` object before it is returned to the web service
client.

a|
link:#beari[`call-property`]


 |zero or more |Specifies JAX-RPC property values that are set on a
`javax.xml.rpc.Call` object before it is returned to the web service
client.

a|
link:#beaux[`message-security-binding`]


 |zero or one |Specifies a custom authentication provider binding.
|===


[[beavu]][[GSDPG00226]][[prefetch-disabled]]

=== `prefetch-disabled`

Disables prefetching of entity bean states for the specified query
methods. Container-managed relationship fields are prefetched if their
link:#beatc[`fetched-with`] element is set to link:#beasl[`default`].

[[fvyxl]][[GSDPG00628]][[superelements-142]]

==== Superelements

link:#beart[`cmp`] (`glassfish-ejb-jar.xml`)

[[fvyyb]][[GSDPG00629]][[subelements-134]]

==== Subelements

The following table describes subelements for the `prefetch-disabled`
element.

[[GSDPG980]][[sthref172]][[fvyyn]]


Table C-109 `prefetch-disabled` Subelements

[width="100%",cols="30%,14%,56%",options="header",]
|===
|Element |Required |Description
a|
link:#beawc[`query-method`]


 |one or more |Specifies a query method.
|===


[[beavv]][[GSDPG00227]][[principal]]

=== `principal`

Defines a user name on the platform.

[[fvyvy]][[GSDPG00630]][[superelements-143]]

==== Superelements

link:#beass[`ejb`] (`glassfish-ejb-jar.xml`);
link:#giyhy[`security-map`] (`glassfish-resources.xml`)

[[fvzbt]][[GSDPG00631]][[subelements-135]]

==== Subelements

The following table describes subelements for the `principal` element.

[[GSDPG981]][[sthref173]][[fvzaq]]


Table C-110 `principal` Subelements

[width="100%",cols="29%,15%,56%",options="header",]
|===
|Element |Required |Description
a|
link:#beavf[`name`]


 |only one |Specifies the name of the user.
|===


[[giyif]][[GSDPG00228]][[principal-map]]

=== `principal-map`

Maps an EIS principal to a principal defined in the {productName}
domain.

[[GSDPG982]][[sthref174]]


[[superelements-144]]
==== Superelements

link:#giyht[`work-security-map`] (`glassfish-resources.xml`)

[[giyjg]][[GSDPG00632]][[subelements-136]]

==== Subelements

none

[[GSDPG983]][[sthref175]]


[[attributes-29]]
==== Attributes

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

[[GSDPG984]][[sthref176]][[sthref177]]


Table C-111 `principal-map` Attributes

[width="181%",cols="13%,49%,38%",options="header",]
|===
|Attribute |Default |Description
|`eis-principal` |none |Specifies an EIS principal.

|`mapped-principal` |none |Specifies a principal defined in the
{productName} domain.
|===


[[beavw]][[GSDPG00229]][[principal-name]]

=== `principal-name`

Contains the principal (user) name.

In an enterprise bean, specifies the principal (user) name that has the
`run-as` role specified.

[[fvyws]][[GSDPG00633]][[superelements-145]]

==== Superelements

link:#beaxg[`security-role-mapping`] (`glassfish-application.xml`,
`glassfish-web.xml`, `glassfish-ejb-jar.xml`), link:#beaxm[`servlet`]
(`glassfish-web.xml`)

[[fvyxp]][[GSDPG00634]][[subelements-137]]

==== Subelements

none - contains data

[[gatzl]][[GSDPG00635]][[attributes-30]]

==== Attributes

The following table describes attributes for the `principal-name`
element.

[[GSDPG985]][[sthref178]][[gatyf]]


Table C-112 `principal-name` Attributes

[width="100%",cols="13%,36%,51%",options="header",]
|===
|Attribute |Default |Description
|`class-name` |`com.sun.enterprise.deployment.PrincipalImpl` |(optional)
Specifies the custom principal implementation class corresponding to the
named principal.
|===


[[beavx]][[GSDPG00230]][[property-with-attributes]]

=== `property` (with attributes)

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

* Optional with respect to {productName}
* Needed by a system or object that {productName} doesn't have
knowledge of, such as an LDAP server or a Java class

[[fvzeb]][[GSDPG00636]][[superelements-146]]

==== Superelements

link:#beard[`cache`], link:#beare[`cache-helper`],
link:#bearq[`class-loader`], link:#beash[`cookie-properties`],
link:#beasm[`default-helper`], link:#beaum[`manager-properties`],
link:#beaxr[`session-properties`], link:#beaxu[`store-properties`],
link:#beayb[`glassfish-web-app`], link:#gikqk[`valve`],
link:#beayv[`webservice-endpoint`] (`glassfish-web.xml`);
link:#beaqy[`auth-realm`], link:#bearr[`client-container`],
link:#bears[`client-credential`], link:#beauj[`log-service`],
link:#beavz[`provider-config`] (`sun-acc.xml`);
link:#giyhw[`admin-object-resource`],
link:#giygu[`connector-connection-pool`],
link:#giyhv[`connector-resource`], link:#giyhr[`custom-resource`],
link:#giyin[`external-jndi-resource`],
link:#giyil[`jdbc-connection-pool`], link:#giyhm[`jdbc-resource`],
link:#giyik[`mail-resource`], link:#giyit[`resource-adapter-config`]
(`glassfish-resources.xml`)

[[fvyzv]][[GSDPG00637]][[subelements-138]]

==== Subelements

The following table describes subelements for the `property` element.

[[GSDPG986]][[sthref179]][[fvzcb]]


Table C-113 `property` Subelements

[width="100%",cols="27%,17%,56%",options="header",]
|===
|Element |Required |Description
a|
link:#beaso[`description`]


 |zero or one |Specifies an optional text description of a property.
|===



[NOTE]
====
The `property` element in the `sun-acc.xml` file has no subelements.
====


[[fvyvi]][[GSDPG00638]][[attributes-31]]

==== Attributes

The following table describes attributes for the `property` element.

[[GSDPG987]][[sthref180]][[fvzdi]]


Table C-114 `property` Attributes

[width="100%",cols="14%,10%,76%",options="header",]
|===
|Attribute |Default |Description
|`name` |none |Specifies the name of the property.
|`value` |none |Specifies the value of the property.
|===


[[fvzab]][[GSDPG00639]][[example-7]]

==== Example

[source,xml]
----
<property name="reapIntervalSeconds" value="20" />
----

[[beavy]][[GSDPG00231]][[property-with-subelements]]

=== `property` (with subelements)

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

* Optional with respect to {productName}
* Needed by a system or object that {productName} doesn't have
knowledge of, such as an LDAP server or a Java class

[[fvzcl]][[GSDPG00640]][[superelements-147]]

==== Superelements

link:#beasx[`enterprise-beans`], link:#bearv[`cmp-resource`],
link:#beaxd[`schema-generator-properties`],
link:#beayv[`webservice-endpoint`] (`glassfish-ejb-jar.xml`)

[[fvzaf]][[GSDPG00641]][[subelements-139]]

==== Subelements

The following table describes subelements for the `property` element.

[[GSDPG988]][[sthref181]][[fvzcc]]


Table C-115 `property` subelements

[width="100%",cols="22%,16%,62%",options="header",]
|===
|Element |Required |Description
a|
link:#beavf[`name`]


 |only one |Specifies the name of the property.
a|
link:#beayo[`value`]


 |only one |Specifies the value of the property.
|===


[[fvyxz]][[GSDPG00642]][[example-8]]

==== Example

[source,xml]
----
<property>
   <name>use-unique-table-names</name>
   <value>true</value>
</property>
----

[[beavz]][[GSDPG00232]][[provider-config]]

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

[[fvzcy]][[GSDPG00643]][[superelements-148]]

==== Superelements

link:#beauy[`message-security-config`] (`sun-acc.xml`)

[[fvyzt]][[GSDPG00644]][[subelements-140]]

==== Subelements

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

[[GSDPG989]][[sthref182]][[fvyyq]]


Table C-116 `provider-config` Subelements

[width="100%",cols="25%,12%,63%",options="header",]
|===
|Element |Required |Description
a|
link:#beawo[`request-policy`]


 |zero or one |Defines the authentication policy requirements of the
authentication provider's request processing.

a|
link:#beawx[`response-policy`]


 |zero or one |Defines the authentication policy requirements of the
authentication provider's response processing.

a|
link:#beavx[`property` (with attributes)]


 |zero or more |Specifies a property, which has a name and a value.
|===


[[fvywu]][[GSDPG00645]][[attributes-32]]

==== Attributes

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

[[GSDPG990]][[sthref183]][[fvyvz]]


Table C-117 `provider-config` Attributes

[width="172%",cols="11%,46%,43%",options="header",]
|===
|Attribute |Default |Description
|`provider-id` |none |Specifies the provider ID.

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


[[beawb]][[GSDPG00233]][[query-filter]]

=== `query-filter`

Specifies the query filter for the CMP 1.1 finder.

[[fvzdm]][[GSDPG00646]][[superelements-149]]

==== Superelements

link:#beate[`finder`] (`glassfish-ejb-jar.xml`)

[[fvzco]][[GSDPG00647]][[subelements-141]]

==== Subelements

none - contains data

[[beawc]][[GSDPG00234]][[query-method]]

=== `query-method`

Specifies a query method.

[[fvyxo]][[GSDPG00648]][[superelements-150]]

==== Superelements

link:#beavu[`prefetch-disabled`] (`glassfish-ejb-jar.xml`)

[[fvyzm]][[GSDPG00649]][[subelements-142]]

==== Subelements

The following table describes subelements for the `query-method`
element.

[[GSDPG991]][[sthref184]][[fvywl]]


Table C-118 `query-method` Subelements

[width="100%",cols="17%,10%,73%",options="header",]
|===
|Element |Required |Description
a|
link:#beavb[`method-name`]


 |only one |Specifies a method name.

a|
link:#beavd[`method-params`]


 |only one |Specifies the fully qualified Java type names of method
parameters.
|===


[[beawd]][[GSDPG00235]][[query-ordering]]

=== `query-ordering`

Specifies the query ordering for the CMP 1.1 finder.

[[fvzef]][[GSDPG00650]][[superelements-151]]

==== Superelements

link:#beate[`finder`] (`glassfish-ejb-jar.xml`)

[[fvywd]][[GSDPG00651]][[subelements-143]]

==== Subelements

none - contains data

[[beawe]][[GSDPG00236]][[query-params]]

=== `query-params`

Specifies the query parameters for the CMP 1.1 finder.

[[fvyvu]][[GSDPG00652]][[superelements-152]]

==== Superelements

link:#beate[`finder`] (`glassfish-ejb-jar.xml`)

[[fvzax]][[GSDPG00653]][[subelements-144]]

==== Subelements

none - contains data

[[beawf]][[GSDPG00237]][[query-variables]]

=== `query-variables`

Specifies variables in the query expression for the CMP 1.1 finder.

[[fvyyg]][[GSDPG00654]][[superelements-153]]

==== Superelements

link:#beate[`finder`] (`glassfish-ejb-jar.xml`)

[[fvzce]][[GSDPG00655]][[subelements-145]]

==== Subelements

none - contains data

[[beawh]][[GSDPG00238]][[read-only]]

=== `read-only`

Specifies that a field is read-only if `true`. If this element is
absent, the default value is `false` .

[[fvyzs]][[GSDPG00656]][[superelements-154]]

==== Superelements

link:#bearu[`cmp-field-mapping`] (`sun-cmp-mappings.xml`)

[[fvzav]][[GSDPG00657]][[subelements-146]]

==== Subelements

none - contains data

[[beawi]][[GSDPG00239]][[realm]]

=== `realm`

Specifies the name of the realm used to process all authentication
requests associated with this application. If this element is not
specified or does not match the name of a configured realm, the default
realm is used. For more information about realms, see
"link:application-development-guide/securing-apps.html#GSDVG00118[Realm Configuration]" in {productName} Application Development Guide.

[[fvzaa]][[GSDPG00658]][[superelements-155]]

==== Superelements

link:#beaxw[`glassfish-application`] (`glassfish-application.xml`),
link:#beaqw[`as-context`], link:#beauk[`login-config`]
(`glassfish-ejb-jar.xml`)

[[fvzdq]][[GSDPG00659]][[subelements-147]]

==== Subelements

none - contains data

[[beawj]][[GSDPG00240]][[refresh-field]]

=== `refresh-field`

Specifies a field that gives the application component a programmatic
way to refresh a cached entry.

[[fvywt]][[GSDPG00660]][[superelements-156]]

==== Superelements

link:#bearh[`cache-mapping`] (`glassfish-web.xml`)

[[fvzbw]][[GSDPG00661]][[subelements-148]]

==== Subelements

none

[[fvzbp]][[GSDPG00662]][[attributes-33]]

==== Attributes

The following table describes attributes for the `refresh-field`
element.

[[GSDPG992]][[sthref185]][[fvzbz]]


Table C-119 `refresh-field` Attributes

[width="181%",cols="51%,11%,38%",options="header",]
|===
|Attribute |Default |Description
|`name` |none |Specifies the input parameter name.

|`scope` |`request.parameter` |(optional) Specifies the scope from which
the input parameter is retrieved. Allowed values are
`context.attribute`, `request.header`, `request.parameter`,
`request.cookie`, `session.id`, and `session.attribute`.
|===


[[beawk]][[GSDPG00241]][[refresh-period-in-seconds]]

=== `refresh-period-in-seconds`

Specifies the rate at which a read-only-bean must be refreshed from the
data source. If the value is less than or equal to zero, the bean is
never refreshed; if the value is greater than zero, the bean instances
are refreshed at the specified interval. This rate is just a hint to the
container. Default is 0 (no refresh).

[[fvzcn]][[GSDPG00663]][[superelements-157]]

==== Superelements

link:#beass[`ejb`] (`glassfish-ejb-jar.xml`)

[[fvyxh]][[GSDPG00664]][[subelements-149]]

==== Subelements

none - contains data

[[beawl]][[GSDPG00242]][[removal-timeout-in-seconds]]

=== `removal-timeout-in-seconds`

Specifies the amount of time a bean instance can remain idle in the
container before it is removed (timeout). A value of 0 specifies that
the container does not remove inactive beans automatically. The default
value is 5400.

If `removal-timeout-in-seconds` is less than or equal to
`cache-idle-timeout-in-seconds`, beans are removed immediately without
being passivated.

Applies to stateful session beans.

For related information, see
link:#bearg[`cache-idle-timeout-in-seconds`].

[[fvzat]][[GSDPG00665]][[superelements-158]]

==== Superelements

link:#beara[`bean-cache`] (`glassfish-ejb-jar.xml`)

[[fvzeg]][[GSDPG00666]][[subelements-150]]

==== Subelements

none - contains data

[[beawm]][[GSDPG00243]][[remote-home-impl]]

=== `remote-home-impl`

Specifies the fully-qualified class name of the generated `EJBHome`
`impl` class.


[NOTE]
====
This value is automatically generated by the server at deployment or
redeployment time. Do not specify it or change it after deployment.
====


[[fvywr]][[GSDPG00667]][[superelements-159]]

==== Superelements

link:#beath[`gen-classes`] (`glassfish-ejb-jar.xml`)

[[fvyyt]][[GSDPG00668]][[subelements-151]]

==== Subelements

none - contains data

[[beawn]][[GSDPG00244]][[remote-impl]]

=== `remote-impl`

Specifies the fully-qualified class name of the generated `EJBObject`
`impl` class.


[NOTE]
====
This value is automatically generated by the server at deployment or
redeployment time. Do not specify it or change it after deployment.
====


[[fvyzi]][[GSDPG00669]][[superelements-160]]

==== Superelements

link:#beath[`gen-classes`] (`glassfish-ejb-jar.xml`)

[[fvzag]][[GSDPG00670]][[subelements-152]]

==== Subelements

none - contains data

[[beawo]][[GSDPG00245]][[request-policy]]

=== `request-policy`

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

[[fvyxw]][[GSDPG00671]][[superelements-161]]

==== Superelements

link:#beavz[`provider-config`] (`sun-acc.xml`)

[[fvzdz]][[GSDPG00672]][[subelements-153]]

==== Subelements

none

[[fvyvq]][[GSDPG00673]][[attributes-34]]

==== Attributes

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

[[GSDPG993]][[sthref186]][[fvzdy]]


Table C-120 `request-policy` Attributes

[width="172%",cols="11%,46%,43%",options="header",]
|===
|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`.
|===


[[beawp]][[GSDPG00246]][[request-protection]]

=== `request-protection`

Defines the authentication policy requirements of the application's
request processing.

[[fvzcv]][[GSDPG00674]][[superelements-162]]

==== Superelements

link:#beauw[`message-security`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`, `glassfish-application-client.xml`)

[[fvzby]][[GSDPG00675]][[subelements-154]]

==== Subelements

none

[[fvzar]][[GSDPG00676]][[attributes-35]]

==== Attributes

The following table describes attributes for the `request-protection`
element.

[[GSDPG994]][[sthref187]][[fvzbu]]


Table C-121 `request-protection` Attributes

[width="172%",cols="13%,46%,41%",options="header",]
|===
|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`.
|===


[[beawq]][[GSDPG00247]][[required]]

=== `required`

Specifies whether the authentication method specified in the
link:#beaqx[`auth-method`] element must be used for client
authentication. The value is `true` or `false` (the default).

[[fvyvc]][[GSDPG00677]][[superelements-163]]

==== Superelements

link:#beaqw[`as-context`] (`glassfish-ejb-jar.xml`)

[[fvywc]][[GSDPG00678]][[subelements-155]]

==== Subelements

none - contains data

[[beawr]][[GSDPG00248]][[res-ref-name]]

=== `res-ref-name`

Specifies the `res-ref-name` in the corresponding Jakarta EE deployment
descriptor file `resource-ref` entry. The `res-ref-name` element
specifies the name of a resource manager connection factory reference.
The name must be unique within an enterprise bean.

[[fvyvk]][[GSDPG00679]][[superelements-164]]

==== Superelements

link:#beaww[`resource-ref`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`, `glassfish-application-client.xml`)

[[fvyyp]][[GSDPG00680]][[subelements-156]]

==== Subelements

none - contains data

[[beaws]][[GSDPG00249]][[resize-quantity]]

=== `resize-quantity`

Specifies the number of bean instances to be:

* Created, if a request arrives when the pool has less than
link:#beaxt[`steady-pool-size`] quantity of beans (applies to pools only
for creation). If the pool has more than `steady-pool-size` minus
link:#beaws[`resize-quantity`] of beans, then `resize-quantity` is still
created.
* Removed, when the link:#beavr[`pool-idle-timeout-in-seconds`] timer
expires and a cleaner thread removes any unused instances.

** For caches, when link:#beauo[`max-cache-size`] is reached,
`resize-quantity` beans are selected for passivation using the
link:#beayp[`victim-selection-policy`]. In addition, the
link:#bearg[`cache-idle-timeout-in-seconds`] or
link:#beawl[`removal-timeout-in-seconds`] timers passivate beans from
the cache.

** For pools, when the link:#beaup[`max-pool-size`] is reached,
`resize-quantity` beans are selected for removal. In addition, the
link:#beavr[`pool-idle-timeout-in-seconds`] timer removes beans until
`steady-pool-size` is reached.

Values are from 0 to MAX_INTEGER. The pool is not resized below the
`steady-pool-size`. Default is 16.

Applies to stateless session beans, entity beans, and message-driven
beans.

For EJB pools, the value can be defined in the EJB container. Default is
16. For EJB caches, the value can be defined in the EJB container. Default
is 32.

For message-driven beans, the value can be defined in the EJB container.
Default is 2.

[[fvyxb]][[GSDPG00681]][[superelements-165]]

==== Superelements

link:#beara[`bean-cache`], link:#bearb[`bean-pool`]
(`glassfish-ejb-jar.xml`)

[[fvzcf]][[GSDPG00682]][[subelements-157]]

==== Subelements

none - contains data

[[giyit]][[GSDPG00250]][[resource-adapter-config]]

=== `resource-adapter-config`

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

[[GSDPG995]][[sthref188]]


[[superelements-166]]
==== Superelements

link:#giyiy[`resources`] (`glassfish-resources.xml`)

[[GSDPG996]][[sthref189]]


[[subelements-158]]
==== Subelements

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

[[GSDPG997]][[sthref190]][[sthref191]]


Table C-122 `resource-adapter-config` Subelements

[width="100%",cols="25%,12%,63%",options="header",]
|===
|Element |Required |Description
a|
link:#beavx[`property` (with attributes)]


 |zero or more |Specifies a property or a variable.
|===


[[GSDPG998]][[sthref192]]


[[attributes-36]]
==== Attributes

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

[[GSDPG999]][[sthref193]][[sthref194]]


Table C-123 `resource-adapter-config` Attributes

[width="172%",cols="16%,46%,38%",options="header",]
|===
|Attribute |Default |Description
|`name` |none |(optional) Not used. See `resource-adapter-name`.

|`thread-pool-ids` |none |(optional) Specifies a comma-separated list of
the names of thread pools.

|`object-type` |`user` a|
(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 of a deployed
connector module or application. If the resource adapter is embedded in
an application, then it is app_name`#`rar_name.
|===


[[GSDPG1000]][[sthref195]]


[[properties-11]]
==== Properties

Properties of the `resource-adapter-config` element are the names of
setter methods of 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`.

[[beawt]][[GSDPG00251]][[resource-adapter-mid]]

=== `resource-adapter-mid`

Specifies the module ID of the resource adapter that is responsible for
delivering messages to the message-driven bean.

[[fvyvd]][[GSDPG00683]][[superelements-167]]

==== Superelements

link:#beaus[`mdb-resource-adapter`] (`glassfish-ejb-jar.xml`)

[[fvzed]][[GSDPG00684]][[subelements-159]]

==== Subelements

none - contains data

[[beawu]][[GSDPG00252]][[resource-env-ref]]

=== `resource-env-ref`

Maps the `res-ref-name` in the corresponding Jakarta EE deployment
descriptor file `resource-env-ref` entry to the absolute `jndi-name` of
a resource.

[[fvyvr]][[GSDPG00685]][[superelements-168]]

==== Superelements

link:#beayb[`glassfish-web-app`] (`glassfish-web.xml`),
link:#beass[`ejb`] (`glassfish-ejb-jar.xml`),
link:#beaxx[`glassfish-application-client`]
(`glassfish-application-client.xml`)

[[fvywe]][[GSDPG00686]][[subelements-160]]

==== Subelements

The following table describes subelements for the `resource-env-ref`
element.

[[GSDPG1001]][[sthref196]][[fvyye]]


Table C-124 `resource-env-ref` Subelements

[width="100%",cols="26%,10%,64%",options="header",]
|===
|Element |Required |Description
a|
link:#beawv[`resource-env-ref-name`]


 |only one |Specifies the `res-ref-name` in the corresponding Jakarta EE
deployment descriptor file `resource-env-ref` entry.

a|
link:#beatw[`jndi-name`]


 |only one |Specifies the absolute `jndi-name` of a resource.
|===


[[fvzdf]][[GSDPG00687]][[example-9]]

==== Example

[source,xml]
----
<resource-env-ref>
   <resource-env-ref-name>jms/StockQueueName</resource-env-ref-name>
   <jndi-name>jms/StockQueue</jndi-name>
</resource-env-ref>
----

[[beawv]][[GSDPG00253]][[resource-env-ref-name]]

=== `resource-env-ref-name`

Specifies the `res-ref-name` in the corresponding Jakarta EE deployment
descriptor file `resource-env-ref` entry.

[[fvzau]][[GSDPG00688]][[superelements-169]]

==== Superelements

link:#beawu[`resource-env-ref`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`, `glassfish-application-client.xml`)

[[fvyxj]][[GSDPG00689]][[subelements-161]]

==== Subelements

none - contains data

[[beaww]][[GSDPG00254]][[resource-ref]]

=== `resource-ref`

Maps the `res-ref-name` in the corresponding Jakarta EE deployment
descriptor file `resource-ref` entry to the absolute `jndi-name` of a
resource.


[NOTE]
====
Connections acquired from JMS connection factories are not shareable in
the current release of {productName}. The `res-sharing-scope` element
in the `ejb-jar.xml` file `resource-ref` element is ignored for JMS
connection factories.

When `resource-ref` specifies a JMS connection factory for the Open
Message Queue, the `default-resource-principal` (name/password) must
exist in the Message Queue user repository. Refer to the Security
Management chapter in the olink:GMADG[Open Message Queue Administration
Guide] for information on how to manage the Message Queue user
repository.
====


[[fvywf]][[GSDPG00690]][[superelements-170]]

==== Superelements

link:#beayb[`glassfish-web-app`] (`glassfish-web.xml`),
link:#beass[`ejb`] (`glassfish-ejb-jar.xml`),
link:#beaxx[`glassfish-application-client`]
(`glassfish-application-client.xml`)

[[fvyzz]][[GSDPG00691]][[subelements-162]]

==== Subelements

The following table describes subelements for the `resource-ref`
element.

[[GSDPG1002]][[sthref197]][[fvzbd]]


Table C-125 `resource-ref` Subelements

[width="100%",cols="33%,11%,56%",options="header",]
|===
|Element |Required |Description
a|
link:#beawr[`res-ref-name`]


 |only one |Specifies the `res-ref-name` in the corresponding Jakarta EE
deployment descriptor file `resource-ref` entry.

a|
link:#beatw[`jndi-name`]


 |only one |Specifies the absolute `jndi-name` of a resource.

a|
link:#beasn[`default-resource-principal`]


 |zero or one |Specifies the default principal (user) for the resource.
|===


[[fvyzk]][[GSDPG00692]][[example-10]]

==== Example

[source,xml]
----
<resource-ref>
   <res-ref-name>jdbc/EmployeeDBName</res-ref-name>
   <jndi-name>jdbc/EmployeeDB</jndi-name>
</resource-ref>
----

[[giyiy]][[GSDPG00255]][[resources]]

=== `resources`

Defines application-scoped resources for an enterprise application, web
module, EJB module, connector module, or application client module. This
is the root element; there can only be one `resources` element in a
`glassfish-resources.xml` file. See link:dd-files.html#giyhh[The
glassfish-resources.xml File].


[NOTE]
====
You must specify a Java Naming and Directory Interface (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
{productName} application should begin with the string `java:app/`.
====


[[GSDPG1003]][[sthref198]]


[[superelements-171]]
==== Superelements

none

[[GSDPG1004]][[sthref199]]


[[subelements-163]]
==== Subelements

The following table describes subelements for the `resources` element.

[[GSDPG1005]][[sthref200]][[sthref201]]


Table C-126 `resources` Subelements

[width="100%",cols="31%,12%,57%",options="header",]
|===
|Element |Required |Description
a|
link:#giyhr[`custom-resource`]


 |zero or more |Defines a custom resource.

a|
link:#giyin[`external-jndi-resource`]


 |zero or more |Defines a resource that resides in an external JNDI
repository.

a|
link:#giyhm[`jdbc-resource`]


 |zero or more |Defines a JDBC (Java Database Connectivity) resource.

a|
link:#giyik[`mail-resource`]


 |zero or more |Defines a Jakarta Mail resource.

a|
link:#giyhw[`admin-object-resource`]


 |zero or more |Defines an administered object for an inbound resource
adapter.

a|
link:#giyhv[`connector-resource`]


 |zero or more |Defines a connector (resource adapter) resource.

a|
link:#giyit[`resource-adapter-config`]


 |zero or more |Defines a resource adapter configuration.

a|
link:#giyil[`jdbc-connection-pool`]


 |zero or more |Defines the properties that are required for creating a
JDBC connection pool.

a|
link:#giygu[`connector-connection-pool`]


 |zero or more |Defines the properties that are required for creating a
connector connection pool.

a|
link:#giyht[`work-security-map`]


 |zero or more |Defines a work security map.
|===



[NOTE]
====
Subelements of a `resources` element can occur in any order.
====


[[beawx]][[GSDPG00256]][[response-policy]]

=== `response-policy`

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

[[fvzcg]][[GSDPG00693]][[superelements-172]]

==== Superelements

link:#beavz[`provider-config`] (`sun-acc.xml`)

[[fvyxm]][[GSDPG00694]][[subelements-164]]

==== Subelements

none

[[fvyxf]][[GSDPG00695]][[attributes-37]]

==== Attributes

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

[[GSDPG1006]][[sthref202]][[fvyyr]]


Table C-127 `response-policy` Attributes

[width="172%",cols="13%,46%,41%",options="header",]
|===
|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`.
|===


[[beawy]][[GSDPG00257]][[response-protection]]

=== `response-protection`

Defines the authentication policy requirements of the application's
response processing.

[[fvzdk]][[GSDPG00696]][[superelements-173]]

==== Superelements

link:#beauw[`message-security`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`, `glassfish-application-client.xml`)

[[fvyxd]][[GSDPG00697]][[subelements-165]]

==== Subelements

none

[[fvzeh]][[GSDPG00698]][[attributes-38]]

==== Attributes

The following table describes attributes for the `response-protection`
element.

[[GSDPG1007]][[sthref203]][[fvzej]]


Table C-128 `response-protection` Attributes

[width="172%",cols="13%,46%,41%",options="header",]
|===
|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`.
|===


[[beawz]][[GSDPG00258]][[role-name]]

=== `role-name`

Contains the `role-name` in the `security-role` element of the
corresponding Jakarta EE deployment descriptor file.

[[fvzek]][[GSDPG00699]][[superelements-174]]

==== Superelements

link:#beaxg[`security-role-mapping`] (`glassfish-application.xml`,
`glassfish-web.xml`, `glassfish-ejb-jar.xml`)

[[fvzei]][[GSDPG00700]][[subelements-166]]

==== Subelements

none - contains data

[[beaxb]][[GSDPG00259]][[sas-context]]

=== `sas-context`

Describes the sas-context fields.

[[fvzel]][[GSDPG00701]][[superelements-175]]

==== Superelements

link:#beato[`ior-security-config`] (`glassfish-ejb-jar.xml`)

[[fvzfb]][[GSDPG00702]][[subelements-167]]

==== Subelements

The following table describes subelements for the `sas-context` element.

[[GSDPG1008]][[sthref204]][[fvzey]]


Table C-129 `sas-context` Subelements

[width="100%",cols="30%,11%,59%",options="header",]
|===
|Element |Required |Description
a|
link:#bearj[`caller-propagation`]


 |only one |Specifies whether the target accepts propagated caller
identities. The values are NONE, SUPPORTED, or REQUIRED.
|===


[[beaxc]][[GSDPG00260]][[schema]]

=== `schema`

Specifies the file that contains a description of the database schema to
which the beans in this `sun-cmp-mappings.xml` file are mapped. If this
element is empty, the database schema file is automatically generated at
deployment time. Otherwise, the `schema` element names a `.dbschema`
file with a pathname relative to the directory containing the
`sun-cmp-mappings.xml` file, but without the `.dbschema` extension. See
"link:application-development-guide/container_managed-persistence.html#GSDVG00439[Automatic Database Schema Capture]" in {productName} Application Development Guide.

[[fvzfa]][[GSDPG00703]][[superelements-176]]

==== Superelements

link:#beaxy[`sun-cmp-mapping`] (`sun-cmp-mappings.xml`)

[[fvzeq]][[GSDPG00704]][[subelements-168]]

==== Subelements

none - contains data

[[fvzer]][[GSDPG00705]][[examples-1]]

==== Examples

[source,xml]
----
<schema/> <!-- use automatic schema generation -->

<schema>CompanySchema</schema> <!-- use "CompanySchema.dbschema" -->
----

[[beaxd]][[GSDPG00261]][[schema-generator-properties]]

=== `schema-generator-properties`

Specifies field-specific column attributes in `property` subelements.

[[fvzen]][[GSDPG00706]][[superelements-177]]

==== Superelements

link:#bearv[`cmp-resource`] (`glassfish-ejb-jar.xml`)

[[fvzez]][[GSDPG00707]][[subelements-169]]

==== Subelements

The following table describes subelements for the
`schema-generator-properties` element.

[[GSDPG1009]][[sthref205]][[fvzex]]


Table C-130 `schema-generator-properties` Subelements

[width="100%",cols="40%,14%,46%",options="header",]
|===
|Element |Required |Description
a|
link:#beavy[`property` (with subelements)]


 |zero or more |Specifies a property name and value.
|===


[[fvzew]][[GSDPG00708]][[properties-12]]

==== Properties

The following table describes properties for the
`schema-generator-properties` element.

[[GSDPG1010]][[sthref206]][[fvzev]]


Table C-131 `schema-generator-properties` Properties

[width="172%",cols="17%,46%,37%",options="header",]
|===
|Property |Default |Description
|`use-unique-table-names` |`false` |Specifies that generated table names
are unique within each {productName} domain. This property can be
overridden during deployment. See "link:application-development-guide/container_managed-persistence.html#GSDVG00438[Generation Options
for CMP]" in {productName} Application
Development Guide.

|bean-name`.`field-name`.`attribute |none |Defines a column attribute.
For attribute descriptions, see link:#fvymm[Table C-132].
|===


The following table lists the column attributes for properties defined
in the `schema-generator-properties` element.

[[GSDPG1011]][[sthref207]][[fvymm]]


Table C-132 `schema-generator-properties` Column Attributes

[width="100%",cols="24%,76%",options="header",]
|===
|Attribute |Description
|`jdbc-type` |Specifies the JDBC type of the column created for the CMP
field. The actual SQL type generated is based on this JDBC type but is
database vendor specific.

|`jdbc-maximum-length` a|
Specifies the maximum number of characters stored in the column
corresponding to the CMP field. Applies only when the actual SQL that is
generated for the column requires a length.

For example, a `jdbc-maximum-length` of `32` on a CMP `String` field
such as `firstName` normally results in a column definition such as
VARCHAR(32). But if the `jdbc-type` is `CLOB` and you are deploying on
Oracle, the resulting column definition is CLOB. No length is given,
because in an Oracle database, a CLOB has no length.

|`jdbc-precision` |Specifies the maximum number of digits stored in a
column which represents a numeric type.

|`jdbc-scale` |Specifies the number of digits stored to the right of the
decimal point in a column that represents a floating point number.

|`jdbc-nullable` |Specifies whether the column generated for the CMP
field allows null values.
|===


[[fvzem]][[GSDPG00709]][[example-11]]

==== Example

[source,xml]
----
<schema-generator-properties>
   <property>
         <name>Employee.firstName.jdbc-type</name>
         <value>char</value>
   </property>
   <property>
         <name>Employee.firstName.jdbc-maximum-length</name>
         <value>25</value>
   </property>
   <property>
         <name>use-unique-table-names</name>
         <value>true</value>
   </property>
</schema-generator-properties>
----

[[beaxe]][[GSDPG00262]][[secondary-table]]

=== `secondary-table`

Specifies a bean's secondary table(s).

[[fvzep]][[GSDPG00710]][[superelements-178]]

==== Superelements

link:#beasy[`entity-mapping`] (`sun-cmp-mappings.xml`)

[[fvzeo]][[GSDPG00711]][[subelements-170]]

==== Subelements

The following table describes subelements for the `secondary-table`
element.

[[GSDPG1012]][[sthref208]][[fvzet]]


Table C-133 `secondary table` Subelements

[width="100%",cols="28%,15%,57%",options="header",]
|===
|Element |Required |Description
a|
link:#beayd[`table-name`]


 |only one |Specifies the name of a database table.

a|
link:#beasa[`column-pair`]


 |one or more |Specifies the pair of columns that determine the
relationship between two database tables.
|===


[[beaxf]][[GSDPG00263]][[security]]

=== `security`

Defines the SSL security configuration for IIOP/SSL communication with
the target server.

[[fvzes]][[GSDPG00712]][[superelements-179]]

==== Superelements

link:#beaye[`target-server`] (`sun-acc.xml`)

[[fvzeu]][[GSDPG00713]][[subelements-171]]

==== Subelements

The following table describes subelements for the `security` element.

[[GSDPG1013]][[sthref209]][[fvzfe]]


Table C-134 `security` Subelements

[width="100%",cols="20%,12%,68%",options="header",]
|===
|Element |Required |Description
a|
link:#beaxs[`ssl`]


 |only one |Specifies the SSL processing parameters.
a|
link:#beark[`cert-db`]


 |only one |Not implemented. Included for backward compatibility only.
|===


[[giyhy]][[GSDPG00264]][[security-map]]

=== `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 {productName} principals to the same
back-end principal.

This is different from a link:#giyht[`work-security-map`], which maps a
principal associated with an incoming work instance to a principal in
the {productName}'s security domain.

[[GSDPG1014]][[sthref210]]


[[superelements-180]]
==== Superelements

link:#giygu[`connector-connection-pool`] (`glassfish-resources.xml`)

[[GSDPG1015]][[sthref211]]


[[subelements-172]]
==== Subelements

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

[[GSDPG1016]][[sthref212]][[sthref213]]


Table C-135 `security-map` Subelements

[width="100%",cols="21%,12%,67%",options="header",]
|===
|Element |Required |Description
a|
link:#beavv[`principal`]


 |one or more |Contains the principal of the servlet or EJB client.
a|
link:#giyiq[`user-group`]


 |one or more |Contains the group to which the principal belongs.
a|
link:#giyjv[`backend-principal`]


 |only one |Specifies the user name and password required by the EIS.
|===


[[GSDPG1017]][[sthref214]]


[[attributes-39]]
==== Attributes

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

[[GSDPG1018]][[sthref215]][[sthref216]]


Table C-136 `security-map` Attributes

[width="100%",cols="23%,20%,57%",options="header",]
|===
|Attribute |Default |Description
|`name` |none |Specifies a name for the security mapping.
|===


[[beaxg]][[GSDPG00265]][[security-role-mapping]]

=== `security-role-mapping`

Maps roles to users or groups in the currently active realm. See
"link:application-development-guide/securing-apps.html#GSDVG00118[Realm Configuration]" in {productName} Application Development Guide.

The role mapping element maps a role, as specified in the EJB JAR
`role-name` entries, to a environment-specific user or group. If it maps
to a user, it must be a concrete user which exists in the current realm,
who can log into the server using the current authentication method. If
it maps to a group, the realm must support groups and the group must be
a concrete group which exists in the current realm. To be useful, there
must be at least one user in that realm who belongs to that group.

[[fvzfc]][[GSDPG00714]][[superelements-181]]

==== Superelements

link:#beaxw[`glassfish-application`] (`glassfish-application.xml`),
link:#beayb[`glassfish-web-app`] (`glassfish-web.xml`),
link:#beaya[`glassfish-ejb-jar`] (`glassfish-ejb-jar.xml`)

[[fvzfd]][[GSDPG00715]][[subelements-173]]

==== Subelements

The following table describes subelements for the
`security-role-mapping` element.

[[GSDPG1019]][[sthref217]][[fvzfj]]


Table C-137 `security-role-mapping` Subelements

[width="100%",cols="18%,33%,49%",options="header",]
|===
|Element |Required |Description
a|
link:#beawz[`role-name`]


 |only one |Contains the `role-name` in the `security-role` element of
the corresponding Jakarta EE deployment descriptor file.

a|
link:#beavw[`principal-name`]


 |one or more if no `group-name`, otherwise zero or more |Contains a
principal (user) name in the current realm. In an enterprise bean, the
principal must have the run-as role specified.

a|
link:#beati[`group-name`]


 |one or more if no `principal-name`, otherwise zero or more |Contains a
group name in the current realm.
|===


[[beaxh]][[GSDPG00266]][[service-endpoint-interface]]

=== `service-endpoint-interface`

Specifies the web service reference name relative to `java:comp/env`.

[[fvzfm]][[GSDPG00716]][[superelements-182]]

==== Superelements

link:#beavt[`port-info`] (`glassfish-web.xml`, `glassfish-ejb-jar.xml`,
`glassfish-application-client.xml`)

[[fvzfl]][[GSDPG00717]][[subelements-174]]

==== Subelements

none - contains data

[[beaxi]][[GSDPG00267]][[service-impl-class]]

=== `service-impl-class`

Specifies the name of the generated service implementation class.

[[fvzfg]][[GSDPG00718]][[superelements-183]]

==== Superelements

link:#beaxk[`service-ref`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`, `glassfish-application-client.xml`)

[[fvzfk]][[GSDPG00719]][[subelements-175]]

==== Subelements

none - contains data

[[beaxj]][[GSDPG00268]][[service-qname]]

=== `service-qname`

Specifies the WSDL service element that is being referred to.

[[fvzfn]][[GSDPG00720]][[superelements-184]]

==== Superelements

link:#beaxk[`service-ref`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`, `glassfish-application-client.xml`);
link:#beayv[`webservice-endpoint`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`)

[[fvzff]][[GSDPG00721]][[subelements-176]]

==== Subelements

The following table describes subelements for the `service-qname`
element.

[[GSDPG1020]][[sthref218]][[fvzfi]]


Table C-138 `service-qname` subelements

[width="100%",cols="30%,15%,55%",options="header",]
|===
|Element |Required |Description
a|
link:#beavh[`namespaceURI`]


 |only one |Specifies the namespace URI.
a|
link:#beaug[`localpart`]


 |only one |Specifies the local part of a QNAME.
|===


[[beaxk]][[GSDPG00269]][[service-ref]]

=== `service-ref`

Specifies runtime settings for a web service reference. Runtime
information is only needed in the following cases:

* To define the port used to resolve a container-managed port
* To define the default Stub/Call property settings for Stub objects
* To define the URL of a final WSDL document to be used instead of the
one associated with the `service-ref` in the standard Jakarta EE deployment
descriptor

[[fvzfh]][[GSDPG00722]][[superelements-185]]

==== Superelements

link:#beayb[`glassfish-web-app`] (`glassfish-web.xml`),
link:#beass[`ejb`] (`glassfish-ejb-jar.xml`),
link:#beaxx[`glassfish-application-client`]
(`glassfish-application-client.xml`)

[[fvzhf]][[GSDPG00723]][[subelements-177]]

==== Subelements

The following table describes subelements for the `service-ref` element.

[[GSDPG1021]][[sthref219]][[fvzgc]]


Table C-139 `service-ref` subelements

[width="100%",cols="23%,12%,65%",options="header",]
|===
|Element |Required |Description
a|
link:#beaxl[`service-ref-name`]


 |only one |Specifies the web service reference name relative to
`java:comp/env`.

a|
link:#beavt[`port-info`]


 |zero or more |Specifies information for a port within a web service
reference.

a|
link:#beari[`call-property`]


 |zero or more |Specifies JAX-RPC property values that can be set on a
`javax.xml.rpc.Call` object before it is returned to the web service
client.

a|
link:#beayw[`wsdl-override`]


 |zero or one |Specifies a valid URL pointing to a final WSDL document.

a|
link:#beaxi[`service-impl-class`]


 |zero or one |Specifies the name of the generated service
implementation class.

a|
link:#beaxj[`service-qname`]


 |zero or one |Specifies the WSDL service element that is being
referenced.
|===


[[beaxl]][[GSDPG00270]][[service-ref-name]]

=== `service-ref-name`

Specifies the web service reference name relative to `java:comp/env`.

[[fvzfx]][[GSDPG00724]][[superelements-186]]

==== Superelements

link:#beaxk[`service-ref`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`, `glassfish-application-client.xml`)

[[fvzga]][[GSDPG00725]][[subelements-178]]

==== Subelements

none - contains data

[[beaxm]][[GSDPG00271]][[servlet]]

=== `servlet`

Specifies a principal name for a servlet. Used for the `run-as` role
defined in `web.xml`.

[[fvzgd]][[GSDPG00726]][[superelements-187]]

==== Superelements

link:#beayb[`glassfish-web-app`] (`glassfish-web.xml`)

[[fvzhs]][[GSDPG00727]][[subelements-179]]

==== Subelements

The following table describes subelements for the `servlet` element.

[[GSDPG1022]][[sthref220]][[fvzhy]]


Table C-140 `servlet` Subelements

[width="100%",cols="24%,12%,64%",options="header",]
|===
|Element |Required |Description
a|
link:#beaxo[`servlet-name`]


 |only one |Contains the name of a servlet, which is matched to a
`servlet-name` in `web.xml`.

a|
link:#beavw[`principal-name`]


 |zero or one |Contains a principal (user) name in the current realm.

a|
link:#beayv[`webservice-endpoint`]


 |zero or more |Specifies information about a web service endpoint.
|===


[[beaxn]][[GSDPG00272]][[servlet-impl-class]]

=== `servlet-impl-class`

Specifies the automatically generated name of the servlet implementation
class.

[[fvzhx]][[GSDPG00728]][[superelements-188]]

==== Superelements

link:#beayv[`webservice-endpoint`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`)

[[fvzfs]][[GSDPG00729]][[subelements-180]]

==== Subelements

none - contains data

[[beaxo]][[GSDPG00273]][[servlet-name]]

=== `servlet-name`

Specifies the name of a servlet, which is matched to a `servlet-name` in
`web.xml`. This name must be present in `web.xml`.

[[fvzhj]][[GSDPG00730]][[superelements-189]]

==== Superelements

link:#bearh[`cache-mapping`], link:#beaxm[`servlet`]
(`glassfish-web.xml`)

[[fvzir]][[GSDPG00731]][[subelements-181]]

==== Subelements

none - contains data

[[beaxp]][[GSDPG00274]][[session-config]]

=== `session-config`

Specifies session configuration information. Overrides the web container
settings for an individual web module.

[[fvzic]][[GSDPG00732]][[superelements-190]]

==== Superelements

link:#beayb[`glassfish-web-app`] (`glassfish-web.xml`)

[[fvzfy]][[GSDPG00733]][[subelements-182]]

==== Subelements

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

[[GSDPG1023]][[sthref221]][[fvzib]]


Table C-141 `session-config` Subelements

[width="100%",cols="31%,16%,53%",options="header",]
|===
|Element |Required |Description
a|
link:#beaxq[`session-manager`]


 |zero or one |Specifies session manager configuration information.
a|
link:#beaxr[`session-properties`]


 |zero or one |Specifies session properties.
a|
link:#beash[`cookie-properties`]


 |zero or one |Specifies session cookie properties.
|===


[[beaxq]][[GSDPG00275]][[session-manager]]

=== `session-manager`

Specifies session manager information.

[[fvzgx]][[GSDPG00734]][[superelements-191]]

==== Superelements

link:#beaxp[`session-config`] (`glassfish-web.xml`)

[[fvzit]][[GSDPG00735]][[subelements-183]]

==== Subelements

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

[[GSDPG1024]][[sthref222]][[fvzgo]]


Table C-142 `session-manager` Subelements

[width="100%",cols="32%,15%,53%",options="header",]
|===
|Element |Required |Description
a|
link:#beaum[`manager-properties`]


 |zero or one |Specifies session manager properties.
a|
link:#beaxu[`store-properties`]


 |zero or one |Specifies session persistence (storage) properties.
|===


[[fvzgm]][[GSDPG00736]][[attributes-40]]

==== Attributes

The following table describes attributes for the `session-manager`
element.

[[GSDPG1025]][[sthref223]][[fvzje]]


Table C-143 `session-manager` Attributes

[width="172%",cols="13%,46%,41%",options="header",]
|===
|Attribute |Default |Description
|`persistence-type` |`memory` a|
(optional) Specifies the session persistence mechanism. Allowed values
are `memory`, `file`, and `replicated`.

If you have installed and configured Coherence*Web, the `coherence-web`
persistence type is also available. For more information, see Using
Coherence*Web with {productName}
(`http://docs.oracle.com/cd/E18686_01/coh.37/e18690/glassfish.html`).

|===


[[beaxr]][[GSDPG00276]][[session-properties]]

=== `session-properties`

Specifies session properties.

[[fvzha]][[GSDPG00737]][[superelements-192]]

==== Superelements

link:#beaxp[`session-config`] (`glassfish-web.xml`)

[[fvzgk]][[GSDPG00738]][[subelements-184]]

==== Subelements

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

[[GSDPG1026]][[sthref224]][[fvzgv]]


Table C-144 `session-properties` Subelements

[width="100%",cols="36%,14%,50%",options="header",]
|===
|Element |Required |Description
a|
link:#beavx[`property` (with attributes)]


 |zero or more |Specifies a property, which has a name and a value.
|===


[[fvzht]][[GSDPG00739]][[properties-13]]

==== Properties

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

[[GSDPG1027]][[sthref225]][[fvzii]]


Table C-145 `session-properties` Properties

[width="172%",cols="14%,46%,40%",options="header",]
|===
|Property |Default |Description
|`timeoutSeconds` |`1800` a|
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 `timeoutSeconds` value. If neither
`session-timeout` nor `timeoutSeconds` is specified, the
`timeoutSeconds` default is used.

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

|`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 JSP.
|===


[[beaxs]][[GSDPG00277]][[ssl]]

`ssl`
~~~~~

Defines SSL processing parameters.

[[fvzft]][[GSDPG00740]][[superelements-193]]

==== Superelements

link:#beaxf[`security`] (`sun-acc.xml`)

[[fvzgh]][[GSDPG00741]][[subelements-185]]

==== Subelements

none

[[fvzip]][[GSDPG00742]][[attributes-41]]

==== Attributes

The following table describes attributes for the `SSL` element.

[[GSDPG1028]][[sthref226]][[fvzgb]]


Table C-146 `ssl attributes`

[width="172%",cols="16%,46%,38%",options="header",]
|===
|Attribute |Default |Description
|`cert-nickname` |`s1as` |(optional) 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.

|`ssl2-ciphers` |none |(optional) A comma-separated list of the SSL2
ciphers to be used. Ciphers not explicitly listed will be disabled for
the target, even if those ciphers are available in the particular cipher
suite you are using. If this option is not used, all supported ciphers
are assumed to be enabled. Allowed values are `rc4`, `rc4export`, `rc2`,
`rc2export`, `idea`, `des`, `desede3`.

|`ssl3-enabled` |`true` |(optional) Determines whether SSL3 is enabled.

|`ssl3-tls-ciphers` |none |(optional) A comma-separated list of the
SSL3 and/or TLS ciphers to be used. Ciphers not explicitly listed will
be disabled for the target, even if those ciphers are available in the
particular cipher suite you are using. If this option is not used, all
supported ciphers are assumed to be enabled. 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`,
`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. Enable TLS rollback for Microsoft Internet Explorer
5.0 and 5.5.
|===


[[beaxt]][[GSDPG00278]][[steady-pool-size]]

=== `steady-pool-size`

Specifies the initial and minimum number of bean instances that are
maintained in the pool. Default is 32. Applies to stateless session
beans and message-driven beans.

[[fvziq]][[GSDPG00743]][[superelements-194]]

==== Superelements

link:#bearb[`bean-pool`] (`glassfish-ejb-jar.xml`)

[[fvziy]][[GSDPG00744]][[subelements-186]]

==== Subelements

none - contains data

[[beaxu]][[GSDPG00279]][[store-properties]]

=== `store-properties`

Specifies session persistence (storage) properties.

[[fvzie]][[GSDPG00745]][[superelements-195]]

==== Superelements

link:#beaxq[`session-manager`] (`glassfish-web.xml`)

[[fvzid]][[GSDPG00746]][[subelements-187]]

==== Subelements

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

[[GSDPG1029]][[sthref227]][[fvzif]]


Table C-147 `store-properties` Subelements

[width="100%",cols="37%,14%,49%",options="header",]
|===
|Element |Required |Description
a|
link:#beavx[`property` (with attributes)]


 |zero or more |Specifies a property, which has a name and a value.
|===


[[fvzho]][[GSDPG00747]][[properties-14]]

==== Properties

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

[[GSDPG1030]][[sthref228]][[fvzgr]]


Table C-148 `store-properties` Properties

[width="100%",cols="21%,23%,56%",options="header",]
|===
|Property |Default |Description
|`directory` |domain-dir``/generated/jsp/``app-name``/``module-name``_war`` a|
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 module.

Applicable only if the `persistence-type` attribute of the parent
link:#beaxq[`session-manager`] element is `file`.

|`persistenceScope` |`session` a|
Specifies how much of the session state is stored. Allowed values are as
follows:

* `session` - The entire session state is stored every time. This mode
provides the best guarantee that your session data is correctly stored
for any distributable web module.
* `modified-session` - The entire session state is stored if it has been
modified. A session is considered to have been modified if
`HttpSession.setAttribute()` or `HttpSession.removeAttribute()` was
called. You must guarantee that `setAttribute` is called every time an
attribute is changed. This is not a Jakarta EE specification requirement,
but it is required for this mode to work properly.
* `modified-attribute` - Only modified session attributes are stored.
For this mode to work properly, you must follow some guidelines, which
are explained immediately following this table.

Applicable only if the `persistence-type` attribute of the parent
link:#beaxq[`session-manager`] element is `replicated`.

|===


If the `persistenceScope` store property is set to `modified-attribute`,
a web module must follow these guidelines:

* Call `setAttribute` every time the session state is modified.
* Make sure there are no cross-references between attributes. The object
graph under each distinct attribute key is serialized and stored
separately. If there are any object cross references between the objects
under each separate key, they are not serialized and deserialized
correctly.
* Distribute the session state across multiple attributes, or at least
between a read-only attribute and a modifiable attribute.

[[beaxv]][[GSDPG00280]][[stub-property]]

=== `stub-property`

Specifies JAX-RPC property values that are set on a `javax.xml.rpc.Stub`
object before it is returned to the web service client. The property
names can be any properties supported by the JAX-RPC `Stub`
implementation.

[[fvzgu]][[GSDPG00748]][[superelements-196]]

==== Superelements

link:#beavt[`port-info`] (`glassfish-web.xml`, `glassfish-ejb-jar.xml`,
`glassfish-application-client.xml`)

[[fvzij]][[GSDPG00749]][[subelements-188]]

==== Subelements

The following table describes subelements for the `stub-property`
element.

[[GSDPG1031]][[sthref229]][[fvziz]]


Table C-149 `stub-property` subelements

[width="100%",cols="23%,13%,64%",options="header",]
|===
|Element |Required |Description
a|
link:#beavf[`name`]


 |only one |Specifies the name of the entity.
a|
link:#beayo[`value`]


 |only one |Specifies the value of the entity.
|===


[[gawoa]][[GSDPG00750]][[properties-15]]

==== Properties

The following table describes properties for the `stub-property`
element.

[[GSDPG1032]][[sthref230]][[gawou]]


Table C-150 `stub-property` properties

[width="181%",cols="10%,49%,41%",options="header",]
|===
|Property |Default |Description
|`jbi-enabled` |`true` |Determines whether the visibility of this
endpoint as a Java Business Integration service is enabled or disabled.
|===


[[fvzji]][[GSDPG00751]][[example-12]]

==== Example

[source,xml]
----
<service-ref>
<service-ref-name>service/FooProxy</service-ref-name>
  <port-info>
       <service-endpoint-interface>a.FooPort</service-endpoint-interface>
       <wsdl-port>
          <namespaceURI>urn:Foo</namespaceURI>
          <localpart>FooPort</localpart>
       </wsdl-port>
       <stub-property>
          <name>javax.xml.rpc.service.endpoint.address</name>
          <value>http://localhost:8080/a/Foo</value>
       </stub-property>
  </port-info>
</service-ref>
----

[[beaxy]][[GSDPG00281]][[sun-cmp-mapping]]

=== `sun-cmp-mapping`

Specifies beans mapped to a particular database schema.


[NOTE]
====
A bean cannot be related to a bean that maps to a different database
schema, even if the beans are deployed in the same EJB JAR file.
====


[[fvzhh]][[GSDPG00752]][[superelements-197]]

==== Superelements

link:#beaxz[`sun-cmp-mappings`] (`sun-cmp-mappings.xml`)

[[fvzjg]][[GSDPG00753]][[subelements-189]]

==== Subelements

The following table describes subelements for the `sun-cmp-mapping`
element.

[[GSDPG1033]][[sthref231]][[fvzhm]]


Table C-151 `sun-cmp-mapping` Subelements

[width="100%",cols="20%,13%,67%",options="header",]
|===
|Element |Required |Description
a|
link:#beaxc[`schema`]


 |only one |Specifies the file that contains a description of the
database schema.

a|
link:#beasy[`entity-mapping`]


 |one or more |Specifies the mapping of a bean to database columns.
|===


[[beaxz]][[GSDPG00282]][[sun-cmp-mappings]]

=== `sun-cmp-mappings`

Defines the {productName} specific CMP mapping configuration for an
EJB JAR file. This is the root element; there can only be one
`sun-cmp-mappings` element in a `sun-cmp-mappings.xml` file. See
link:dd-files.html#beaqn[The sun-cmp-mappings.xml File].

[[fvzix]][[GSDPG00754]][[superelements-198]]

==== Superelements

none

[[fvzjj]][[GSDPG00755]][[subelements-190]]

==== Subelements

The following table describes subelements for the `sun-cmp-mappings`
element.

[[GSDPG1034]][[sthref232]][[fvzin]]


Table C-152 `sun-cmp-mappings` Subelements

[width="100%",cols="32%,16%,52%",options="header",]
|===
|Element |Required |Description
a|
link:#beaxy[`sun-cmp-mapping`]


 |one or more |Specifies beans mapped to a particular database schema.
|===


[[beayd]][[GSDPG00283]][[table-name]]

=== `table-name`

Specifies the name of a database table. The table must be present in the
database schema file. See "link:application-development-guide/container_managed-persistence.html#GSDVG00439[Automatic Database Schema
Capture]" in {productName} Application
Development Guide.

[[fvzis]][[GSDPG00756]][[superelements-199]]

==== Superelements

link:#beasy[`entity-mapping`], link:#beaxe[`secondary-table`]
(`sun-cmp-mappings.xml`)

[[fvzjk]][[GSDPG00757]][[subelements-191]]

==== Subelements

none - contains data

[[beaye]][[GSDPG00284]][[target-server]]

=== `target-server`

Specifies the IIOP listener for the target server. Also specifies IIOP
endpoints used for load balancing. If the {productName} instance on
which the application client is deployed participates in a cluster,
{productName} finds all currently active IIOP endpoints in the
cluster automatically. However, a client should have at least two
endpoints specified for bootstrapping purposes, in case one of the
endpoints has failed.

A listener or endpoint is in the form host`:`port, where the host is an
IP address or host name, and the port specifies the port number.

Not used if the deprecated `endpoints` property is defined for load
balancing. For more information, see link:#bearr[`client-container`].

[[fvzgy]][[GSDPG00758]][[superelements-200]]

==== Superelements

link:#bearr[`client-container`] (`sun-acc.xml`)

[[fvzhi]][[GSDPG00759]][[subelements-192]]

==== Subelements

The following table describes subelements for the `target-server`
element.

[[GSDPG1035]][[sthref233]][[fvzhg]]


Table C-153 `target-server` subelements

[width="100%",cols="23%,14%,63%",options="header",]
|===
|Element |Required |Description
a|
link:#beaso[`description`]


 |zero or one |Specifies the description of the target server.

a|
link:#beaxf[`security`]


 |zero or one |Specifies the security configuration for the IIOP/SSL
communication with the target server.
|===


[[fvzfp]][[GSDPG00760]][[attributes-42]]

==== Attributes

The following table describes attributes for the `target-server`
element.

[[GSDPG1036]][[sthref234]][[fvzgg]]


Table C-154 `target-server` attributes

[width="181%",cols="7%,49%,44%",options="header",]
|===
|Attribute |Default |Description
|`name` |none |Specifies the name of the server instance accessed by the
client container.

|`address` |none |Specifies the host name or IP address (resolvable by
DNS) of the server to which this client attaches.

|`port` |none a|
Specifies the naming service port number of the server to which this
client attaches.

For a new server instance, assign a port number other than 3700. You can
change the port number in the Administration Console. Click the Help
button in the Administration Console for more information.

|===


[[beayf]][[GSDPG00285]][[tie-class]]

=== `tie-class`

Specifies the automatically generated name of a tie implementation class
for a port component.

[[fvzgz]][[GSDPG00761]][[superelements-201]]

==== Superelements

link:#beayv[`webservice-endpoint`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`)

[[fvzfq]][[GSDPG00762]][[subelements-193]]

==== Subelements

none - contains data

[[beayg]][[GSDPG00286]][[timeout]]

=== `timeout`

Specifies the link:#bearh[`cache-mapping`] specific maximum amount of
time in seconds that an entry can remain in the cache after it is
created or refreshed. If not specified, the default is the value of the
`timeout` attribute of the link:#beard[`cache`] element.

[[fvzhc]][[GSDPG00763]][[superelements-202]]

==== Superelements

link:#bearh[`cache-mapping`] (`glassfish-web.xml`)

[[fvziv]][[GSDPG00764]][[subelements-194]]

==== Subelements

none - contains data

[[fvzhd]][[GSDPG00765]][[attributes-43]]

==== Attributes

The following table describes attributes for the `timeout` element.

[[GSDPG1037]][[sthref235]][[fvzih]]


Table C-155 `timeout` Attributes

[width="181%",cols="51%,11%,38%",options="header",]
|===
|Attribute |Default |Description
|`name` |none |Specifies the timeout input parameter, whose value is
interpreted in seconds. The field's type must be `java.lang.Long` or
`java.lang.Integer`.

|`scope` |`request.attribute` |(optional) Specifies the scope from which
the input parameter is retrieved. Allowed values are
`context.attribute`, `request.header`, `request.parameter`,
`request.cookie`, `request.attribute`, and `session.attribute`.
|===


[[beayh]][[GSDPG00287]][[transport-config]]

=== `transport-config`

Specifies the security transport information.

[[fvzfo]][[GSDPG00766]][[superelements-203]]

==== Superelements

link:#beato[`ior-security-config`] (`glassfish-ejb-jar.xml`)

[[fvzhv]][[GSDPG00767]][[subelements-195]]

==== Subelements

The following table describes subelements for the `transport-config`
element.

[[GSDPG1038]][[sthref236]][[fvziu]]


Table C-156 `transport-config` Subelements

[width="100%",cols="30%,10%,60%",options="header",]
|===
|Element |Required |Description
a|
link:#beatn[`integrity`]


 |only one |Specifies if the target supports integrity-protected
messages. The values are NONE, SUPPORTED, or REQUIRED.

a|
link:#beasc[`confidentiality`]


 |only one |Specifies if the target supports privacy-protected messages.
The values are NONE, SUPPORTED, or REQUIRED.

a|
link:#beata[`establish-trust-in-target`]


 |only one |Specifies if the target is capable of authenticating to a
client. The values are NONE, SUPPORTED, or REQUIRED.

a|
link:#beasz[`establish-trust-in-client`]


 |only one |Specifies if the target is capable of authenticating a
client. The values are NONE, SUPPORTED, or REQUIRED.
|===


[[beayi]][[GSDPG00288]][[transport-guarantee]]

=== `transport-guarantee`

Specifies that the communication between client and server is `NONE`,
`INTEGRAL`, or `CONFIDENTIAL`.

* `NONE` means the application does not require any transport
guarantees.
* `INTEGRAL` means the application requires that the data sent between
client and server be sent in such a way that it can't be changed in
transit.
* `CONFIDENTIAL` means the application requires that the data be
transmitted in a fashion that prevents other entities from observing the
contents of the transmission.

In most cases, a value of `INTEGRAL` or `CONFIDENTIAL` indicates that
the use of SSL is required.

[[fvzhb]][[GSDPG00768]][[superelements-204]]

==== Superelements

link:#beayv[`webservice-endpoint`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`)

[[fvzgl]][[GSDPG00769]][[subelements-196]]

==== Subelements

none - contains data

[[beayk]][[GSDPG00289]][[unique-id]]

=== `unique-id`

Contains the unique ID for the application. This value is automatically
updated each time the application is deployed or redeployed. Do not edit
this value.

[[fvzig]][[GSDPG00770]][[superelements-205]]

==== Superelements

link:#beaxw[`glassfish-application`] (`glassfish-application.xml`),
link:#beasx[`enterprise-beans`] (`glassfish-ejb-jar.xml`)

[[fvzjc]][[GSDPG00771]][[subelements-197]]

==== Subelements

none - contains data

[[beayl]][[GSDPG00290]][[url-pattern]]

=== `url-pattern`

Specifies a servlet URL pattern for which caching is enabled. See the
Servlet 2.4 specification section SRV. 11.2 for applicable patterns.

[[fvziw]][[GSDPG00772]][[superelements-206]]

==== Superelements

link:#bearh[`cache-mapping`] (`glassfish-web.xml`)

[[fvzfw]][[GSDPG00773]][[subelements-198]]

==== Subelements

none - contains data

[[giyiq]][[GSDPG00291]][[user-group]]

=== `user-group`

Contains the group to which the principal belongs.

[[GSDPG1039]][[sthref237]]


[[superelements-207]]
==== Superelements

link:#giyhy[`security-map`] (`glassfish-resources.xml`)

[[GSDPG1040]][[sthref238]]


[[subelements-199]]
==== Subelements

none - contains data

[[beaym]][[GSDPG00292]][[use-thread-pool-id]]

=== `use-thread-pool-id`

Specifies the thread pool from which threads are selected for remote
invocations of this bean.

[[fvzhz]][[GSDPG00774]][[superelements-208]]

==== Superelements

link:#beass[`ejb`] (`glassfish-ejb-jar.xml`)

[[fvzhp]][[GSDPG00775]][[subelements-200]]

==== Subelements

none - contains data

[[beayo]][[GSDPG00293]][[value]]

=== `value`

Specifies the value of the entity.

[[fvzhq]][[GSDPG00776]][[superelements-209]]

==== Superelements

link:#beari[`call-property`], link:#beaxv[`stub-property`]
(`glassfish-web.xml`, `glassfish-ejb-jar.xml`,
`glassfish-application-client.xml`); link:#beavy[`property` (with
subelements)] (`glassfish-ejb-jar.xml`)

[[fvzhe]][[GSDPG00777]][[subelements-201]]

==== Subelements

none - contains data

[[gikqk]][[GSDPG00294]][[valve]]

=== `valve`

Specifies a custom valve for this web application. You can define a
valve for all the web applications on a specific virtual server. For
details, see link:reference-manual/create-virtual-server.html#GSRFM00062[`create-virtual-server`(1)].

[[giksf]][[GSDPG00778]][[superelements-210]]

==== Superelements

link:#beayb[`glassfish-web-app`] (`glassfish-web.xml`)

[[gikvt]][[GSDPG00779]][[subelements-202]]

==== Subelements

The following table describes subelements for the `valve` element.

[[GSDPG1041]][[sthref239]][[giktu]]


Table C-157 `valve` Subelements

[width="100%",cols="25%,12%,63%",options="header",]
|===
|Element |Required |Description
a|
link:#beaso[`description`]


 |zero or one |Specifies a text description of this element.
a|
link:#beavx[`property` (with attributes)]


 |zero or more |Specifies a property, which has a name and a value.
|===


[[gikuo]][[GSDPG00780]][[attributes-44]]

==== Attributes

The following table describes attributes for the `valve` element.

[[GSDPG1042]][[sthref240]][[gikqw]]


Table C-158 `valve` Attributes

[width="172%",cols="9%,46%,45%",options="header",]
|===
|Attribute |Default |Description
|`name` |none |Specifies a unique name for the valve.

|`class-name` |none |Specifies the fully qualified class name of the
valve. The valve class must implement the org.apache.catalina.Valve
interface from Tomcat or previous {productName} releases, or the
org.glassfish.web.valve.GlassFishValve interface from the current
{productName} release.
|===


[[giksd]][[GSDPG00781]][[example-13]]

==== Example

[source,xml]
----
<valve name="MyValve" classname="org.glassfish.extension.Valve">
   <property name="MyProperty1" value="MyValue1" />
   <property name="MyProperty2" value="MyValue2" />
</valve>
----

[[gbgdw]][[GSDPG00295]][[vendor]]

=== `vendor`

Specifies a vendor-specific icon, splash screen, text string, or a
combination of these for Java Web Start download and launch screens. The
complete format of this element's data is as follows:

[source,xml]
----
<vendor>icon-image-URI::splash-screen-image-URI::vendor-text</vendor>
----

The following example vendor element contains an icon, a splash screen,
and a text string:

[source,xml]
----
<vendor>images/icon.jpg::otherDir/splash.jpg::MyCorp, Inc.</vendor>
----

The following example vendor element contains an icon and a text string:

[source,xml]
----
<vendor>images/icon.jpg::MyCorp, Inc.</vendor>
----

The following example vendor element contains a splash screen and a text
string; note the initial double colon:

[source,xml]
----
<vendor>::otherDir/splash.jpg::MyCorp, Inc.</vendor>
----

The following example vendor element contains only a text string:

[source,xml]
----
<vendor>MyCorp, Inc.</vendor>
----

The default value is the text string `Application Client`.

[[gbgdu]][[GSDPG00782]][[superelements-211]]

==== Superelements

link:#gauax[`java-web-start-access`]
(`glassfish-application-client.xml`)

[[gbgcq]][[GSDPG00783]][[subelements-203]]

==== Subelements

none - contains data

[[gkkfd]][[GSDPG00296]][[version-identifier]]

=== `version-identifier`

Contains version information for an application or module. For more
information about application versioning, see
link:overview.html#gkhhv[Module and Application Versions].

[[GSDPG1043]][[sthref241]]


[[superelements-212]]
==== Superelements

link:#beaxw[`glassfish-application`] (`glassfish-application.xml`),
link:#beayb[`glassfish-web-app`] (`glassfish-web-app.xml`),
link:#beaya[`glassfish-ejb-jar`] (`glassfish-ejb-jar.xml`),
link:#beaxx[`glassfish-application-client`]
(`glassfish-application-client.xml`)

[[GSDPG1044]][[sthref242]]


[[subelements-204]]
==== Subelements

none - contains data

[[beayp]][[GSDPG00297]][[victim-selection-policy]]

=== `victim-selection-policy`

Specifies how stateful session beans are selected for passivation.
Possible values are First In, First Out (`FIFO`), Least Recently Used
(`LRU`), Not Recently Used (`NRU`). The default value is `NRU`, which is
actually pseudo-LRU.


[NOTE]
====
You cannot plug in your own victim selection algorithm.
====


The victims are generally passivated into a backup store (typically a
file system or database). This store is cleaned during startup, and also
by a periodic background process that removes idle entries as specified
by `removal-timeout-in-seconds`. The backup store is monitored by a
background thread (or sweeper thread) to remove unwanted entries.

Applies to stateful session beans.

[[fvzhu]][[GSDPG00784]][[superelements-213]]

==== Superelements

link:#beara[`bean-cache`] (`glassfish-ejb-jar.xml`)

[[fvzfr]][[GSDPG00785]][[subelements-205]]

==== Subelements

none - contains data

[[fvzgi]][[GSDPG00786]][[example-14]]

==== Example

[source,xml]
----
<victim-selection-policy>LRU</victim-selection-policy>
----

If both SSL2 and SSL3 are enabled, the server tries SSL3 encryption
first. If that fails, the server tries SSL2 encryption. 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.

[[beayr]][[GSDPG00298]][[web]]

`web`
~~~~~

Specifies the application's web tier configuration.

[[fvzil]][[GSDPG00787]][[superelements-214]]

==== Superelements

link:#beaxw[`glassfish-application`] (`glassfish-application.xml`)

[[fvzge]][[GSDPG00788]][[subelements-206]]

==== Subelements

The following table describes subelements for the `web` element.

[[GSDPG1045]][[sthref243]][[fvzfz]]


Table C-159 `web` Subelements

[width="100%",cols="24%,11%,65%",options="header",]
|===
|Element |Required |Description
a|
link:#beays[`web-uri`]


 |only one |Contains the web URI for the application.
a|
link:#beasg[`context-root`]


 |only one |Contains the web context root for the web module.
|===


[[beays]][[GSDPG00299]][[web-uri]]

=== `web-uri`

Contains the web URI for the application. Must match the corresponding
element in the `application.xml` file.

[[fvzhk]][[GSDPG00789]][[superelements-215]]

==== Superelements

link:#beayr[`web`] (`glassfish-application.xml`)

[[fvzik]][[GSDPG00790]][[subelements-207]]

==== Subelements

none - contains data

[[beayt]][[GSDPG00300]][[webservice-description]]

=== `webservice-description`

Specifies a name and optional publish location for a web service.

[[fvzjd]][[GSDPG00791]][[superelements-216]]

==== Superelements

link:#beayb[`glassfish-web-app`] (`glassfish-web.xml`),
link:#beasx[`enterprise-beans`] (`glassfish-ejb-jar.xml`)

[[fvzgs]][[GSDPG00792]][[subelements-208]]

==== Subelements

The following table describes subelements for the
`webservice-description` element.

[[GSDPG1046]][[sthref244]][[fvzjb]]


Table C-160 `webservice-description` subelements

[width="100%",cols="33%,11%,56%",options="header",]
|===
|Element |Required |Description
a|
link:#beayu[`webservice-description-name`]


 |only one |Specifies a unique name for the web service within a web or
EJB module.

a|
link:#beayy[`wsdl-publish-location`]


 |zero or one |Specifies the URL of a directory to which a web service's
WSDL is published during deployment.
|===


[[beayu]][[GSDPG00301]][[webservice-description-name]]

=== `webservice-description-name`

Specifies a unique name for the web service within a web or EJB module.

[[fvzgp]][[GSDPG00793]][[superelements-217]]

==== Superelements

link:#beayt[`webservice-description`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`)

[[fvzgw]][[GSDPG00794]][[subelements-209]]

==== Subelements

none - contains data

[[beayv]][[GSDPG00302]][[webservice-endpoint]]

=== `webservice-endpoint`

Specifies information about a web service endpoint.

[[fvzio]][[GSDPG00795]][[superelements-218]]

==== Superelements

link:#beaxm[`servlet`] (`glassfish-web.xml`), link:#beass[`ejb`]
(`glassfish-ejb-jar.xml`)

[[fvzjp]][[GSDPG00796]][[subelements-210]]

==== Subelements

The following table describes subelements for the `webservice-endpoint`
element.

[[GSDPG1047]][[sthref245]][[fvzjs]]


Table C-161 `webservice-endpoint` subelements

[width="100%",cols="29%,12%,59%",options="header",]
|===
|Element |Required |Description
a|
link:#beavs[`port-component-name`]


 |only one |Specifies a unique name for a port component within a web or
EJB module.

a|
link:#beasw[`endpoint-address-uri`]


 |zero or one |Specifies the automatically generated endpoint address.

a|
link:#beauk[`login-config`]


 |zero or one |Specifies the authentication configuration for an EJB web
service endpoint.

a|
link:#beaux[`message-security-binding`]


 |zero or one |Specifies a custom authentication provider binding.

a|
link:#beayi[`transport-guarantee`]


 |zero or one |Specifies that the communication between client and
server is `NONE`, `INTEGRAL`, or `CONFIDENTIAL`.

a|
link:#beaxj[`service-qname`]


 |zero or one |Specifies the WSDL service element that is being
referenced.

a|
link:#beayf[`tie-class`]


 |zero or one |Specifies the automatically generated name of a tie
implementation class for a port component.

a|
link:#beaxn[`servlet-impl-class`]


 |zero or one |Specifies the automatically generated name of the
generated servlet implementation class.

a|
link:#gaubj[`debugging-enabled`]


 |zero or one |Specifies whether the debugging servlet is enabled for
this web service endpoint. Allowed values are `true` and `false` (the
default).

a|
link:#beavx[`property` (with attributes)] (`glassfish-web.xml`)

link:#beavy[`property` (with subelements)] (`glassfish-ejb-jar.xml`)

 |zero or more |Specifies a property, which has a name and a value.
|===


[[giyht]][[GSDPG00303]][[work-security-map]]

=== `work-security-map`

Defines a work security map, which maps a principal associated with an
incoming work instance to a principal in the {productName}'s security
domain. It is possible to map multiple EIS group or user principals to
the same {productName} principal.

This is different from a link:#giyhy[`security-map`], which maps the
principal received during servlet or EJB authentication to the
credentials accepted by the EIS.

[[GSDPG1048]][[sthref246]]


[[superelements-219]]
==== Superelements

link:#giyiy[`resources`] (`glassfish-resources.xml`)

[[giyih]][[GSDPG00797]][[subelements-211]]

==== Subelements

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

[[GSDPG1049]][[sthref247]][[sthref248]]


Table C-162 `work-security-map` Subelements

[width="100%",cols="17%,12%,71%",options="header",]
|===
|Element |Required |Description
a|
link:#beaso[`description`]


 |zero or one |Contains a text description of this element.

a|
link:#giyif[`principal-map`]


 |zero or more |Maps an EIS principal to a principal defined in the
{productName} domain.

a|
link:#giygy[`group-map`]


 |zero or more |Maps an EIS group to a group defined in the {productName} domain.
|===


[[GSDPG1050]][[sthref249]]


[[attributes-45]]
==== Attributes

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

[[GSDPG1051]][[sthref250]][[sthref251]]


Table C-163 `work-security-map` Attributes

[width="181%",cols="13%,49%,38%",options="header",]
|===
|Attribute |Default |Description
|`name` |none |Specifies a unique name for the work security map.
|`description` |none |Specifies a text description for this element.
|===


[[beayw]][[GSDPG00304]][[wsdl-override]]

=== `wsdl-override`

Specifies a valid URL pointing to a final WSDL document. If not
specified, the WSDL document associated with the `service-ref` in the
standard Jakarta EE deployment descriptor is used.

[[fvzjl]][[GSDPG00798]][[superelements-220]]

==== Superelements

link:#beaxk[`service-ref`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`, `glassfish-application-client.xml`)

[[fvzjq]][[GSDPG00799]][[subelements-212]]

==== Subelements

none - contains data

[[fvzjt]][[GSDPG00800]][[example-15]]

==== Example

[source,xml]
----
// available via HTTP
<wsdl-override>http://localhost:8000/myservice/myport?WSDL</wsdl-override>

// in a file
<wsdl-override>file:/home/user1/myfinalwsdl.wsdl</wsdl-override>
----

[[beayx]][[GSDPG00305]][[wsdl-port]]

=== `wsdl-port`

Specifies the WSDL port.

[[fvzjo]][[GSDPG00801]][[superelements-221]]

==== Superelements

link:#beavt[`port-info`] (`glassfish-web.xml`, `glassfish-ejb-jar.xml`,
`glassfish-application-client.xml`)

[[fvzjm]][[GSDPG00802]][[subelements-213]]

==== Subelements

The following table describes subelements for the `wsdl-port` element.

[[GSDPG1052]][[sthref252]][[fvzju]]


Table C-164 `wsdl-port` subelements

[width="100%",cols="30%,11%,59%",options="header",]
|===
|Element |Required |Description
a|
link:#beavh[`namespaceURI`]


 |only one |Specifies the namespace URI.
a|
link:#beaug[`localpart`]


 |only one |Specifies the local part of a QNAME.
|===


[[beayy]][[GSDPG00306]][[wsdl-publish-location]]

=== `wsdl-publish-location`

Specifies the URL of a directory to which a web service's WSDL is
published during deployment. Any required files are published to this
directory, preserving their location relative to the module-specific
WSDL directory (`META-INF/wsdl` or `WEB-INF/wsdl`).

[[fvzjw]][[GSDPG00803]][[superelements-222]]

==== Superelements

link:#beayt[`webservice-description`] (`glassfish-web.xml`,
`glassfish-ejb-jar.xml`)

[[fvzjr]][[GSDPG00804]][[subelements-214]]

==== Subelements

none - contains data

[[fvzjn]][[GSDPG00805]][[example-16]]

==== Example

Suppose you have an `ejb.jar` file whose `webservices.xml` file's
`wsdl-file` element contains the following reference:

[source]
----
META-INF/wsdl/a/Foo.wsdl
----

Suppose your `glassfish-ejb.jar` file contains the following element:

[source,xml]
----
<wsdl-publish-location>file:/home/user1/publish</wsdl-publish-location>
----

The final WSDL is stored in `/home/user1/publish/a/Foo.wsdl`.