Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Developer's Guide

- Previous: Part III Using Services and APIs

# Appendix A Deployment Descriptor Files

This chapter describes deployment descriptor files specific to the Sun Java System Application Server in the following sections:

- Sun Java System Application Server Descriptors

- The sun-application.xml File

- The sun-web.xml File

- The sun-ejb-jar.xml File

- The sun-cmp-mappings.xml File

- The sun-application-client.xml file

- The sun-acc.xml File

- Alphabetical Listing of All Elements

# Sun Java System Application Server Descriptors

Sun Java System Application Server uses deployment descriptors in addition to the J2EE standard descriptors for configuring features specific to the 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 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 the Application Server.

To check the correctness of these deployment descriptors prior to deployment, see The Deployment Descriptor Verifier.

For general information about DTD files and XML, see the XML specification at `http://www.w3.org/TR/REC-xml`.

The following table lists the Application Server deployment descriptors and their DTD files.

Table A–1 Sun Java System Application Server Descriptors

Deployment Descriptor | DTD File | Description
--- | --- | ---
`sun-application.xml` | `sun-application_1_4-0.dtd` | Configures an entire J2EE application (EAR file).
`sun-web.xml` | `sun-web-app_2_4-1.dtd` | Configures a web application (WAR file).
`sun-ejb-jar.xml` | `sun-ejb-jar_2_1-1.dtd` | Configures an enterprise bean (EJB JAR file).
`sun-cmp-mappings.xml` | `sun-cmp-mapping_1_2.dtd` | Configures container-managed persistence for an enterprise bean.
`sun-application-client.xml` | `sun-application-client_1_4-1.dtd` | Configures an Application Client Container (ACC) client (JAR file).
`sun-acc.xml` | `sun-application-client-container_1_0.dtd` | Configures the Application Client Container.

Note –

The Application Server deployment descriptors must be readable and writable by the file owners.

In each deployment descriptor file, subelements must be defined in the order in which they are listed under each Subelements heading, unless otherwise noted.

# The sun-application.xml File

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

Here 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 File

The 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-location

Here 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 File

The 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 File

The 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-name

Here 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 file

The 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 File

The 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

A B C D E F G H I J K L M N O P Q R S T U V W

# A

## activation-config

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

### Superelements

mdb-resource-adapter (`sun-ejb-jar.xml`)

### Subelements

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

Table A–2 `activation-config` subelements

Element | Required | Description
--- | --- | ---
description | zero or one | Specifies a text description of the activation configuration.
activation-config-property | one or more | Specifies an activation configuration property.

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

Table A–3 `activation-config-property` subelements

Element | Required | Description
--- | --- | ---
activation-config-property-name | only one | Specifies the name of an activation configuration property.
activation-config-property-value | only one | Specifies the value of an activation configuration property.

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

Table A–4 `as-context` Subelements

Element | Required | Description
--- | --- | ---
auth-method | only one | Specifies the authentication method. The only supported value is `USERNAME_PASSWORD`.
realm | only one | Specifies the realm in which the user is authenticated.
required | only one | Specifies whether the authentication method specified must be used for client authentication.

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

### 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
--- | --- | ---
property (with attributes) | 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.

# B

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

Table A–7 `bean-cache` Subelements

Element | Required | Description
--- | --- | ---
max-cache-size | zero or one | Specifies the maximum number of beans allowable in cache.
is-cache-overflow-allowed | zero or one | Deprecated.
cache-idle-timeout-in-seconds | zero or one | Specifies the maximum time that a stateful session bean or entity bean is allowed to be idle in cache before being passivated. Default value is 10 minutes (600 seconds).
removal-timeout-in-seconds | zero or one | Specifies the amount of time a bean remains before being removed. If `removal-timeout-in-seconds` is less than `idle-timeout`, the bean is removed without being passivated.
resize-quantity | zero or one | Specifies the number of beans to be created if the pool is empty (subject to the `max-pool-size` limit). Values are from 0 to MAX_INTEGER.
victim-selection-policy | zero or one | Specifies the algorithm that must be used by the container to pick victims. Applies only to stateful session beans.

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

Table A–8 `bean-pool` Subelements

Element | Required | Description
--- | --- | ---
steady-pool-size | zero or one | Specifies the initial and minimum number of beans maintained in the pool. Default is 32.
resize-quantity | zero or one | Specifies the number of beans to be created if the pool is empty (subject to the `max-pool-size` limit). Values are from 0 to MAX_INTEGER.
max-pool-size | zero or one | Specifies the maximum number of beans in the pool. Values are from 0 to MAX_INTEGER. Default is to the EJB container value or 60.
max-wait-time-in-millis | zero or one | Deprecated.
pool-idle-timeout-in-seconds | zero or one | Specifies the maximum time that a bean is allowed to be idle in the pool. After this time, the bean is removed. This is a hint to the server. Default time is 600 seconds (10 minutes).

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

# C

## cache

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
--- | --- | ---
cache-helper | zero or more | Specifies a custom class that implements the `CacheHelper` interface.
default-helper | zero or one | Allows you to change the properties of the default, built-in cache-helper class.
property (with attributes) | zero or more | Specifies a cache property, which has a name and a value.
cache-mapping | 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. See Cache Class Names for possible values.
`MultiLRUSegmentSize` | `4096` | Specifies the number of entries in a segment of the cache table that should have its own LRU (least recently used) list. Applicable only if `cacheClassName` is set to `com.sun.appserv.web.cache.MultiLruCache`.
`MaxSize` | unlimited; `Long.MAX_VALUE` | Specifies an upper bound on the cache memory size in bytes (KB or MB units). Example values are `32 KB` or `2 MB`. Applicable only if `cacheClassName` is set to `com.sun.appserv.web.cache.BoundedMultiLruCache`.

### Cache Class Names

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

Table A–12 `cacheClassName` Values

Value | Description
--- | ---
`com.sun.appserv.web.cache.LruCache` | A bounded cache with an LRU (least recently used) cache replacement policy.
`com.sun.appserv.web.cache.BaseCache` | An unbounded cache suitable if the maximum number of entries is known.
`com.sun.appserv.web.cache.MultiLruCache` | A cache suitable for a large number of entries (>4096). Uses the `MultiLRUSegmentSize` property.
`com.sun.appserv.web.cache.BoundedMultiLruCache` | A cache suitable for limiting the cache size by memory rather than number of entries. Uses the `MaxSize` property.

