|
| |
| Sun Java System Application Server Enterprise Edition 8.1 2005Q1 Developer's Guide | |
Appendix A
Deployment Descriptor FilesThis chapter describes deployment descriptor files specific to the Sun Java System Application Server in the following sections:
Sun Java System Application Server DescriptorsSun Java System Application Server uses deployment descriptors in addition to the J2EE standard descriptors for configuring features specific to the Sun Java System Application Server. The sun-application.xml, sun-web.xml, and sun-cmp-mappings.xml files are optional; all the others are required.
Each deployment descriptor (or XML) file has a corresponding DTD file, which defines the elements, data, and attributes that the deployment descriptor file can contain. For example, the sun-application_1_4-0.dtd file defines the structure of the sun-application.xml file. The DTD files for the Sun Java System Application Server deployment descriptors are located in the install_dir/lib/dtds directory.
Note
Do not edit the DTD files; their contents change only with new versions of Sun Java System Application Server.
To check the correctness of these deployment descriptors prior to deployment, see “The Deployment Descriptor Verifier” on page 80.
For general information about DTD files and XML, see the XML specification at:
The following table lists the Sun Java System Application Server deployment descriptors and their DTD files.
The sun-application.xml FileThe element hierarchy in the sun-application.xml file is as follows:
sun-application
. web
. . web-uri
. . context-root
. pass-by-reference
. unique-id
. security-role-mapping
. . role-name
. . principal-name
. . group-name
. realmHere is a sample sun-application.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sun-application PUBLIC '-//Sun Microsystems, Inc.//DTD Application Server 8.1 J2EE Application 1.4//EN' 'http://www.sun.com/software/appserver/dtds/sun-application_1_4-0.dtd'>
<sun-application>
<unique-id>67488732739338240</unique-id>
</sun-application>
The sun-web.xml FileThe element hierarchy in the sun-web.xml file is as follows:
sun-web-app
. context-root
. security-role-mapping
. . role-name
. . principal-name
. . group-name
. servlet
. . servlet-name
. . principal-name
. . webservice-endpoint
. . . port-component-name
. . . endpoint-address-uri
. . . login-config
. . . . auth-method
. . . message-security-binding
. . . . message-security
. . . . . message
. . . . . . java-method
. . . . . . . method-name
. . . . . . . method-params
. . . . . . . . method-param
. . . . . . operation-name
. . . . . request-protection
. . . . . response-protection
. . . transport-guarantee
. . . service-qname
. . . tie-class
. . . servlet-impl-class
. idempotent-url-pattern
. session-config
. . session-manager
. . . manager-properties
. . . . property (with attributes)
. . . . . description
. . . store-properties
. . . . property (with attributes)
. . . . . description
. . session-properties
. . . property (with attributes)
. . . . description
. . cookie-properties
. . . property (with attributes)
. . . . description
. ejb-ref
. . ejb-ref-name
. . jndi-name
. resource-ref
. . res-ref-name
. . jndi-name
. . default-resource-principal
. . . name
. . . password
. resource-env-ref
. . resource-env-ref-name
. . jndi-name
. service-ref
. . service-ref-name
. . port-info
. . . service-endpoint-interface
. . . wsdl-port
. . . . namespaceURI
. . . . localpart
. . . stub-property
. . . . name
. . . . value
. . . call-property
. . . . name
. . . . value
. . . message-security-binding
. . . . message-security
. . . . . message
. . . . . . java-method
. . . . . . . method-name
. . . . . . . method-params
. . . . . . . . method-param
. . . . . . operation-name
. . . . . request-protection
. . . . . response-protection
. . call-property
. . . name
. . . value
. . wsdl-override
. . service-impl-class
. . service-qname
. . . namespaceURI
. . . localpart
. cache
. . cache-helper
. . . property (with attributes)
. . . . description
. . default-helper
. . . property (with attributes)
. . . . description
. . property (with attributes)
. . . description
. . cache-mapping
. . . servlet-name
. . . url-pattern
. . . cache-helper-ref
. . . dispatcher
. . . timeout
. . . refresh-field
. . . http-method
. . . key-field
. . . constraint-field
. . . . constraint-field-value
. class-loader
. . property (with attributes)
. . . description
. jsp-config
. locale-charset-info
. . locale-charset-map
. . parameter-encoding
. property (with attributes)
. . description
. parameter-encoding
. message-destination
. . message-destination-name
. . jndi-name
. webservice-description
. . webservice-description-name
. . wsdl-publish-locationHere is a sample sun-web.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sun-web-app PUBLIC '-//Sun Microsystems, Inc.//DTD Application Server 8.1 Servlet 2.4//EN' 'http://www.sun.com/software/appserver/dtds/sun-web-app_2_4-1.dtd'>
<sun-web-app>
<session-config>
<session-manager/>
</session-config>
<resource-ref>
<res-ref-name>mail/Session</res-ref-name>
<jndi-name>mail/Session</jndi-name>
</resource-ref>
<jsp-config/>
</sun-web-app>
The sun-ejb-jar.xml FileThe element hierarchy in the sun-ejb-jar.xml file is as follows:
sun-ejb-jar
. security-role-mapping
. . role-name
. . principal-name
. . group-name
. enterprise-beans
. . name
. . unique-id
. . ejb
. . . ejb-name
. . . jndi-name
. . . ejb-ref
. . . . ejb-ref-name
. . . . jndi-name
. . . resource-ref
. . . . res-ref-name
. . . . jndi-name
. . . . default-resource-principal
. . . . . name
. . . . . password
. . . resource-env-ref
. . . . resource-env-ref-name
. . . . jndi-name
. . . service-ref
. . . . service-ref-name
. . . . port-info
. . . . . service-endpoint-interface
. . . . . wsdl-port
. . . . . . namespaceURI
. . . . . . localpart
. . . . . stub-property
. . . . . . name
. . . . . . value
. . . . . call-property
. . . . . . name
. . . . . . value
. . . . . message-security-binding
. . . . . . message-security
. . . . . . . message
. . . . . . . . java-method
. . . . . . . . . method-name
. . . . . . . . . method-params
. . . . . . . . . . method-param
. . . . . . . . operation-name
. . . . . . . request-protection
. . . . . . . response-protection
. . . . call-property
. . . . . name
. . . . . value
. . . . wsdl-override
. . . . service-impl-class
. . . . service-qname
. . . . . namespaceURI
. . . . . localpart
. . . pass-by-reference
. . . cmp
. . . . mapping-properties
. . . . is-one-one-cmp
. . . . one-one-finders
. . . . . finder
. . . . . . method-name
. . . . . . query-params
. . . . . . query-filter
. . . . . . query-variables
. . . . . . query-ordering
. . . . prefetch-disabled
. . . . . query-method
. . . . . . method-name
. . . . . . method-params
. . . . . . . method-param
. . . principal
. . . . name
. . . mdb-connection-factory
. . . . jndi-name
. . . . default-resource-principal
. . . . . name
. . . . . password
. . . jms-durable-subscription-name
. . . jms-max-messages-load
. . . ior-security-config
. . . . transport-config
. . . . . integrity
. . . . . confidentiality
. . . . . establish-trust-in-target
. . . . . establish-trust-in-client
. . . . as-context
. . . . . auth-method
. . . . . realm
. . . . . required
. . . . sas-context
. . . . . caller-propagation
. . . is-read-only-bean
. . . refresh-period-in-seconds
. . . commit-option
. . . cmt-timeout-in-seconds
. . . use-thread-pool-id
. . . gen-classes
. . . . remote-impl
. . . . local-impl
. . . . remote-home-impl
. . . . local-home-impl
. . . bean-pool
. . . . steady-pool-size
. . . . resize-quantity
. . . . max-pool-size
. . . . pool-idle-timeout-in-seconds
. . . . max-wait-time-in-millis
. . . bean-cache
. . . . max-cache-size
. . . . resize-quantity
. . . . is-cache-overflow-allowed
. . . . cache-idle-timeout-in-seconds
. . . . removal-timeout-in-seconds
. . . . victim-selection-policy
. . . mdb-resource-adapter
. . . . resource-adapter-mid
. . . . activation-config
. . . . . description
. . . . . activation-config-property
. . . . . . activation-config-property-name
. . . . . . activation-config-property-value
. . . webservice-endpoint
. . . . port-component-name
. . . . endpoint-address-uri
. . . . login-config
. . . . . auth-method
. . . . message-security-binding
. . . . . message-security
. . . . . . message
. . . . . . . java-method
. . . . . . . . method-name
. . . . . . . . method-params
. . . . . . . . . method-param
. . . . . . . operation-name
. . . . . . request-protection
. . . . . . response-protection
. . . . transport-guarantee
. . . . service-qname
. . . . tie-class
. . . . servlet-impl-class
. . . flush-at-end-of-method
. . . . method
. . . . . description
. . . . . ejb-name
. . . . . method-name
. . . . . method-intf
. . . . . method-params
. . . . . . method-param
. . . checkpointed-methods
. . . checkpoint-at-end-of-method
. . . . method
. . . . . description
. . . . . ejb-name
. . . . . method-name
. . . . . method-intf
. . . . . method-params
. . . . . . method-param
. . pm-descriptors
. . cmp-resource
. . . jndi-name
. . . default-resource-principal
. . . . name
. . . . password
. . . property (with subelements)
. . . . name
. . . . value
. . . create-tables-at-deploy
. . . drop-tables-at-undeploy
. . . database-vendor-name
. . . schema-generator-properties
. . . . property (with subelements)
. . . . . name
. . . . . value
. . message-destination
. . . message-destination-name
. . . jndi-name
. . webservice-description
. . . webservice-description-name
. . . wsdl-publish-location
Note
If any configuration information for an enterprise bean is not specified in the sun-ejb-jar.xml file, it defaults to a corresponding setting in the EJB container if an equivalency exists.
Here is a sample sun-ejb-jar.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sun-ejb-jar PUBLIC '-//Sun Microsystems, Inc.//DTD Application Server 8.1 EJB 2.1//EN' 'http://www.sun.com/software/appserver/dtds/sun-ejb-jar_2_1-1.dtd'>
<sun-ejb-jar>
<display-name>First Module</display-name>
<enterprise-beans>
<ejb>
<ejb-name>CustomerEJB</ejb-name>
<jndi-name>customer</jndi-name>
<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>
<cmp-resource>
<jndi-name>jdbc/PointBase</jndi-name>
<create-tables-at-deploy>true</create-tables-at-deploy>
<drop-tables-at-undeploy>true</drop-tables-at-undeploy>
</cmp-resource>
</enterprise-beans>
</sun-ejb-jar>
The sun-cmp-mappings.xml FileThe element hierarchy in the sun-cmp-mappings.xml file is as follows:
sun-cmp-mappings
. sun-cmp-mapping
. . schema
. . entity-mapping
. . . ejb-name
. . . table-name
. . . cmp-field-mapping
. . . . field-name
. . . . column-name
. . . . read-only
. . . . fetched-with
. . . . . default
. . . . . level
. . . . . named-group
. . . . . none
. . . cmr-field-mapping
. . . . cmr-field-name
. . . . column-pair
. . . . . column-name
. . . . fetched-with
. . . . . default
. . . . . level
. . . . . named-group
. . . . . none
. . . secondary-table
. . . . table-name
. . . . column-pair
. . . . . column-name
. . . consistency
. . . . none
. . . . check-modified-at-commit
. . . . lock-when-loaded
. . . . check-all-at-commit
. . . . lock-when-modified
. . . . check-version-of-accessed-instances
. . . . . column-nameHere is a sample database schema definition:
create table TEAMEJB (
TEAMID varchar2(256) not null,
NAME varchar2(120) null,
CITY char(30) not null,
LEAGUEEJB_LEAGUEID varchar2(256) null,
constraint PK_TEAMEJB primary key (TEAMID)
)create table PLAYEREJB (
POSITION varchar2(15) null,
PLAYERID varchar2(256) not null,
NAME char(64) null,
SALARY number(10, 2) not null,
constraint PK_PLAYEREJB primary key (PLAYERID)
)create table LEAGUEEJB (
LEAGUEID varchar2(256) not null,
NAME varchar2(256) null,
SPORT varchar2(256) null,
constraint PK_LEAGUEEJB primary key (LEAGUEID)
)create table PLAYEREJBTEAMEJB (
PLAYEREJB_PLAYERID varchar2(256) null,
TEAMEJB_TEAMID varchar2(256) null
)alter table TEAMEJB
add constraint FK_LEAGUE foreign key (LEAGUEEJB_LEAGUEID)
references LEAGUEEJB (LEAGUEID)alter table PLAYEREJBTEAMEJB
add constraint FK_TEAMS foreign key (PLAYEREJB_PLAYERID)
references PLAYEREJB (PLAYERID)alter table PLAYEREJBTEAMEJB
add constraint FK_PLAYERS foreign key (TEAMEJB_TEAMID)
references TEAMEJB (TEAMID)Here is a corresponding sample sun-cmp-mappings.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<sun-cmp-mappings>
<sun-cmp-mapping>
<schema>Roster</schema>
<entity-mapping>
<ejb-name>TeamEJB</ejb-name>
<table-name>TEAMEJB</table-name>
<cmp-field-mapping>
<field-name>teamId</field-name>
<column-name>TEAMEJB.TEAMID</column-name>
</cmp-field-mapping>
<cmp-field-mapping>
<field-name>name</field-name>
<column-name>TEAMEJB.NAME</column-name>
</cmp-field-mapping>
<cmp-field-mapping>
<field-name>city</field-name>
<column-name>TEAMEJB.CITY</column-name>
</cmp-field-mapping>
<cmr-field-mapping>
<cmr-field-name>league</cmr-field-name>
<column-pair>
<column-name>TEAMEJB.LEAGUEEJB_LEAGUEID</column-name>
<column-name>LEAGUEEJB.LEAGUEID</column-name>
</column-pair>
<fetched-with>
<none/>
</fetched-with>
</cmr-field-mapping>
<cmr-field-mapping>
<cmr-field-name>players</cmr-field-name>
<column-pair>
<column-name>TEAMEJB.TEAMID</column-name>
<column-name>PLAYEREJBTEAMEJB.TEAMEJB_TEAMID</column-name>
</column-pair>
<column-pair>
<column-name>PLAYEREJBTEAMEJB.PLAYEREJB_PLAYERID</column-name>
<column-name>PLAYEREJB.PLAYERID</column-name>
</column-pair>
<fetched-with>
<none/>
</fetched-with>
</cmr-field-mapping>
</entity-mapping>
<entity-mapping>
<ejb-name>PlayerEJB</ejb-name>
<table-name>PLAYEREJB</table-name>
<cmp-field-mapping>
<field-name>position</field-name>
<column-name>PLAYEREJB.POSITION</column-name>
</cmp-field-mapping>
<cmp-field-mapping>
<field-name>playerId</field-name>
<column-name>PLAYEREJB.PLAYERID</column-name>
</cmp-field-mapping>
<cmp-field-mapping>
<field-name>name</field-name>
<column-name>PLAYEREJB.NAME</column-name>
</cmp-field-mapping>
<cmp-field-mapping>
<field-name>salary</field-name>
<column-name>PLAYEREJB.SALARY</column-name>
</cmp-field-mapping>
<cmr-field-mapping>
<cmr-field-name>teams</cmr-field-name>
<column-pair>
<column-name>PLAYEREJB.PLAYERID</column-name>
<column-name>PLAYEREJBTEAMEJB.PLAYEREJB_PLAYERID</column-name>
</column-pair>
<column-pair>
<column-name>PLAYEREJBTEAMEJB.TEAMEJB_TEAMID</column-name>
<column-name>TEAMEJB.TEAMID</column-name>
</column-pair>
<fetched-with>
<none/>
</fetched-with>
</cmr-field-mapping>
</entity-mapping>
<entity-mapping>
<ejb-name>LeagueEJB</ejb-name>
<table-name>LEAGUEEJB</table-name>
<cmp-field-mapping>
<field-name>leagueId</field-name>
<column-name>LEAGUEEJB.LEAGUEID</column-name>
</cmp-field-mapping>
<cmp-field-mapping>
<field-name>name</field-name>
<column-name>LEAGUEEJB.NAME</column-name>
</cmp-field-mapping>
<cmp-field-mapping>
<field-name>sport</field-name>
<column-name>LEAGUEEJB.SPORT</column-name>
</cmp-field-mapping>
<cmr-field-mapping>
<cmr-field-name>teams</cmr-field-name>
<column-pair>
<column-name>LEAGUEEJB.LEAGUEID</column-name>
<column-name>TEAMEJB.LEAGUEEJB_LEAGUEID</column-name>
</column-pair>
<fetched-with>
<none/>
</fetched-with>
</cmr-field-mapping>
</entity-mapping>
</sun-cmp-mapping>
</sun-cmp-mappings>
The sun-application-client.xml fileThe element hierarchy in the sun-application-client.xml file is as follows:
sun-application-client
. ejb-ref
. . ejb-ref-name
. . jndi-name
. resource-ref
. . res-ref-name
. . jndi-name
. . default-resource-principal
. . . name
. . . password
. resource-env-ref
. . resource-env-ref-name
. . jndi-name
. service-ref
. . service-ref-name
. . port-info
. . . service-endpoint-interface
. . . wsdl-port
. . . . namespaceURI
. . . . localpart
. . . stub-property
. . . . name
. . . . value
. . . call-property
. . . . name
. . . . value
. . . message-security-binding
. . . . message-security
. . . . . message
. . . . . . java-method
. . . . . . . method-name
. . . . . . . method-params
. . . . . . . . method-param
. . . . . . operation-name
. . . . . request-protection
. . . . . response-protection
. . call-property
. . . name
. . . value
. . wsdl-override
. . service-impl-class
. . service-qname
. . . namespaceURI
. . . localpart
. message-destination
. . message-destination-name
. . jndi-name
The sun-acc.xml FileThe element hierarchy in the sun-acc.xml file is as follows:
client-container
. target-server
. . description
. . security
. . . ssl
. . . cert-db
. auth-realm
. . property (with attributes)
. client-credential
. . property (with attributes)
. log-service
. . property (with attributes)
. message-security-config
. . provider-config
. . . request-policy
. . . response-policy
. . . property (with attributes)
. property (with attributes)
Alphabetical Listing of All Elements
Aactivation-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.
Superelements
mdb-resource-adapter (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the activation-config element.
activation-config-property
Specifies the name and value of an activation configuration property.
Superelements
activation-config (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the activation-config-property element.
activation-config-property-name
Specifies the name of an activation configuration property.
Superelements
activation-config-property (sun-ejb-jar.xml)
Subelements
none - contains data
activation-config-property-value
Specifies the value of an activation configuration property.
Superelements
activation-config-property (sun-ejb-jar.xml)
Subelements
none - contains data
as-context
Specifies the authentication mechanism used to authenticate the client.
Superelements
ior-security-config (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the as-context element.
auth-method
Specifies the authentication method.
If the parent element is as-context, the only supported value is USERNAME_PASSWORD.
If the parent element is 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.
Superelements
login-config (sun-web.xml), as-context (sun-ejb-jar.xml)
Subelements
none - contains data
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 “Realm Configuration” on page 40.
Superelements
client-container (sun-acc.xml)
Subelements
The following table describes subelements for the auth-realm element.
Table A-5 auth-realm subelement
Element
Required
Description
zero or more
Specifies a property, which has a name and a value.
Attributes
The following table describes attributes for the auth-realm element.
Table A-6 auth-realm attributes
Attribute
Default
Description
name
none
Defines the name of this realm.
classname
none
Defines the Java class which implements this realm.
Example
Here is an example of the default file realm:
<auth-realm name="file" classname="com.sun.enterprise.security.auth.realm.file.FileRealm">
<property name="file" value="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 “Realm Configuration” on page 40.
Bbean-cache
Specifies the entity bean cache properties. Used for entity beans and stateful session beans.
Superelements
ejb (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the bean-cache element.
Example
<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>bean-pool
Specifies the pool properties of stateless session beans, entity beans, and message-driven bean.
Superelements
ejb (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the bean-pool element.
Example
<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>
Ccache
Configures caching for web application components.
Superelements
sun-web-app (sun-web.xml)
Subelements
The following table describes subelements for the cache element.
Table A-9 cache Subelements
Element
Required
Description
zero or more
Specifies a custom class that implements the CacheHelper interface.
zero or one
Allows you to change the properties of the default, built-in cache-helper class.
zero or more
Specifies a cache property, which has a name and a value.
zero or more
Maps a URL pattern or a servlet name to its cacheability constraints.
Attributes
The following table describes attributes for the cache element.
Table A-10 cache Attributes
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 timeout element.
enabled
true
(optional) Determines whether servlet and JSP caching is enabled.
Properties
The following table describes properties for the cache element.
Table A-11 cache Properties
Property
Default
Description
cacheClassName
com.sun.appserv.web.cache.LruCache
Specifies the fully qualified name of the class that implements the cache functionality. The cacheClassName Values table below lists 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.
Cache Class Names
The following table lists possible values of the cacheClassName property.
cache-helper
Specifies a class that implements the com.sun.appserv.web.cache.CacheHelper interface.
Superelements
cache (sun-web.xml)
Subelements
The following table describes subelements for the cache-helper element.
Table A-13 cache-helper Subelements
Element
Required
Description
zero or more
Specifies a property, which has a name and a value.
Attributes
The following table describes attributes for the cache-helper element.
Table A-14 cache-helper Attributes
Attribute
Default
Description
name
default
Specifies a unique name for the helper class, which is referenced in the 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.
cache-helper-ref
Specifies the name of the cache-helper used by the parent cache-mapping element.
Superelements
cache-mapping (sun-web.xml)
Subelements
none - contains data
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.
Superelements
bean-cache (sun-ejb-jar.xml)
Subelements
none - contains data
cache-mapping
Maps a URL pattern or a servlet name to its cacheability constraints.
Superelements
cache (sun-web.xml)
Subelements
The following table describes subelements for the cache-mapping element.
Table A-15 cache-mapping Subelements
Element
Required
Description
requires one servlet-name or url-pattern
Contains the name of a servlet.
requires one servlet-name or url-pattern
Contains a servlet URL pattern for which caching is enabled.
required if dispatcher, timeout, refresh-field, http-method, key-field, and constraint-field are not used
Contains the name of the cache-helper used by the parent cache-mapping element.
zero or one if cache-helper-ref is not used
Contains a comma-separated list of RequestDispatcher methods for which caching is enabled.
zero or one if cache-helper-ref is not used
Contains the cache-mapping specific maximum amount of time in seconds that an entry can remain in the cache after it is created or refreshed.
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.
zero or more if cache-helper-ref is not used
Contains an HTTP method that is eligible for caching.
zero or more if cache-helper-ref is not used
Specifies a component of the key used to look up and extract cache entries.
zero or more if cache-helper-ref is not used
Specifies a cacheability constraint for the given url-pattern or servlet-name.
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.
Superelements
port-info, service-ref (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml)
Subelements
The following table describes subelements for the call-property element.
Table A-16 call-property subelements
Element
Required
Description
only one
Specifies the name of the entity.
only one
Specifies the value of the entity.
caller-propagation
Specifies whether the target accepts propagated caller identities. The values are NONE, SUPPORTED, or REQUIRED.
Superelements
sas-context (sun-ejb-jar.xml)
Subelements
none - contains data
cert-db
Not implemented. Included for backward compatibility only. Attribute values are ignored.
Superelements
security (sun-acc.xml)
Subelements
none
Attributes
The following table describes attributes for the cert-db element.
Table A-17 cert-db attributes
Attribute
Default
Description
path
none
Specifies the absolute path of the certificate database.
password
none
Specifies the password to access the certificate database.
check-all-at-commit
This element is not implemented. Do not use.
Superelements
consistency (sun-cmp-mappings.xml)
check-modified-at-commit
Checks concurrent modification of fields in modified beans at commit time.
Superelements
consistency (sun-cmp-mappings.xml)
Subelements
none - element is present or absent
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.
Superelements
consistency (sun-cmp-mappings.xml)
Subelements
The following table describes subelements for the check-version-of-accessed-instances element.
Table A-18 check-version-of-accessed-instances Subelements
Element
Required
Description
only one
Specifies the name of the version column.
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 ejb element must be set to true.
Superelements
ejb (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the checkpoint-at-end-of-method element.
Table A-19 checkpoint-at-end-of-method Subelements
Element
Required
Description
one or more
Specifies a bean method.
checkpointed-methods
Deprecated. Supported for backward compatibility. Use checkpoint-at-end-of-method instead.
Superelements
ejb (sun-ejb-jar.xml)
class-loader
Configures the classloader for the web module.
Superelements
sun-web-app (sun-web.xml)
Subelements
The following table describes subelements for the class-loader element.
Table A-20 class-loader Subelements
Element
Required
Description
zero or more
Specifies a property, which has a name and a value.
Attributes
The following table describes attributes for the class-loader element.
client-container
Defines the Sun Java System Application Server 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 The sun-acc.xml File.
Superelements
none
Subelements
The following table describes subelements for the client-container element.
Attributes
The following table describes attributes for the client-container element.
Properties
The following table describes properties for the client-container element.
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.
Superelements
client-container (sun-acc.xml)
Subelements
The following table describes subelements for the client-credential element.
Table A-25 client-credential subelement
Element
Required
Description
zero or more
Specifies a property, which has a name and a value.
Attributes
The following table describes attributes for the client-credential element.
cmp
Describes runtime information for a CMP entity bean object for EJB1.1 and EJB2.1 beans.
Superelements
ejb (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the cmp element.
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.
Superelements
entity-mapping (sun-cmp-mappings.xml)
Subelements
The following table describes subelements for the cmp-field-mapping element.
cmp-resource
Specifies the database to be used for storing CMP beans. For more information about this element, see Configuring the CMP Resource.
Superelements
enterprise-beans (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the cmp-resource element.
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.
Superelements
entity-mapping (sun-cmp-mappings.xml)
Subelements
The following table describes subelements for the cmr-field-mapping element.
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.
Superelements
cmr-field-mapping (sun-cmp-mappings.xml)
Subelements
none - contains data
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.
Superelements
ejb (sun-ejb-jar.xml)
Subelements
none - contains data
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.
Superelements
check-version-of-accessed-instances, cmp-field-mapping, column-pair (sun-cmp-mappings.xml)
Subelements
none - contains data
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.
Superelements
cmr-field-mapping, secondary-table (sun-cmp-mappings.xml)
Subelements
The following table describes subelements for the column-pair element.
commit-option
Specifies the commit option used on transaction completion. Valid values for the Sun Java System Application Server are B or C. Default value is B. Applies to entity beans.
Superelements
ejb (sun-ejb-jar.xml)
Subelements
none - contains data
confidentiality
Specifies if the target supports privacy-protected messages. The values are NONE, SUPPORTED, or REQUIRED.
Superelements
transport-config (sun-ejb-jar.xml)
Subelements
none - contains data
consistency
Specifies container behavior in guaranteeing transactional consistency of the data in the bean.
Superelements
entity-mapping (sun-cmp-mappings.xml)
Subelements
The following table describes subelements for the consistency element.
constraint-field
Specifies a cacheability constraint for the given url-pattern or 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.
Superelements
cache-mapping (sun-web.xml)
Subelements
The following table describes subelements for the constraint-field element.
Table A-33 constraint-field Subelements
Element
Required
Description
zero or more
Contains a value to be matched to the input parameter value.
Attributes
The following table describes attributes for the constraint-field element.
Table A-34 constraint-field Attributes
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 constraint-field-value subelement.
cache-on-match-failure
false
(optional) If true, caches the response if matching fails. Overrides the same attribute in a constraint-field-value subelement.
constraint-field-value
Specifies a value to be matched to the input parameter value. The matching is case sensitive. For example:
<value match-expr="in-range">1-60</value>
Superelements
constraint-field (sun-web.xml)
Subelements
none - contains data
Attributes
The following table describes attributes for the constraint-field-value element.
context-root
Contains the web context root for the application or web application. Overrides the corresponding element in the application.xml or web.xml file.
If you are setting up load balancing, web module context roots must be unique within a cluster. See the Sun Java System Application Server Administration Guide for more information about load balancing.
Superelements
web (sun-application.xml), sun-web-app (sun-web.xml)
Subelements
none - contains data
cookie-properties
Specifies session cookie properties.
Superelements
session-config (sun-web.xml)
Subelements
The following table describes subelements for the cookie-properties element.
Table A-36 cookie-properties Subelements
Element
Required
Description
zero or more
Specifies a property, which has a name and a value.
Properties
The following table describes properties for the cookie-properties element.
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 Table 7-5.
Superelements
cmp-resource (sun-ejb-jar.xml)
Subelements
none - contains data
Ddatabase-vendor-name
Specifies the name of the database vendor for which tables can be created. Allowed values are db2, mssql, oracle, pointbase, and sybase, case-insensitive.
If no value is specified, a connection is made to the resource specified by the jndi-name subelement of the 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 Table 7-5.
Superelements
cmp-resource (sun-ejb-jar.xml)
Subelements
none - contains data
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 prefetch-disabled element in the sun-ejb-jar.xml file.
Superelements
fetched-with (sun-cmp-mappings.xml)
Subelements
none - element is present or absent
default-helper
Passes property values to the built-in default cache-helper class.
Superelements
cache (sun-web.xml)
Subelements
The following table describes subelements for the default-helper element.
Table A-38 default-helper Subelements
Element
Required
Description
zero or more
Specifies a property, which has a name and a value.
Properties
The following table describes properties for the default-helper element.
Table A-39 default-helper Properties
Property
Default
Description
cacheKeyGeneratorAttrName
Uses the built-in default cache-helper key generation, which concatenates the servlet path with 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 “CacheKeyGenerator Interface” on page 143.
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 Sun Java™ System Message Queue broker user repository. See the “Security Management” chapter in the Sun Java System Message Queue Administration Guide for details.
Superelements
resource-ref (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml); cmp-resource, mdb-connection-factory (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the default-resource-principal element.
description
Specifies a text description of the containing element.
Superelements
property (with attributes) (sun-web.xml); activation-config, method (sun-ejb-jar.xml); target-server (sun-acc.xml)
Subelements
none - contains data
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.
Superelements
cache-mapping (sun-web.xml)
Subelements
none - contains data
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 Table 7-5.
Superelements
cmp-resource (sun-ejb-jar.xml)
Subelements
none - contains data
Eejb
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, cmp, ior-security-config, gen-classes, jndi-name, use-thread-pool-id
- Stateless session beans and message-driven beans: bean-pool
- Stateful session beans: checkpoint-at-end-of-method
- Stateful session beans and entity beans: bean-cache
- Entity beans: commit-option, bean-cache, bean-pool, is-read-only-bean, refresh-period-in-seconds, flush-at-end-of-method
- Message-driven beans: mdb-connection-factory, jms-durable-subscription-name, jms-max-messages-load, bean-pool
Superelements
enterprise-beans (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the ejb element.
Table A-41 ejb Subelements
Element
Required
Description
only one
Matches the ejb-name in the corresponding ejb-jar.xml file.
zero or more
Specifies the absolute jndi-name.
zero or more
Maps the absolute JNDI name to the ejb-ref element in the corresponding J2EE XML file.
zero or more
Maps the absolute JNDI name to the resource-ref in the corresponding J2EE XML file.
zero or more
Maps the absolute JNDI name to the resource-env-ref in the corresponding J2EE XML file.
zero or more
Specifies runtime settings for a web service reference.
zero or one
Specifies the passing method used by an enterprise bean calling a remote interface method in another bean that is co-located within the same process.
zero or one
Specifies runtime information for a container-managed persistence (CMP) EntityBean object for EJB1.1 and EJB2.1 beans.
zero or one
Specifies the principal (user) name in an enterprise bean that has the run-as role specified.
zero or one
Specifies the connection factory associated with a message-driven bean.
zero or one
Specifies the durable subscription associated with a message-driven bean.
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.
zero or one
Specifies the security information for the IOR.
zero or one
Specifies that this entity bean is read-only.
zero or one
Specifies the rate at which a read-only-bean must be refreshed from the data source.
zero or one
Has valid values of B or C. Default value is B.
zero or one
Overrides the Transaction Timeout setting of the Transaction Service for an individual bean.
zero or one
Specifies the thread pool from which threads are selected for remote invocations of this bean.
zero or one
Specifies all the generated class names for a bean.
zero or one bean-pool
Specifies the bean pool properties. Used for stateless session beans, entity beans, and message-driven bean pools.
zero or one bean-pool
Specifies the bean cache properties. Used only for stateful session beans and entity beans.
zero or one
Specifies runtime configuration information for a message-driven bean.
zero or more
Specifies information about a web service endpoint.
zero or one
Specifies the methods that force a database flush after execution. Used for entity beans.
zero or one
Deprecated. Supported for backward compatibility. Use checkpoint-at-end-of-method instead.
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.
Attributes
The following table describes attributes for the ejb element.
Example
<ejb>
<ejb-name>CustomerEJB</ejb-name>
<jndi-name>customer</jndi-name>
<resource-ref>
<res-ref-name>jdbc/SimpleBank</res-ref-name>
<jndi-name>jdbc/PointBase</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>ejb-name
In the sun-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.
Superelements
ejb, method (sun-ejb-jar.xml); entity-mapping (sun-cmp-mappings.xml)
Subelements
none - contains data
ejb-ref
Maps the ejb-ref-name in the corresponding J2EE 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.
Superelements
sun-web-app (sun-web.xml), ejb (sun-ejb-jar.xml), sun-application-client (sun-application-client.xml)
Subelements
The following table describes subelements for the ejb-ref element.
ejb-ref-name
Specifies the ejb-ref-name in the corresponding J2EE deployment descriptor file ejb-ref entry.
Superelements
ejb-ref (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml)
Subelements
none - contains data
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.
Superelements
webservice-endpoint (sun-web.xml, sun-ejb-jar.xml)
Subelements
none - contains data
Example
If the web server is listening at http://localhost:8080, the following endpoint-address-uri:
<endpoint-address-uri>StockQuoteService/StockQuotePort</endpoint-address-uri>
results in the following target endpoint address:
http://localhost:8080/StockQuoteService/StockQuotePort
enterprise-beans
Specifies all the runtime properties for an EJB JAR file in the application.
Superelements
sun-ejb-jar (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the enterprise-beans element.
Example
<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/PointBase</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>entity-mapping
Specifies the mapping a bean to database columns.
Superelements
sun-cmp-mapping (sun-cmp-mappings.xml)
Subelements
The following table describes subelements for the entity-mapping element.
establish-trust-in-client
Specifies if the target is capable of authenticating a client. The values are NONE, SUPPORTED, or REQUIRED.
Superelements
transport-config (sun-ejb-jar.xml)
Subelements
none - contains data
establish-trust-in-target
Specifies if the target is capable of authenticating to a client. The values are NONE, SUPPORTED, or REQUIRED.
Superelements
transport-config (sun-ejb-jar.xml)
Subelements
none - contains data
Ffetched-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 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:
<fetched-with><default/></fetched-with>
- If there is no fetched-with subelement of a 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:
<fetched-with><none/></fetched-with>
- If there is no fetched-with subelement of a cmr-field-mapping, fetched-with can have any valid subelement. The default subelement is as follows:
<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 Managed Fields.
Superelements
cmp-field-mapping, cmr-field-mapping (sun-cmp-mappings.xml)
Subelements
The following table describes subelements for the fetched-with element.
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.
Superelements
cmp-field-mapping (sun-cmp-mappings.xml)
Subelements
none - contains data
finder
Describes the finders for CMP 1.1 with a method name and query.
Superelements
one-one-finders (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the finder element.
flush-at-end-of-method
Specifies the methods that force a database flush after execution. Applicable to entity beans.
Superelements
ejb (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the flush-at-end-of-method element.
Table A-48 flush-at-end-of-method Subelements
Element
Required
Description
one or more
Specifies a bean method.
Ggen-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.
Superelements
ejb (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the gen-class element.
group-name
Specifies a group name in the current realm.
Superelements
security-role-mapping (sun-application.xml, sun-web.xml, sun-ejb-jar.xml)
Subelements
none - contains data
Hhttp-method
Specifies an HTTP method that is eligible for caching. The default is GET.
Superelements
cache-mapping (sun-web.xml)
Subelements
none - contains data
Iidempotent-url-pattern
Specifies a URL pattern for idempotent requests.
Superelements
sun-web-app (sun-web.xml)
Subelements
none
Attributes
The following table describes attributes for the idempotent-url-pattern element.
Example
The following example specifies that all requests for the URI sun-java/* are idempotent.
<idempotent-url-pattern url-pattern="sun_java/*" num-of-retries="10"/>
integrity
Specifies if the target supports integrity-protected messages. The values are NONE, SUPPORTED, or REQUIRED.
Superelements
transport-config (sun-ejb-jar.xml)
Subelements
none - contains data
ior-security-config
Specifies the security information for the input-output redirection (IOR).
Superelements
ejb (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the ior-security-config element.
is-cache-overflow-allowed
This element is deprecated. Do not use.
Superelements
bean-cache (sun-ejb-jar.xml)
is-one-one-cmp
This element is not used.
Superelements
cmp (sun-ejb-jar.xml)
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.
Superelements
ejb (sun-ejb-jar.xml)
Subelements
none - contains data
Jjava-method
Specifies a method.
Superelements
message (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml)
Subelements
The following table describes subelements for the java-method element.
Table A-52 java-method Subelements
Element
Required
Description
only one
Specifies a method name.
zero or one
Specifies fully qualified Java type names of method parameters.
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.
Superelements
ejb (sun-ejb-jar.xml)
Subelements
none - contains data
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.
Superelements
ejb (sun-ejb-jar.xml)
Subelements
none - contains data
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 activation-config subelement of the mdb-resource-adapter element. For more information about JMS resources, see Chapter 14, “Using the Java Message Service.”
Superelements
ejb-ref, message-destination, resource-env-ref, resource-ref (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml); cmp-resource, ejb, mdb-connection-factory (sun-ejb-jar.xml)
Subelements
none - contains data
jsp-config
Specifies JSP configuration information.
Superelements
sun-web-app (sun-web.xml)
Subelements
The following table describes subelements for the jsp-config element.
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:
The following table describes properties for the jsp-config element.
Table A-54 jsp-config Properties
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
Specifies the compiler Ant uses to compile JSP files. See the Ant documentation for more information:
http://computing.ee.ethz.ch/sepp/ant-1.5.4-ke/manual/index .html
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.
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 separate from the one in which Tomcat is running.
genStrAsCharArray
false
If set to true, generates text strings as char arrays, which improves performance in some cases.
ieClassId
clsid:8AD9C840-044E-11D1-B3E9-00805F499D93
Specifies the Java plug-in COM class ID for Internet Explorer. Used by the <jsp:plugin> tags.
javaEncoding
UTF8
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://java.sun.com/j2se/1.4/docs/guide/intl/encoding.doc. html
keepgenerated
true
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.
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
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.
Kkey-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.
Superelements
cache-mapping (sun-web.xml)
Subelements
none
Attributes
The following table describes attributes for the key-field element.
Llevel
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.
Superelements
fetched-with (sun-cmp-mappings.xml)
Subelements
none - contains data
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.
Superelements
gen-classes (sun-ejb-jar.xml)
Subelements
none - contains data
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.
Superelements
gen-classes (sun-ejb-jar.xml)
Subelements
none - contains data
locale-charset-info
Deprecated. For backward compatibility only. Use the parameter-encoding subelement of sun-web-app instead. Specifies information about the application’s internationalization settings.
Superelements
sun-web-app (sun-web.xml)
Subelements
The following table describes subelements for the locale-charset-info element.
Attributes
The following table describes attributes for the locale-charset-info element.
Table A-57 locale-charset-info Attributes
Attribute
Default
Description
default-locale
none
Although a value is required, the value is ignored. Use the default-charset attribute of the parameter-encoding element.
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 parameter-encoding element.
For encodings, see:
http://java.sun.com/j2se/1.4/docs/guide/intl/encoding.doc.html
Superelements
locale-charset-info (sun-web.xml)
Subelements
The following table describes subelements for the locale-charset-map element.
Table A-58 locale-charset-map Subelements
Element
Required
Description
zero or one
Specifies an optional text description of a mapping.
Attributes
The following table describes attributes for the locale-charset-map element.
Table A-59 locale-charset-map Attributes
Attribute
Default
Description
locale
none
Specifies the locale name.
agent
none
(optional) Specifies the type of client that interacts with the application server. 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 the Example agent Attribute Values table for more information.
charset
none
Specifies the character encoding to which the locale maps.
Example Agents
The following table specifies example agent attribute values.
localpart
Specifies the local part of a QNAME.
Superelements
service-qname, wsdl-port (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml)
Subelements
none - contains data
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.
Superelements
consistency (sun-cmp-mappings.xml)
Subelements
none - element is present or absent
lock-when-modified
This element is not implemented. Do not use.
Superelements
consistency (sun-cmp-mappings.xml)
log-service
Specifies configuration settings for the log file.
Superelements
client-container (sun-acc.xml)
Subelements
The following table describes subelements for the log-service element.
Table A-61 log-service subelement
Element
Required
Description
zero or more
Specifies a property, which has a name and a value.
Attributes
The following table describes attributes for the log-service element.
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.
Superelements
webservice-endpoint (sun-web.xml, sun-ejb-jar.xml)
Subelements
The following table describes subelements for the login-config element.
Table A-63 login-config subelements
Element
Required
Description
only one
Specifies the authentication method.
Mmanager-properties
Specifies session manager properties.
Superelements
session-manager (sun-web.xml)
Subelements
The following table describes subelements for the manager-properties element.
Table A-64 manager-properties Subelements
Element
Required
Description
zero or more
Specifies a property, which has a name and a value.
Properties
The following table describes properties for the manager-properties element.
Table A-65 manager-properties Properties
Property
Default
Description
reapIntervalSeconds
60
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 website, or the last few hits might be lost each time the server is restarted.
Applicable only if the persistence-type attribute of the parent session-manager element is file or ha.
maxSessions
-1
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.
The session manager passivates sessions to the persistent store when this maximum is reached.
Applicable only if the persistence-type attribute of the parent session-manager element is file or ha.
sessionFilename
none; state is not preserved across restarts
Specifies the absolute or relative path to the directory in which the session state is preserved between application restarts, if preserving the state is possible. A relative path is relative to the temporary directory for this web application.
Applicable only if the persistence-type attribute of the parent session-manager element is memory.
persistenceFrequency
web-method
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 session-manager element is ha.
mapping-properties
This element is not implemented.
Superelements
cmp (sun-ejb-jar.xml)
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.
Superelements
bean-cache (sun-ejb-jar.xml)
Subelements
none - contains data
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.
Superelements
bean-pool (sun-ejb-jar.xml)
Subelements
none - contains data
max-wait-time-in-millis
This element is deprecated. Do not use.
Superelements
bean-pool (sun-ejb-jar.xml)
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.
Superelements
ejb (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the mdb-connection-factory element.
mdb-resource-adapter
Specifies runtime configuration information for a message-driven bean.
Superelements
ejb (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the mdb-resource-adapter element.
Table A-67 mdb-resource-adapter subelements
Element
Required
Description
zero or one
Specifies a resource adapter module ID.
one or more
Specifies an activation configuration.
message
Specifies the methods or operations to which message security requirements apply.
Superelements
message-security (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml)
Subelements
The following table describes subelements for the message element.
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 J2EE deployment descriptor file.
Superelements
sun-web-app (sun-web.xml), enterprise-beans (sun-ejb-jar.xml), sun-application-client (sun-application-client.xml)
Subelements
The following table describes subelements for the message-destination element.
message-destination-name
Specifies the name of a logical message destination defined within the corresponding J2EE deployment descriptor file.
Superelements
message-destination (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml)
Subelements
none - contains data
message-security
Specifies message security requirements.
- If the grandparent element is webservice-endpoint, these requirements pertain to request and response messages of the endpoint.
- If the grandparent element is port-info, these requirements pertain to the port of the referenced service.
Superelements
message-security-binding (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml)
Subelements
The following table describes subelements for the message-security element.
message-security-binding
Specifies a custom authentication provider binding for a parent webservice-endpoint or port-info element in one or both of these ways:
Superelements
webservice-endpoint, port-info (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml)
Subelements
The following table describes subelements for the message-security-binding element.
Table A-71 message-security-binding Subelements
Element
Required
Description
zero or more
Specifies message security requirements.
Attributes
The following table describes attributes for the message-security-binding element.
message-security-config
Specifies configurations for message security providers.
Superelements
client-container (sun-acc.xml)
Subelements
The following table describes subelements for the message-security-config element.
Table A-73 message-security-config Subelements
Element
Required
Description
one or more
Specifies a configuration for one message security provider.
Attributes
The following table describes attributes for the message-security-config element.
method
Specifies a bean method.
Superelements
flush-at-end-of-method (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the method element.
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.
Superelements
method (sun-ejb-jar.xml)
Subelements
none - contains data
method-name
Specifies a method name or * (an asterisk) for all methods. If a method is overloaded, specifies all methods with the same name.
Superelements
java-method (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml); finder, query-method , method (sun-ejb-jar.xml)
Subelements
none - contains data
Examples
<method-name>findTeammates</method-name>
<method-name>*</method-name>
method-param
Specifies the fully qualified Java type name of a method parameter.
Superelements
method-params (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml)
Subelements
none - contains data
method-params
Specifies fully qualified Java type names of method parameters.
Superelements
java-method (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml); query-method, method (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the method-params element.
Table A-76 method-params Subelements
Element
Required
Description
zero or more
Specifies the fully qualified Java type name of a method parameter.
Nname
Specifies the name of the entity.
Superelements
call-property, default-resource-principal, stub-property (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml); enterprise-beans, principal, property (with subelements) (sun-ejb-jar.xml)
Subelements
none - contains data
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.
Superelements
fetched-with (sun-cmp-mappings.xml)
Subelements
none - contains data
namespaceURI
Specifies the namespace URI.
Superelements
service-qname, wsdl-port (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml)
Subelements
none - contains data
none
Specifies that this field or relationship is fetched by itself, with no other fields or relationships.
Superelements
consistency, fetched-with (sun-cmp-mappings.xml)
Subelements
none - element is present or absent
Oone-one-finders
Describes the finders for CMP 1.1 beans.
Superelements
cmp (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the one-one-finders element.
Table A-77 one-one-finders Subelements
Element
Required
Description
one or more
Describes the finders for CMP 1.1 with a method name and query.
operation-name
Specifies the WSDL name of an operation of a web service.
Superelements
message (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml)
Subelements
none - contains data
Pparameter-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 sun-web-app and locale-charset-info elements have parameter-encoding subelements, the subelement of sun-web-app takes precedence.
For encodings, see:
http://java.sun.com/j2se/1.4/docs/guide/intl/encoding.doc.html
Superelements
locale-charset-info, sun-web-app (sun-web.xml)
Subelements
none
Attributes
The following table describes attributes for the parameter-encoding element.
pass-by-reference
Specifies the passing method used by a servlet or enterprise bean calling a remote interface method in another bean that is co-located 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.
When a servlet or enterprise bean calls a remote interface method in another bean that is co-located within the same process, by default the Sun Java System Application Server 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 sun-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 sun-ejb-jar.xml file. If pass-by-reference is used at both the bean and application level, the bean level takes precedence.
Superelements
sun-application (sun-application.xml), ejb (sun-ejb-jar.xml)
Subelements
none - contains data
password
Specifies the password for the principal.
Superelements
default-resource-principal (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml)
Subelements
none - contains data
pm-descriptors
This element and its subelements are deprecated. Do not use.
Superelements
enterprise-beans (sun-ejb-jar.xml)
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.
Superelements
bean-pool (sun-ejb-jar.xml)
Subelements
none - contains data
port-component-name
Specifies a unique name for a port component within a web or EJB module.
Superelements
webservice-endpoint (sun-web.xml, sun-ejb-jar.xml)
Subelements
none - contains data
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.
Superelements
service-ref (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml)
Subelements
The following table describes subelements for the port-info element.
prefetch-disabled
Disables prefetching of entity bean states for the specified query methods. Container-managed relationship fields are prefetched if their fetched-with element is set to default.
Superelements
cmp (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the prefetch-disabled element.
Table A-80 prefetch-disabled Subelements
Element
Required
Description
one or more
Specifies a query method.
principal
Defines a node that specifies a user name on the platform.
Superelements
ejb (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the principal element.
Table A-81 principal Subelements
Element
Required
Description
only one
Specifies the name of the user.
principal-name
Contains the principal (user) name.
In an enterprise bean, specifies the principal (user) name that has the run-as role specified.
Superelements
security-role-mapping (sun-application.xml, sun-web.xml, sun-ejb-jar.xml), servlet (sun-web.xml)
Subelements
none - contains data
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:
Superelements
cache, cache-helper, class-loader, cookie-properties, default-helper, manager-properties, session-properties, store-properties, sun-web-app (sun-web.xml); auth-realm, client-container, client-credential, log-service, provider-config (sun-acc.xml)
Subelements
The following table describes subelements for the property element.
Table A-82 property Subelements
Element
Required
Description
zero or one
Specifies an optional text description of a property.
Attributes
The following table describes attributes for the property element.
Table A-83 property Attributes
Attribute
Default
Description
name
none
Specifies the name of the property.
value
none
Specifies the value of the property.
Example
<property name="reapIntervalSeconds" value="20" />
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:
Superelements
cmp-resource, schema-generator-properties (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the property element.
Table A-84 property subelements
Element
Required
Description
only one
Specifies the name of the property.
only one
Specifies the value of the property.
Example
<property>
<name>use-unique-table-names</name>
<value>true</value>
</property>provider-config
Specifies a configuration for one message security provider.
Although the request-policy and response-policy subelements are optional, the provider-config element does nothing if they are not specified.
Use property subelements to configure provider-specific properties. Property values are passed to the provider when its initialize method is called.
Superelements
message-security-config (sun-acc.xml)
Subelements
The following table describes subelements for the provider-config element.
Attributes
The following table describes attributes for the provider-config element.
Qquery-filter
Specifies the query filter for the CMP 1.1 finder.
Superelements
finder (sun-ejb-jar.xml)
Subelements
none - contains data
query-method
Specifies a query method.
Superelements
prefetch-disabled (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the query-method element.
Table A-87 query-method Subelements
Element
Required
Description
only one
Specifies a method name.
only one
Specifies the fully qualified Java type names of method parameters.
query-ordering
Specifies the query ordering for the CMP 1.1 finder.
Superelements
finder (sun-ejb-jar.xml)
Subelements
none - contains data
query-params
Specifies the query parameters for the CMP 1.1 finder.
Superelements
finder (sun-ejb-jar.xml)
Subelements
none - contains data
query-variables
Specifies variables in the query expression for the CMP 1.1 finder.
Superelements
finder (sun-ejb-jar.xml)
Subelements
none - contains data
Rread-only
Specifies that a field is read-only if true. If this element is absent, the default value is false .
Superelements
cmp-field-mapping (sun-cmp-mappings.xml)
Subelements
none - contains data
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 “Realm Configuration” on page 40.
Superelements
sun-application (sun-application.xml), as-context (sun-ejb-jar.xml)
Subelements
none - contains data
refresh-field
Specifies a field that gives the application component a programmatic way to refresh a cached entry.
Superelements
cache-mapping (sun-web.xml)
Subelements
none
Attributes
The following table describes attributes for the refresh-field element.
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).
Superelements
ejb (sun-ejb-jar.xml)
Subelements
none - contains data
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 cache-idle-timeout-in-seconds.
Superelements
bean-cache (sun-ejb-jar.xml)
Subelements
none - contains data
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.
Superelements
gen-classes (sun-ejb-jar.xml)
Subelements
none - contains data
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.
Superelements
gen-classes (sun-ejb-jar.xml)
Subelements
none - contains data
request-policy
Defines the authentication policy requirements of the authentication provider’s request processing.
Superelements
provider-config (sun-acc.xml)
Subelements
none
Attributes
The following table describes attributes for the request-policy element.
request-protection
Defines the authentication policy requirements of the application’s request processing.
Superelements
message-security (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml)
Subelements
none
Attributes
The following table describes attributes for the request-protection element.
required
Specifies whether the authentication method specified must be used for client authentication. The value is true or false.
Superelements
as-context (sun-ejb-jar.xml)
Subelements
none - contains data
res-ref-name
Specifies the res-ref-name in the corresponding J2EE 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.
Superelements
resource-ref (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml)
Subelements
none - contains data
resize-quantity
Specifies the number of bean instances to be:
- Created, if a request arrives when the pool has less than steady-pool-size quantity of beans (applies to pools only for creation). If the pool has more than steady-pool-size minus resize-quantity of beans, then resize-quantity is still created.
- Removed, when the pool-idle-timeout-in-seconds timer expires and a cleaner thread removes any unused instances.
- For caches, when max-cache-size is reached, resize-quantity beans are selected for passivation using the victim-selection-policy. In addition, the cache-idle-timeout-in-seconds or removal-timeout-in-seconds timers passivate beans from the cache.
- For pools, when the max-pool-size is reached, resize-quantity beans are selected for removal. In addition, the 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.
Superelements
bean-cache, bean-pool (sun-ejb-jar.xml)
Subelements
none - contains data
resource-adapter-mid
Specifies the module ID of the resource adapter that is responsible for delivering messages to the message-driven bean.
Superelements
mdb-resource-adapter (sun-ejb-jar.xml)
Subelements
none - contains data
resource-env-ref
Maps the res-ref-name in the corresponding J2EE deployment descriptor file resource-env-ref entry to the absolute jndi-name of a resource.
Superelements
sun-web-app (sun-web.xml), ejb (sun-ejb-jar.xml), sun-application-client (sun-application-client.xml)
Subelements
The following table describes subelements for the resource-env-ref element.
Example
<resource-env-ref>
<resource-env-ref-name>jms/StockQueueName</resource-env-ref-name>
<jndi-name>jms/StockQueue</jndi-name>
</resource-env-ref>resource-env-ref-name
Specifies the res-ref-name in the corresponding J2EE deployment descriptor file resource-env-ref entry.
Superelements
resource-env-ref (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml)
Subelements
none - contains data
resource-ref
Maps the res-ref-name in the corresponding J2EE deployment descriptor file resource-ref entry to the absolute jndi-name of a resource.
Superelements
sun-web-app (sun-web.xml), ejb (sun-ejb-jar.xml), sun-application-client (sun-application-client.xml)
Subelements
The following table describes subelements for the resource-ref element.
Example
<resource-ref>
<res-ref-name>jdbc/EmployeeDBName</res-ref-name>
<jndi-name>jdbc/EmployeeDB</jndi-name>
</resource-ref>response-policy
Defines the authentication policy requirements of the authentication provider’s response processing.
Superelements
provider-config (sun-acc.xml)
Subelements
none
Attributes
The following table describes attributes for the response-policy element.
response-protection
Defines the authentication policy requirements of the application’s response processing.
Superelements
message-security (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml)
Subelements
none
Attributes
The following table describes attributes for the response-protection element.
role-name
Contains the role-name in the security-role element of the corresponding J2EE deployment descriptor file.
Superelements
security-role-mapping (sun-application.xml, sun-web.xml, sun-ejb-jar.xml)
Subelements
none - contains data
Ssas-context
Describes the sas-context fields.
Superelements
ior-security-config (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the sas-context element.
Table A-95 sas-context Subelements
Element
Required
Description
only one
Specifies whether the target accepts propagated caller identities. The values are NONE, SUPPORTED, or REQUIRED.
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 Automatic Database Schema Capture.
Superelements
sun-cmp-mapping (sun-cmp-mappings.xml)
Subelements
none - contains data
Examples
<schema/> <!-- use automatic schema generation -->
<schema>CompanySchema</schema> <!-- use "CompanySchema.dbschema" -->
schema-generator-properties
Specifies field-specific column attributes in property subelements.
Superelements
cmp-resource (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the schema-generator-properties element.
Table A-96 schema-generator-properties Subelements
Element
Required
Description
zero or more
Specifies a property name and value.
Properties
The following table describes properties for the schema-generator-properties element.
Table A-97 schema-generator-properties Properties
Property
Default
Description
use-unique-table-names
false
Specifies that generated table names are unique within each application server domain. This property can be overridden during deployment. See Table 7-5.
bean_name.field_name.attribute
none
Defines a column attribute. For attribute descriptions, see Table 7-4.
Example
<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>secondary-table
Specifies a bean’s secondary table(s).
Superelements
entity-mapping (sun-cmp-mappings.xml)
Subelements
The following table describes subelements for the secondary-table element.
security
Defines the SSL security configuration for IIOP/SSL communication with the target server.
Superelements
target-server (sun-acc.xml)
Subelements
The following table describes subelements for the security element.
Table A-99 security Subelements
Element
Required
Description
only one
Specifies the SSL processing parameters.
only one
Not implemented. Included for backward compatibility only.
security-role-mapping
Maps roles to users or groups in the currently active realm. See “Realm Configuration” on page 40 for how to define the currently active realm.
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.
Superelements
sun-application (sun-application.xml), sun-web-app (sun-web.xml), sun-ejb-jar (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the security-role-mapping element.
service-endpoint-interface
Specifies the web service reference name relative to java:comp/env.
Superelements
port-info (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml)
Subelements
none - contains data
service-impl-class
Specifies the name of the generated service implementation class.
Superelements
service-ref (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml)
Subelements
none - contains data
service-qname
Specifies the WSDL service element that is being referred to.
Superelements
service-ref (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml); webservice-endpoint (sun-web.xml, sun-ejb-jar.xml)
Subelements
The following table describes subelements for the service-qname element.
Table A-101 service-qname subelements
Element
Required
Description
only one
Specifies the namespace URI.
only one
Specifies the local part of a QNAME.
service-ref
Specifies runtime settings for a web service reference. Runtime information is only needed in the following cases:
Superelements
sun-web-app (sun-web.xml), ejb (sun-ejb-jar.xml), sun-application-client (sun-application-client.xml)
Subelements
The following table describes subelements for the service-ref element.
service-ref-name
Specifies the web service reference name relative to java:comp/env.
Superelements
service-ref (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml)
Subelements
none - contains data
servlet
Specifies a principal name for a servlet. Used for the run-as role defined in web-xml.
Superelements
sun-web-app (sun-web.xml)
Subelements
The following table describes subelements for the servlet element.
servlet-impl-class
Specifies the automatically generated name of the servlet implementation class.
Superelements
webservice-endpoint (sun-web.xml, sun-ejb-jar.xml)
Subelements
none - contains data
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.
Superelements
cache-mapping, servlet (sun-web.xml)
Subelements
none - contains data
session-config
Specifies session configuration information. Overrides the web container settings for an individual web application.
Superelements
sun-web-app (sun-web.xml)
Subelements
The following table describes subelements for the session-config element.
session-manager
Specifies session manager information.
Superelements
session-config (sun-web.xml)
Subelements
The following table describes subelements for the session-manager element.
Table A-105 session-manager Subelements
Element
Required
Description
zero or one
Specifies session manager properties.
zero or one
Specifies session persistence (storage) properties.
Attributes
The following table describes attributes for the session-manager element.
session-properties
Specifies session properties.
Superelements
session-config (sun-web.xml)
Subelements
The following table describes subelements for the session-properties element.
Table A-107 session-properties Subelements
Element
Required
Description
zero or more
Specifies a property, which has a name and a value.
Properties
The following table describes properties for the session-properties element.
ssl
Defines SSL processing parameters.
Superelements
security (sun-acc.xml)
Subelements
none
Attributes
The following table describes attributes for the SSL element.
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.
Superelements
bean-pool (sun-ejb-jar.xml)
Subelements
none - contains data
store-properties
Specifies session persistence (storage) properties.
Superelements
session-manager (sun-web.xml)
Subelements
The following table describes subelements for the store-properties element.
Table A-110 store-properties Subelements
Element
Required
Description
zero or more
Specifies a property, which has a name and a value.
Properties
The following table describes properties for the store-properties element.
Table A-111 store-properties Properties
Property
Default
Description
directory
domain_dir/generated/jsp/j2ee-apps/appname/appname_war
Specifies the absolute or relative pathname of the directory into which individual session files are written. A relative path is relative to the temporary work directory for this web application.
Applicable only if the persistence-type attribute of the parent session-manager element is file.
persistenceScope
session
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 application.
- 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 J2EE 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 session-manager element is ha.
If the persistenceScope store property is set to modified-attribute, a web application 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.
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.
Superelements
port-info (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml)
Subelements
The following table describes subelements for the stub-property element.
Table A-112 stub-property subelements
Element
Required
Description
only one
Specifies the name of the entity.
only one
Specifies the value of the entity.
Example
<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>sun-application
Defines the Sun Java System Application Server specific configuration for an application. This is the root element; there can only be one sun-application element in a sun-application.xml file. See The sun-application.xml File.
Superelements
none
Subelements
The following table describes subelements for the sun-application element.
sun-application-client
Defines the Sun Java System Application Server specific configuration for an application client. This is the root element; there can only be one sun-application-client element in a sun-application-client.xml file. See The sun-application-client.xml file.
Superelements
none
Subelements
The following table describes subelements for the sun-application-client element.
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.
Superelements
sun-cmp-mappings (sun-cmp-mappings.xml)
Subelements
The following table describes subelements for the sun-cmp-mapping element.
sun-cmp-mappings
Defines the Sun Java System Application Server 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 The sun-cmp-mappings.xml File.
Superelements
none
Subelements
The following table describes subelements for the sun-cmp-mappings element.
Table A-116 sun-cmp-mappings Subelements
Element
Required
Description
one or more
Specifies beans mapped to a particular database schema.
sun-ejb-jar
Defines the Sun Java System Application Server specific configuration for an EJB JAR file. This is the root element; there can only be one sun-ejb-jar element in a sun-ejb-jar.xml file. See The sun-ejb-jar.xml File.
Superelements
none
Subelements
The following table describes subelements for the sun-ejb-jar element.
sun-web-app
Defines Sun Java System Application Server specific configuration for a web module. This is the root element; there can only be one sun-web-app element in a sun-web.xml file. See The sun-web.xml File.
Superelements
none
Subelements
The following table describes subelements for the sun-web-app element.
Attributes
The following table describes attributes for the sun-web-app element.
Table A-119 sun-web-app Attributes
Attribute
Default
Description
error-url
(blank)
(optional) Specifies a redirect URL in case of an error.
Properties
The following table describes properties for the sun-web-app element.
Ttable-name
Specifies the name of a database table. The table must be present in the database schema file. See Automatic Database Schema Capture.
Superelements
entity-mapping, secondary-table (sun-cmp-mappings.xml)
Subelements
none - contains data
target-server
Defines the IIOP listener configuration of the target server.
Not used if the endpoints property is defined for load balancing. For more information, see client-container.
Superelements
client-container (sun-acc.xml)
Subelements
The following table describes subelements for the target-server element.
Attributes
The following table describes attributes for the target-server element.
tie-class
Specifies the automatically generated name of a tie implementation class for a port component.
Superelements
webservice-endpoint (sun-web.xml, sun-ejb-jar.xml)
Subelements
none - contains data
timeout
Specifies the 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 cache element.
Superelements
cache-mapping (sun-web.xml)
Subelements
none - contains data
Attributes
The following table describes attributes for the timeout element.
transport-config
Specifies the security transport information.
Superelements
ior-security-config (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the transport-config element.
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.
Superelements
webservice-endpoint (sun-web.xml, sun-ejb-jar.xml)
Subelements
none - contains data
Uunique-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.
Superelements
sun-application (sun-application.xml), enterprise-beans (sun-ejb-jar.xml)
Subelements
none - contains data
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.
Superelements
cache-mapping (sun-web.xml)
Subelements
none - contains data
use-thread-pool-id
Specifies the thread pool from which threads are selected for remote invocations of this bean.
Superelements
ejb (sun-ejb-jar.xml)
Subelements
none - contains data
Vvalue
Specifies the value of the entity.
Superelements
call-property, stub-property (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml); property (with subelements) (sun-ejb-jar.xml)
Subelements
none - contains data
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.
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.
Superelements
bean-cache (sun-ejb-jar.xml)
Subelements
none - contains data
Example
<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.
Wweb
Specifies the application’s web tier configuration.
Superelements
sun-application (sun-application.xml)
Subelements
The following table describes subelements for the web element.
Table A-125 web Subelements
Element
Required
Description
only one
Contains the web URI for the application.
only one
Contains the web context root for the application.
web-uri
Contains the web URI for the application. Must match the corresponding element in the application.xml file.
Superelements
web (sun-application.xml)
Subelements
none - contains data
webservice-description
Specifies a name and optional publish location for a web service.
Superelements
sun-web-app (sun-web.xml), enterprise-beans (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the webservice-description element.
webservice-description-name
Specifies a unique name for the web service within a web or EJB module.
Superelements
webservice-description (sun-web.xml, sun-ejb-jar.xml)
Subelements
none - contains data
webservice-endpoint
Specifies information about a web service endpoint.
Superelements
servlet (sun-web.xml), ejb (sun-ejb-jar.xml)
Subelements
The following table describes subelements for the webservice-endpoint element.
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 J2EE deployment descriptor is used.
Superelements
service-ref (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml)
Subelements
none - contains data
Example
// 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>wsdl-port
Specifies the WSDL port.
Superelements
port-info (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml)
Subelements
The following table describes subelements for the wsdl-port element.
Table A-128 wsdl-port subelements
Element
Required
Description
only one
Specifies the namespace URI.
only one
Specifies the local part of a QNAME.
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).
Superelements
webservice-description (sun-web.xml, sun-ejb-jar.xml)
Subelements
none - contains data
Example
Suppose you have an ejb.jar file whose webservices.xml file’s wsdl-file element contains the following reference:
META-INF/wsdl/a/Foo.wsdl
Suppose your sun-ejb-jar file contains the following element:
<wsdl-publish-location>file:/home/user1/publish</wsdl-publish-location>
The final WSDL is stored in /home/user1/publish/a/Foo.wsdl.