## 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
--- | --- | ---
property (with attributes) | 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
--- | --- | ---
servlet-name | requires one `servlet-name` or `url-pattern` | Contains the name of a servlet.
url-pattern | requires one `servlet-name` or `url-pattern` | Contains a servlet URL pattern for which caching is enabled.
cache-helper-ref | 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.
dispatcher | zero or one if `cache-helper-ref` is not used | Contains a comma-separated list of `RequestDispatcher` methods for which caching is enabled.
timeout | 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.
refresh-field | zero or one if `cache-helper-ref` is not used | Specifies a field that gives the application component a programmatic way to refresh a cached entry.
http-method | zero or more if `cache-helper-ref` is not used | Contains an HTTP method that is eligible for caching.
key-field | zero or more if `cache-helper-ref` is not used | Specifies a component of the key used to look up and extract cache entries.
constraint-field | 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
--- | --- | ---
name | only one | Specifies the name of the entity.
value | 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
--- | --- | ---
column-name | 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
--- | --- | ---
method | 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 class loader 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
--- | --- | ---
property (with attributes) | zero or more | Specifies a property, which has a name and a value.

### Attributes

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

Table A–21 `class-loader` Attributes

Attribute | Default | Description
--- | --- | ---
`extra-class-path` | null | (optional) Specifies additional classpath settings for this web module.
`delegate` | `true` | (optional) If `true`, the web module follows the standard class loader delegation model and delegates to its parent class loader first before looking in the local class loader. You must set this to `true` for a web application that accesses EJB components or that acts as a web service client or endpoint. If `false`, the web module follows the delegation model specified in the Servlet specification and looks in its class loader before looking in the parent class loader. It’s safe to set this to `false` only for a web module that does not interact with any other modules.
`dynamic-reload-interval` |  | (optional) Not implemented. Included for backward compatibility with previous Sun Java System Web Server versions.

Note –

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

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

## client-container

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

Table A–22 `client-container` Subelements

Element | Required | Description
--- | --- | ---
target-server | only one | Specifies the IIOP listener configuration of the target server.
auth-realm | zero or one | Specifies the optional configuration for JAAS authentication realm.
client-credential | zero or one | Specifies the default client credential that is sent to the server.
log-service | zero or one | Specifies the default log file and the severity level of the message.
message-security-config | zero or more | Specifies configurations for message security providers.
property (with attributes) | zero or more | Specifies a property, which has a name and a value.

### Attributes

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

Table A–23 `client-container` Attributes

Attribute | Default | Description
--- | --- | ---
`send-password` | `true` | If `true`, specifies that client authentication credentials must be sent to the server. Without authentication credentials, all access to protected EJB components results in exceptions.

### Properties

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

Table A–24 `client-container` Properties

Property | Default | Description
--- | --- | ---
`com.sun.appserv.iiop.endpoints` | none | Specifies a comma-separated list of one or more IIOP endpoints used for load balancing. An IIOP endpoint is in the form host`:`port, where the host is an IP address or host name, and the port specifies the port number.

## 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
--- | --- | ---
property (with attributes) | zero or more | Specifies a property, which has a name and a value.

### Attributes

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

Table A–26 `client-credential` attributes

Attribute | Default | Description
--- | --- | ---
`user-name` | none | The user name used to authenticate the Application client container.
`password` | none | The password used to authenticate the Application client container.
`realm` | the default realm for the domain | (optional) The realm (specified by name) where credentials are to be resolved.

## cmp

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

### Superelements

ejb (`sun-ejb-jar.xml`)

### Subelements

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

Table A–27 `cmp` Subelements

Element | Required | Description
--- | --- | ---
mapping-properties | zero or one | This element is not implemented.
is-one-one-cmp | zero or one | This element is not implemented.
one-one-finders | zero or one | Describes the finders for CMP 1.1 beans.
prefetch-disabled | zero or one | Disables prefetching of entity bean states for the specified query methods.

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

Table A–28 `cmp-field-mapping` Subelements

Element | Required | Description
--- | --- | ---
field-name | only one | Specifies the Java identifier of a field. This identifier must match the value of the `field-name` subelement of the `cmp-field` that is being mapped.
column-name | one or more | Specifies the name of a column from the primary table, or the qualified table name (TABLE.COLUMN) of a column from a secondary or related table.
read-only | zero or one | Specifies that a field is read-only.
fetched-with | zero or one | Specifies the fetch group for this CMP field’s mapping.

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

Table A–29 `cmp-resource` Subelements

Element | Required | Description
--- | --- | ---
jndi-name | only one | Specifies the absolute `jndi-name` of a JDBC resource or Persistence Manager resource.
default-resource-principal | zero or one | Specifies the default runtime bindings of a resource reference.
property (with subelements) | zero or more | Specifies a property name and value. Used to configure `PersistenceManagerFactory` properties if the `jndi-name` subelement refers to a JDBC resource.
create-tables-at-deploy | zero or one | If `true`, specifies that database tables are created for beans that are automatically mapped by the EJB container.
drop-tables-at-undeploy | zero or one | If `true`, specifies that database tables that were automatically created when the bean(s) were last deployed are dropped when the bean(s) are undeployed.
database-vendor-name | zero or one | Specifies the name of the database vendor for which tables can be created.
schema-generator-properties | zero or one | Specifies field-specific type mappings and allows you to set the `use-unique-table-names` property.

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

Table A–30 `cmr-field-mapping` Subelements

Element | Required | Description
--- | --- | ---
cmr-field-name | only one | Specifies the Java identifier of a field. Must match the value of the `cmr-field-name` subelement of the `cmr-field` that is being mapped.
column-pair | one or more | Specifies the pair of columns that determine the relationship between two database tables.
fetched-with | zero or one | Specifies the fetch group for this CMR field’s relationship.

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

Table A–31 `column-pair` Subelements

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

## commit-option

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

Note –

Commit option A is not supported for this Application Server release.

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

Table A–32 `consistency` Subelements

Element | Required | Description
--- | --- | ---
none | exactly one subelement is required | No consistency checking occurs.
check-modified-at-commit | exactly one subelement is required | Checks concurrent modification of fields in modified beans at commit time.
lock-when-loaded | exactly one subelement is required | Obtains an exclusive lock when the data is loaded.
check-all-at-commit |  | This element is not implemented. Do not use.
lock-when-modified |  | This element is not implemented. Do not use.
check-version-of-accessed-instances | exactly one subelement is required | Checks the version column of the modified beans.

## 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
--- | --- | ---
constraint-field-value | 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.

Table A–35 `constraint-field-value` Attributes

Attribute | Default | Description
--- | --- | ---
`match-expr` | `equals` | (optional) Specifies the type of comparison performed with the value. Allowed values are `equals`, `not-equals`, `greater`, `lesser`, and `in-range`. If `match-expr` is `greater` or `lesser`, the value must be a number. If `match-expr` is `in-range`, the value must be of the form n1`-`n2, where n1 and n2 are numbers.
`cache-on-match` | `true` | (optional) If `true`, caches the response if matching succeeds.
`cache-on-match-failure` | `false` | (optional) If `true`, caches the response if matching fails.

## 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 Enterprise Edition 8.1 2005Q2 High Availability 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
--- | --- | ---
property (with attributes) | zero or more | Specifies a property, which has a name and a value.

### Properties

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

Table A–37 `cookie-properties` Properties

Property | Default | Description
--- | --- | ---
`cookiePath` | Context path at which the web module is installed. | Specifies the pathname that is set when the cookie is created. The browser sends the cookie if the pathname for the request contains this pathname. If set to `/` (slash), the browser sends cookies to all URLs served by the Application Server. You can set the path to a narrower mapping to limit the request URLs to which the browser sends cookies.
`cookieMaxAgeSeconds` | `-1` | Specifies the expiration time (in seconds) after which the browser expires the cookie.
`cookieDomain` | (unset) | Specifies the domain for which the cookie is valid.
`cookieComment` | `Sun Java System Application Server Session Tracking Cookie` | Specifies the comment that identifies the session tracking cookie in the cookie file. Applications can provide a more specific comment for the cookie.

## 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–4.

### Superelements

cmp-resource (`sun-ejb-jar.xml`)

### Subelements

none - contains data

# D

## database-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–4.

### 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
--- | --- | ---
property (with attributes) | 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.

## 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 JavaTM System Message Queue broker user repository. See the Security Management chapter in the Sun Java System Message Queue 3 2005Q4 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.

Table A–40 `default-resource-principal` Subelements

Element | Required | Description
--- | --- | ---
name | only one | Specifies the default resource principal name used to sign on to a resource manager.
password | only one | Specifies password of the default resource principal.

## 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–4.

### Superelements

cmp-resource (`sun-ejb-jar.xml`)

### Subelements

none - contains data

# E

## ejb

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

- All types of beans: `ejb-name`, `ejb-ref`, `resource-ref`, `resource-env-ref`, `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
--- | --- | ---
ejb-name | only one | Matches the `ejb-name` in the corresponding `ejb-jar.xml` file.
jndi-name | zero or more | Specifies the absolute `jndi-name`.
ejb-ref | zero or more | Maps the absolute JNDI name to the `ejb-ref` element in the corresponding J2EE XML file.
resource-ref | zero or more | Maps the absolute JNDI name to the `resource-ref` in the corresponding J2EE XML file.
resource-env-ref | zero or more | Maps the absolute JNDI name to the `resource-env-ref` in the corresponding J2EE XML file.
service-ref | zero or more | Specifies runtime settings for a web service reference.
pass-by-reference | zero or one | Specifies the passing method used by an enterprise bean calling a remote interface method in another bean that is colocated within the same process.
cmp | zero or one | Specifies runtime information for a container-managed persistence (CMP) entity bean for EJB 1.1 and EJB 2.1 beans.
principal | zero or one | Specifies the principal (user) name in an enterprise bean that has the `run-as` role specified.
mdb-connection-factory | zero or one | Specifies the connection factory associated with a message-driven bean.
jms-durable-subscription-name | zero or one | Specifies the durable subscription associated with a message-driven bean.
jms-max-messages-load | zero or one | Specifies the maximum number of messages to load into a Java Message Service session at one time for a message-driven bean to serve. The default is 1.
ior-security-config | zero or one | Specifies the security information for the IOR.
is-read-only-bean | zero or one | Specifies that this entity bean is read-only.
refresh-period-in-seconds | zero or one | Specifies the rate at which a read-only-bean must be refreshed from the data source.
commit-option | zero or one | Has valid values of B or C. Default value is B.
cmt-timeout-in-seconds | zero or one | Overrides the Transaction Timeout setting of the Transaction Service for an individual bean.
use-thread-pool-id | zero or one | Specifies the thread pool from which threads are selected for remote invocations of this bean.
gen-classes | zero or one | Specifies all the generated class names for a bean.
bean-pool | zero or one `bean-pool` | Specifies the bean pool properties. Used for stateless session beans, entity beans, and message-driven bean pools.
bean-cache | zero or one `bean-pool` | Specifies the bean cache properties. Used only for stateful session beans and entity beans.
mdb-resource-adapter | zero or one | Specifies runtime configuration information for a message-driven bean.
webservice-endpoint | zero or more | Specifies information about a web service endpoint.
flush-at-end-of-method | zero or one | Specifies the methods that force a database flush after execution. Used for entity beans.
checkpointed-methods | zero or one | Deprecated. Supported for backward compatibility. Use checkpoint-at-end-of-method instead.
checkpoint-at-end-of-method | zero or one | Specifies that the stateful session bean state is checkpointed, or persisted, after the specified methods are executed. The `availability-enabled` attribute must be set to `true`.

### Attributes

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

Table A–42 `ejb` Attributes

Attribute | Default | Description
--- | --- | ---
`availability-enabled` | `false` | (optional)If set to `true`, and if availability is enabled in the EJB container, high-availability features apply to this bean if it is a stateful session bean.

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

Table A–43 `ejb-ref` Subelements

Element | Required | Description
--- | --- | ---
ejb-ref-name | only one | Specifies the `ejb-ref-name` in the corresponding J2EE deployment descriptor file `ejb-ref` entry.
jndi-name | only one | Specifies the absolute `jndi-name` of a resource.

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

Table A–44 `enterprise-beans` Subelements

Element | Required | Description
--- | --- | ---
name | zero or one | Specifies the name string.
unique-id | zero or one | Specifies a unique system identifier. This data is automatically generated and updated at deployment/redeployment. Do not specify or edit this value.
ejb | zero or more | Defines runtime properties for a single enterprise bean within the application.
pm-descriptors | zero or one | Deprecated.
cmp-resource | zero or one | Specifies the database to be used for storing container-managed persistence (CMP) beans in an EJB JAR file.
message-destination | zero or more | Specifies the name of a logical message destination.
webservice-description | zero or more | Specifies a name and optional publish location for a web service.

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

Table A–45 `entity-mapping` Subelements

Element | Required | Description
--- | --- | ---
ejb-name | only one | Specifies the name of the entity bean in the `ejb-jar.xml` file to which the CMP bean corresponds.
table-name | only one | Specifies the name of a database table. The table must be present in the database schema file.
cmp-field-mapping | one or more | Associates a field with one or more columns to which it maps.
cmr-field-mapping | zero or more | A container-managed relationship field has a name and one or more column pairs that define the relationship.
secondary-table | zero or more | Describes the relationship between a bean’s primary and secondary table.
consistency | zero or one | Specifies container behavior in guaranteeing transactional consistency of the data in the bean.

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

# F

## fetched-with

Specifies the fetch group configuration for fields and relationships. The `fetched-with` element has different allowed and default subelements based on its parent element and the data types of the fields.

- If there is no `fetched-with` subelement of a 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.

Table A–46 `fetched-with` Subelements

Element | Required | Description
--- | --- | ---
default | exactly one subelement is required | Specifies that a CMP field belongs to the default hierarchical fetch group, which means it is fetched any time the bean is loaded from a database. Enables prefetching of a CMR field.
level | exactly one subelement is required | Specifies the level number of a hierarchical fetch group.
named-group | exactly one subelement is required | Specifies the name of an independent fetch group.
none | exactly one subelement is required | Specifies that this field or relationship is placed into its own individual fetch group, which means it is loaded from a database the first time it is accessed in this transaction.

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

Table A–47 `finder` Subelements

Element | Required | Description
--- | --- | ---
method-name | only one | Specifies the method name for the finder.
query-params | zero or one | Specifies the query parameters for the CMP 1.1 finder.
query-filter | zero or one | Specifies the query filter for the CMP 1.1 finder.
query-variables | zero or one | Specifies variables in query expression for the CMP 1.1 finder.
query-ordering | zero or one | Specifies the query ordering for the CMP 1.1 finder.

## 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
--- | --- | ---
method | one or more | Specifies a bean method.

# G

## gen-classes

Specifies all the generated class names for a bean.

Note –

This value is automatically generated by the server at deployment or redeployment time. Do not specify it or change it after deployment.

### Superelements

ejb (`sun-ejb-jar.xml`)

### Subelements

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

Table A–49 `gen-classes` Subelements

Element | Required | Description
--- | --- | ---
remote-impl | zero or one | Specifies the fully-qualified class name of the generated `EJBObject` impl class.
local-impl | zero or one | Specifies the fully-qualified class name of the generated `EJBLocalObject` impl class.
remote-home-impl | zero or one | Specifies the fully-qualified class name of the generated EJBHome impl class.
local-home-impl | zero or one | Specifies the fully-qualified class name of the generated `EJBLocalHome` impl class.

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

# H

## http-method

Specifies an HTTP method that is eligible for caching. The default is `GET`.

### Superelements

cache-mapping (`sun-web.xml`)

### Subelements

none - contains data

# I

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

Table A–50 `idempotent-url-pattern` Attributes

Attribute | Default | Description
--- | --- | ---
`url-pattern` | none | Specifies a URL pattern, which can contain wildcards. The URL pattern must conform to the mappings specified in section SRV 11.2 of the Servlet 2.4 specification.
`no-of-retries` | `-1` | (optional) Specifies the number of times the load balancer retries an idempotent request. A value of `-1` indicates infinite retries.

### Example

The following example specifies that all requests for the URI `sun-java/*` are idempotent.

    <idempotent-url-pattern url-pattern="sun_java/*" no-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.

Table A–51 `ior-security-config` Subelements

Element | Required | Description
--- | --- | ---
transport-config | zero or one | Specifies the security information for transport.
as-context | zero or one | Specifies the authentication mechanism used to authenticate the client. If specified, it is `USERNAME_PASSWORD`.
sas-context | zero or one | Describes the sas-context fields.

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

# J

## java-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
--- | --- | ---
method-name | only one | Specifies a method name.
method-params | 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.

Table A–53 `jsp-config` Subelements

Element | Required | Description
--- | --- | ---
property (with attributes) | zero or more | Specifies a property.

### Properties

The default property values are tuned for development of JSP files at the cost of performance. To maximize performance, set `jsp-config` properties to these non-default values:

- `development` - `false` (as an alternative, set to `true` and give `modificationTestInterval` a large value)

- `mappedfile` - `false`

- `trimSpaces` - `true`

- `suppressSmap` - `true`

- `fork` - `false` (on Solaris)

- `classdebuginfo` - `false`

The following table describes properties for the `jsp-config` element.

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://antinstaller.sourceforge.net/manual/manual/
`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.

# K

## key-field

Specifies a component of the key used to look up and extract cache entries. The web container looks for the named parameter, or field, in the specified scope.

If this element is not present, the web container uses the Servlet Path (the path section that corresponds to the servlet mapping that activated the current request). See the Servlet 2.4 specification, section SRV 4.4, for details on the Servlet Path.

### Superelements

cache-mapping (`sun-web.xml`)

### Subelements

none

### Attributes

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

Table A–55 `key-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`, `session.id`, and `session.attribute`.

# L

## level

Specifies the name of a hierarchical fetch group. The name must be an integer. Fields and relationships that belong to a hierarchical fetch group of equal (or lesser) value are fetched at the same time. The value of level must be greater than zero. Only one is allowed.

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

Table A–56 `locale-charset-info` Subelements

Element | Required | Description
--- | --- | ---
locale-charset-map | one or more | Maps a locale and an agent to a character encoding. Provided for backward compatibility. Used only for request processing, and only if no `parameter-encoding` is defined.
parameter-encoding | zero or one | Determines the default request character encoding and how the web container decodes parameters from forms according to a hidden field value.

### 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
--- | --- | ---
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 Table A–60 for more information.
`charset` | none | Specifies the character encoding to which the locale maps.

### Example Agents

The following table specifies example `agent` attribute values.

Table A–60 Example `agent` Attribute Values

Agent | `user-agent` Header and `agent` Attribute Value
--- | ---
Internet Explorer 5.00 for Windows 2000 |
    Mozilla/4.0 (compatible; MSIE 5.01; Windows NT 5.0)
Netscape 4.7.7 for Windows 2000 |
    Mozilla/4.77 [en] (Windows NT 5.0; U)
Netscape 4.7 for Solaris |
    Mozilla/4.7 [en] (X11; u; Sun OS 5.6 sun4u)

## 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
--- | --- | ---
property (with attributes) | zero or more | Specifies a property, which has a name and a value.

### Attributes

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

Table A–62 `log-service` attributes

Attribute | Default | Description
--- | --- | ---
`log-file` | your-ACC-dir`/logs/client.log` | (optional) Specifies the file where the application client container logging information is stored.
`level` | `SEVERE` | (optional) Sets the base level of severity. Messages at or above this setting get logged to the log file.

## 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
--- | --- | ---
auth-method | only one | Specifies the authentication method.

# M

## manager-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
--- | --- | ---
property (with attributes) | 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 web site, or the last few hits might be lost each time the server is restarted. Applicable only if the `persistence-type` attribute of the parent 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.

Table A–66 `mdb-connection-factory` Subelements

Element | Required | Description
--- | --- | ---
jndi-name | only one | Specifies the absolute `jndi-name`.
default-resource-principal | zero or one | Specifies the default sign-on (name/password) to the resource manager.

## 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
--- | --- | ---
resource-adapter-mid | zero or one | Specifies a resource adapter module ID.
activation-config | 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.

Table A–68 `message` Subelements

Element | Required | Description
--- | --- | ---
java-method | zero or one | Specifies the methods or operations to which message security requirements apply.
operation-name | zero or one | Specifies the WSDL name of an operation of a web service.

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

Table A–69 `message-destination` subelements

Element | Required | Description
--- | --- | ---
message-destination-name | only one | Specifies the name of a logical message destination defined within the corresponding J2EE deployment descriptor file.
jndi-name | only one | Specifies the `jndi-name` of the associated entity.

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

Table A–70 `message-security` Subelements

Element | Required | Description
--- | --- | ---
message | one or more | Specifies the methods or operations to which message security requirements apply.
request-protection | zero or one | Defines the authentication policy requirements of the application’s request processing.
response-protection | zero or one | Defines the authentication policy requirements of the application’s response processing.

### 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:

- By binding to a specific provider

- By specifying the message security requirements enforced by the provider

### 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
--- | --- | ---
message-security | zero or more | Specifies message security requirements.

### Attributes

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

Table A–72 `message-security-binding` Attributes

Attribute | Default | Description
--- | --- | ---
`auth-layer` | none | Specifies the message layer at which authentication is performed. The value must be `SOAP`.
`provider-id` | none | (optional) Specifies the authentication provider used to satisfy application-specific message security requirements. If this attribute is not specified, a default provider is used, if it is defined for the message layer. if no default provider is defined, authentication requirements defined in the `message-security-binding` are not enforced.

## 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
--- | --- | ---
provider-config | one or more | Specifies a configuration for one message security provider.

### Attributes

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

Table A–74 `message-security-config` Attributes

Attribute | Default | Description
--- | --- | ---
`auth-layer` | none | Specifies the message layer at which authentication is performed. The value must be `SOAP`.
`default-provider` | none | (optional) Specifies the server provider that is invoked for any application not bound to a specific server provider.
`default-client-provider` | none | (optional) Specifies the client provider that is invoked for any application not bound to a specific client provider.

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

Table A–75 `method` Subelements

Element | Required | Description
--- | --- | ---
description | zero or one | Specifies an optional text description.
ejb-name | zero or one | Matches the `ejb-name` in the corresponding `ejb-jar.xml` file.
method-name | only one | Specifies a method name.
method-intf | zero or one | Specifies the method interface to distinguish between methods with the same name in different interfaces.
method-params | zero or one | Specifies fully qualified Java type names of method parameters.

## 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
--- | --- | ---
method-param | zero or more | Specifies the fully qualified Java type name of a method parameter.

# N

## name

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

# O

## one-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
--- | --- | ---
finder | 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

# P

## parameter-encoding

Specifies the default request character encoding and how the web container decodes parameters from forms according to a hidden field value.

If both the 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.

Table A–78 `parameter-encoding` Attributes

Attribute | Default | Description
--- | --- | ---
`form-hint-field` | none | (optional) The name of the hidden field in the form. This field specifies the character encoding the web container uses for `request.``getParameter` and `request.``getReader` calls when the charset is not set in the request’s `content-type` header.
`default-charset` | `ISO-8859-1` | (optional) The default request character encoding.

## pass-by-reference

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

- If `false` (the default if this element is not present), this application uses pass-by-value semantics.

- If `true`, this application uses pass-by-reference semantics.

Note –

The `pass-by-reference` element only applies to remote calls. As defined in the EJB 2.1 specification, section 5.4, calls to local interfaces use pass-by-reference semantics.

If the `pass-by-reference` element is set to its default value of `false`, the passing semantics for calls to remote interfaces comply with the EJB 2.1 specification, section 5.4. If set to `true`, remote calls involve pass-by-reference semantics instead of pass-by-value semantics, contrary to this specification.

Portable programs cannot assume that a copy of the object is made during such a call, and thus that it’s safe to modify the original. Nor can they assume that a copy is not made, and thus that changes to the object are visible to both caller and callee. When this element is set to `true`, parameters and return values should be considered read-only. The behavior of a program that modifies such parameters or return values is undefined.

When a servlet or enterprise bean calls a remote interface method in another bean that is colocated within the same process, by default the 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.

Table A–79 `port-info` subelements

Element | Required | Description
--- | --- | ---
service-endpoint-interface | zero or one | Specifies the web service reference name relative to `java:comp/env`.
wsdl-port | zero or one | Specifies the WSDL port.
stub-property | zero or more | Specifies JAX-RPC property values that are set on a `javax.xml.rpc.Stub` object before it is returned to the web service client.
call-property | zero or more | Specifies JAX-RPC property values that are set on a `javax.xml.rpc.Call` object before it is returned to the web service client.
message-security-binding | zero or one | Specifies a custom authentication provider binding.

## 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
--- | --- | ---
query-method | 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
--- | --- | ---
name | 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:

- Optional with respect to Application Server

- Needed by a system or object that Application Server doesn’t have knowledge of, such as an LDAP server or a Java class

### 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
--- | --- | ---
description | zero or one | Specifies an optional text description of a property.

Note –

The `property` element in the `sun-acc.xml` file has no subelements.

### 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:

- Optional with respect to Application Server

- Needed by a system or object that Application Server doesn’t have knowledge of, such as an LDAP server or a Java class

### 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
--- | --- | ---
name | only one | Specifies the name of the property.
value | 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.

Table A–85 `provider-config` Subelements

Element | Required | Description
--- | --- | ---
request-policy | zero or one | Defines the authentication policy requirements of the authentication provider’s request processing.
response-policy | zero or one | Defines the authentication policy requirements of the authentication provider’s response processing.
property (with attributes) | zero or more | Specifies a property or a variable.

### Attributes

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

Table A–86 `provider-config` Attributes

Attribute | Default | Description
--- | --- | ---
`provider-id` | none | Specifies the provider ID.
`provider-type` | none | Specifies whether the provider is a `client`, `server`, or `client-server` authentication provider.
`class-name` | none | Specifies the Java implementation class of the provider. Client authentication providers must implement the `com.sun.enterprise.security.jauth.ClientAuthModule` interface. Server authentication providers must implement the `com.sun.enterprise.security.jauth.ServerAuthModule` interface. Client-server providers must implement both interfaces.

# Q

## query-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
--- | --- | ---
method-name | only one | Specifies a method name.
method-params | 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

# R

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

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

Table A–88 `refresh-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`, `session.id`, and `session.attribute`.

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

Table A–89 `request-policy` Attributes

Attribute | Default | Description
--- | --- | ---
`auth-source` | none | Specifies the type of required authentication, either `sender` (user name and password) or `content` (digital signature).
`auth-recipient` | none | Specifies whether recipient authentication occurs before or after content authentication. Allowed values are `before-content` and `after-content`.

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

Table A–90 `request-protection` Attributes

Attribute | Default | Description
--- | --- | ---
`auth-source` | none | Specifies the type of required authentication, either `sender` (user name and password) or `content` (digital signature).
`auth-recipient` | none | Specifies whether recipient authentication occurs before or after content authentication. Allowed values are `before-content` and `after-content`.

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

Table A–91 `resource-env-ref` Subelements

Element | Required | Description
--- | --- | ---
resource-env-ref-name | only one | Specifies the `res-ref-name` in the corresponding J2EE deployment descriptor file `resource-env-ref` entry.
jndi-name | only one | Specifies the absolute `jndi-name` of a resource.

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

Note –

Connections acquired from JMS connection factories are not shareable in the current release of the Application Server. The `res-sharing-scope` element in the `ejb-jar.xml` file `resource-ref` element is ignored for JMS connection factories.

When `resource-ref` specifies a JMS connection factory for the Sun Java System Message Queue, the `default-resource-principal` (name/password) must exist in the Message Queue user repository. Refer to the Security Management chapter in the Sun Java System Message Queue 3 2005Q4 Administration Guide for information on how to manage the Message Queue user repository.

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

Table A–92 `resource-ref` Subelements

Element | Required | Description
--- | --- | ---
res-ref-name | only one | Specifies the `res-ref-name` in the corresponding J2EE deployment descriptor file `resource-ref` entry.
jndi-name | only one | Specifies the absolute `jndi-name` of a resource.
default-resource-principal | zero or one | Specifies the default principal (user) for the resource.

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

Table A–93 `response-policy` Attributes

Attribute | Default | Description
--- | --- | ---
`auth-source` | none | Specifies the type of required authentication, either `sender` (user name and password) or `content` (digital signature).
`auth-recipient` | none | Specifies whether recipient authentication occurs before or after content authentication. Allowed values are `before-content` and `after-content`.

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

Table A–94 `response-protection` Attributes

Attribute | Default | Description
--- | --- | ---
`auth-source` | none | Specifies the type of required authentication, either `sender` (user name and password) or `content` (digital signature).
`auth-recipient` | none | Specifies whether recipient authentication occurs before or after content authentication. Allowed values are `before-content` and `after-content`.

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

# S

## sas-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
--- | --- | ---
caller-propagation | 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
--- | --- | ---
property (with subelements) | 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–4.
    bean-name.field-name.attribute
| none | Defines a column attribute. For attribute descriptions, see Table A–98.

The following table lists the column attributes for properties defined in the `schema-generator-properties` element.

Table A–98 `schema-generator-properties` Column Attributes

Attribute | Description
--- | ---
`jdbc-type` | Specifies the JDBC type of the column created for the CMP field. The actual SQL type generated is based on this JDBC type but is database vendor specific.
`jdbc-maximum-length` | Specifies the maximum number of characters stored in the column corresponding to the CMP field. Applies only when the actual SQL that is generated for the column requires a length. For example, a `jdbc-maximum-length` of `32` on a CMP `String` field such as `firstName` normally results in a column definition such as VARCHAR(32). But if the `jdbc-type` is `CLOB` and you are deploying on Oracle, the resulting column definition is CLOB. No length is given, because in an Oracle database, a CLOB has no length.
`jdbc-precision` | Specifies the maximum number of digits stored in a column which represents a numeric type.
`jdbc-scale` | Specifies the number of digits stored to the right of the decimal point in a column that represents a floating point number.
`jdbc-nullable` | Specifies whether the column generated for the CMP field allows null values.

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

Table A–99 `secondary table` Subelements

Element | Required | Description
--- | --- | ---
table-name | only one | Specifies the name of a database table.
column-pair | one or more | Specifies the pair of columns that determine the relationship between two database tables.

## 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–100 `security` Subelements

Element | Required | Description
--- | --- | ---
ssl | only one | Specifies the SSL processing parameters.
cert-db | 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.

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.

Table A–101 `security-role-mapping` Subelements

Element | Required | Description
--- | --- | ---
role-name | only one | Contains the `role-name` in the `security-role` element of the corresponding J2EE deployment descriptor file.
principal-name | one or more if no `group-name`, otherwise zero or more | Contains a principal (user) name in the current realm. In an enterprise bean, the principal must have the run-as role specified.
group-name | one or more if no `principal-name`, otherwise zero or more | Contains a group name in the current realm.

## 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–102 `service-qname` subelements

Element | Required | Description
--- | --- | ---
namespaceURI | only one | Specifies the namespace URI.
localpart | 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:

- To define the port used to resolve a container-managed port

- To define the default Stub/Call property settings for Stub objects

- To define the URL of a final WSDL document to be used instead of the one associated with the `service-ref` in the standard J2EE deployment descriptor

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

Table A–103 `service-ref` subelements

Element | Required | Description
--- | --- | ---
service-ref-name | only one | Specifies the web service reference name relative to `java:comp/env`.
port-info | zero or more | Specifies information for a port within a web service reference.
call-property | zero or more | Specifies JAX-RPC property values that can be set on a `javax.xml.rpc.Call` object before it is returned to the web service client.
wsdl-override | zero or one | Specifies a valid URL pointing to a final WSDL document.
service-impl-class | zero or one | Specifies the name of the generated service implementation class.
service-qname | zero or one | Specifies the WSDL service element that is being referenced.

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

Table A–104 `servlet` Subelements

Element | Required | Description
--- | --- | ---
servlet-name | only one | Contains the name of a servlet, which is matched to a `servlet-name` in `web.xml`.
principal-name | zero or one | Contains a principal (user) name in the current realm.
webservice-endpoint | zero or more | Specifies information about a web service endpoint.

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

Table A–105 `session-config` Subelements

Element | Required | Description
--- | --- | ---
session-manager | zero or one | Specifies session manager configuration information.
session-properties | zero or one | Specifies session properties.
cookie-properties | zero or one | Specifies session cookie properties.

## 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–106 `session-manager` Subelements

Element | Required | Description
--- | --- | ---
manager-properties | zero or one | Specifies session manager properties.
store-properties | zero or one | Specifies session persistence (storage) properties.

### Attributes

The following table describes attributes for the `session-manager` element.

Table A–107 `session-manager` Attributes

Attribute | Default | Description
--- | --- | ---
`persistence-type` | `memory` | (optional) Specifies the session persistence mechanism. Allowed values are `memory` ,`file`, and `ha` . For production environments that require session persistence, use `ha`.

## session-properties

Specifies session properties.

### Superelements

session-config (`sun-web.xml`)

### Subelements

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

Table A–108 `session-properties` Subelements

Element | Required | Description
--- | --- | ---
property (with attributes) | zero or more | Specifies a property, which has a name and a value.

### Properties

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

Table A–109 `session-properties` Properties

Property | Default | Description
--- | --- | ---
`timeoutSeconds` | `1800` | Specifies the default maximum inactive interval (in seconds) for all sessions created in this web module. If set to `0` or less, sessions in this web module never expire. If a `session-timeout` element is specified in the `web.xml` file, the `session-timeout` value overrides any `timeoutSeconds` value. If neither `session-timeout` nor `timeoutSeconds` is specified, the `timeoutSeconds` default is used. Note that the `session-timeout` element in `web.xml` is specified in minutes, not seconds.
`enableCookies` | `true` | Uses cookies for session tracking if set to `true`.
`enableURLRewriting` | `true` | Enables URL rewriting. This provides session tracking via URL rewriting when the browser does not accept cookies. You must also use an `encodeURL` or `encodeRedirectURL` call in the servlet or JSP.

## ssl

Defines SSL processing parameters.

### Superelements

security (`sun-acc.xml`)

### Subelements

none

### Attributes

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

Table A–110 `ssl attributes`

Attribute | Default | Description
--- | --- | ---
`cert-nickname` | none | (optional) The nickname of the server certificate in the certificate database or the PKCS#11 token. In the certificate, the name format is tokenname`:`nickname. Including the tokenname`:` part of the name in this attribute is optional.
`ssl2-enabled` | `false` | (optional) Determines whether SSL2 is enabled.
`ssl2-ciphers` | none | (optional) A space-separated list of the SSL2 ciphers used with the prefix + to enable or - to disable. For example, `+rc4`. Allowed values are `rc4, rc4export, rc2, rc2export, idea, des, desede3`.
`ssl3-enabled` | `true` | (optional) Determines whether SSL3 is enabled.
`ssl3-tls-ciphers` | none | (optional) A space-separated list of the SSL3 ciphers used, with the prefix + to enable or - to disable, for example +`rsa_des_sha`. Allowed SSL3 values are `rsa_rc4_128_md5, , rsa_des_sha, rsa_rc4_40_md5, rsa_rc2_40_md5, rsa_null_md5. Allowed TLS values are rsa_des_56_sha, rsa_rc4_56_sha`.
`tls-enabled` | `true` | (optional) Determines whether TLS is enabled.
`tls-rollback-enabled` | `true` | (optional) Determines whether TLS rollback is enabled. Enable TLS rollback for Microsoft Internet Explorer 5.0 and 5.5.

## 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–111 `store-properties` Subelements

Element | Required | Description
--- | --- | ---
property (with attributes) | 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–112 `store-properties` Properties

Property | Default | Description
--- | --- | ---
`directory` | domain-dir`/generated/jsp/j2ee-apps/`app-name`/`app-name`_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–113 `stub-property` subelements

Element | Required | Description
--- | --- | ---
name | only one | Specifies the name of the entity.
value | 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 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.

Table A–114 `sun-application` Subelements

Element | Required | Description
--- | --- | ---
web | zero or more | Specifies the application’s web tier configuration.
pass-by-reference | zero or one | Determines whether EJB modules use pass-by-value or pass-by-reference semantics.
unique-id | zero or one | Contains the unique ID for the application.
security-role-mapping | zero or more | Maps a role in the corresponding J2EE XML file to a user or group.
realm | zero or one | Specifies an authentication realm.

## sun-application-client

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

Table A–115 `sun-application-client` subelements

Element | Required | Description
--- | --- | ---
ejb-ref | zero or more | Maps the absolute JNDI name to the `ejb-ref` in the corresponding J2EE XML file.
resource-ref | zero or more | Maps the absolute JNDI name to the `resource-ref` in the corresponding J2EE XML file.
resource-env-ref | zero or more | Maps the absolute JNDI name to the `resource-env-ref` in the corresponding J2EE XML file.
service-ref | zero or more | Specifies runtime settings for a web service reference.
message-destination | zero or more | Specifies the name of a logical message destination.

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

Table A–116 `sun-cmp-mapping` Subelements

Element | Required | Description
--- | --- | ---
schema | only one | Specifies the file that contains a description of the database schema.
entity-mapping | one or more | Specifies the mapping of a bean to database columns.

## sun-cmp-mappings

Defines the 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–117 `sun-cmp-mappings` Subelements

Element | Required | Description
--- | --- | ---
sun-cmp-mapping | one or more | Specifies beans mapped to a particular database schema.

## sun-ejb-jar

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

Table A–118 `sun-ejb-jar` Subelements

Element | Required | Description
--- | --- | ---
security-role-mapping | zero or more | Maps a role in the corresponding J2EE XML file to a user or group.
enterprise-beans | only one | Describes all the runtime properties for an EJB JAR file in the application.

## sun-web-app

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

Table A–119 `sun-web-app` Subelements

Element | Required | Description
--- | --- | ---
context-root | zero or one | Contains the web context root for the web application.
security-role-mapping | zero or more | Maps roles to users or groups in the currently active realm.
servlet | zero or more | Specifies a principal name for a servlet, which is used for the `run-as` role defined in `web.xml`.
idempotent-url-pattern | zero or more | Specifies a URL pattern for idempotent requests.
session-config | zero or one | Specifies session manager, session cookie, and other session-related information.
ejb-ref | zero or more | Maps the absolute JNDI name to the `ejb-ref` in the corresponding J2EE XML file.
resource-ref | zero or more | Maps the absolute JNDI name to the `resource-ref` in the corresponding J2EE XML file.
resource-env-ref | zero or more | Maps the absolute JNDI name to the `resource-env-ref` in the corresponding J2EE XML file.
service-ref | zero or more | Specifies runtime settings for a web service reference.
cache | zero or one | Configures caching for web application components.
class-loader | zero or one | Specifies class loader configuration information.
jsp-config | zero or one | Specifies JSP configuration information.
locale-charset-info | zero or one | Deprecated. Use the `parameter-encoding` subelement of `sun-web-app` instead.
property (with attributes) | zero or more | Specifies a property, which has a name and a value.
parameter-encoding | zero or one | Determines the default request character encoding and how the web container decodes parameters from forms according to a hidden field value.
message-destination | zero or more | Specifies the name of a logical message destination.
webservice-description | zero or more | Specifies a name and optional publish location for a web service.

### Attributes

The following table describes attributes for the `sun-web-app` element.

Table A–120 `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.

Table A–121 `sun-web-app` Properties

Property | Default | Description
--- | --- | ---
`allowLinking` | `true` | If `true`, resources in this web application that are symbolic links are served.
`crossContextAllowed` | `true` | If `true`, allows this web application to access the contexts of other web applications using the `ServletContext.getContext()`method.
`relativeRedirectAllowed` | `false` | If `true`, allows this web application to send a relative URL to the client using `HttpServletResponse.sendRedirect()`, and instructs the web container not to translate any relative URLs to fully qualified ones.
`reuseSessionID` | `false` | If `true`, sessions generated for this web application use the session ID specified in the request.
`singleThreadedServletPoolSize` | `5` | Specifies the maximum number of servlet instances allocated for each `SingleThreadModel` servlet in the web application.
`tempdir` | domain-dir`/generated/j2ee-apps/`app-name or domain-dir`/generated/j2ee-modules/`module-name | Specifies a temporary directory for use by this web module. This value is used to construct the value of the `javax.servlet.context.tempdir` context attribute. Compiled JSP files are also placed in this directory.
`useResponseCTForHeaders` | `false` | If `true`, response headers are encoded using the response’s charset instead of the default (UTF-8).

# T

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

Table A–122 `target-server` subelements

Element | Required | Description
--- | --- | ---
description | zero or one | Specifies the description of the target server.
security | zero or one | Specifies the security configuration for the IIOP/SSL communication with the target server.

### Attributes

The following table describes attributes for the `target-server` element.

Table A–123 `target-server` attributes

Attribute | Default | Description
--- | --- | ---
`name` | none | Specifies the name of the application server instance accessed by the client container.
`address` | none | Specifies the host name or IP address (resolvable by DNS) of the server to which this client attaches.
`port` | none | Specifies the naming service port number of the server to which this client attaches. For a new server instance, assign a port number other than 3700. You can change the port number in the Administration Console. See the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide for more information.

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

Table A–124 `timeout` Attributes

Attribute | Default | Description
--- | --- | ---
`name` | none | Specifies the timeout input parameter, whose value is interpreted in seconds. The field’s type must be `java.lang.Long` or `java.lang.Integer`.
`scope` | `request.attribute` | (optional) Specifies the scope from which the input parameter is retrieved. Allowed values are `context.attribute`, `request.header`, `request.parameter`, `request.cookie`, `request.attribute`, and `session.attribute`.

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

Table A–125 `transport-config` Subelements

Element | Required | Description
--- | --- | ---
integrity | only one | Specifies if the target supports integrity-protected messages. The values are NONE, SUPPORTED, or REQUIRED.
confidentiality | only one | Specifies if the target supports privacy-protected messages. The values are NONE, SUPPORTED, or REQUIRED.
establish-trust-in-target | only one | Specifies if the target is capable of authenticating to a client. The values are NONE, SUPPORTED, or REQUIRED.
establish-trust-in-client | only one | Specifies if the target is capable of authenticating a client. The values are NONE, SUPPORTED, or REQUIRED.

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

# U

## unique-id

Contains the unique ID for the application. This value is automatically updated each time the application is deployed or redeployed. Do not edit this value.

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

# V

## value

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.

Note –

You cannot plug in your own victim selection algorithm.

The victims are generally passivated into a backup store (typically a file system or database). This store is cleaned during startup, and also by a periodic background process that removes idle entries as specified by `removal-timeout-in-seconds`. The backup store is monitored by a background thread (or sweeper thread) to remove unwanted entries.

Applies to stateful session beans.

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

# W

## web

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–126 `web` Subelements

Element | Required | Description
--- | --- | ---
web-uri | only one | Contains the web URI for the application.
context-root | 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.

Table A–127 `webservice-description` subelements

Element | Required | Description
--- | --- | ---
webservice-description-name | only one | Specifies a unique name for the web service within a web or EJB module.
wsdl-publish-location | zero or one | Specifies the URL of a directory to which a web service’s WSDL is published during deployment.

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

Table A–128 `webservice-endpoint` subelements

Element | Required | Description
--- | --- | ---
port-component-name | only one | Specifies a unique name for a port component within a web or EJB module.
endpoint-address-uri | zero or one | Specifies the automatically generated endpoint address.
login-config | zero or one | Specifies the authentication configuration for an EJB web service endpoint.
message-security-binding | zero or one | Specifies a custom authentication provider binding.
transport-guarantee | zero or one | Specifies that the communication between client and server is `NONE`, `INTEGRAL`, or `CONFIDENTIAL`.
service-qname | zero or one | Specifies the WSDL service element that is being referenced.
tie-class | zero or one | Specifies the automatically generated name of a tie implementation class for a port component.
servlet-impl-class | zero or one | Specifies the automatically generated name of the generated servlet implementation class.

## 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–129 `wsdl-port` subelements

Element | Required | Description
--- | --- | ---
namespaceURI | only one | Specifies the namespace URI.
localpart | 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`.

- Previous: Part III Using Services and APIs

- © 2010, Oracle Corporation and/or its affiliates