Appendix A Deployment Descriptor Files

Previous Contents Index Next
Sun Java System Application Server Platform Edition 8.1 2005Q1 Developer's Guide

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 Sun Java System Application Server. The sun-application.xml, sun-web.xml, and sun-cmp-mappings.xml files are optional; all the others are required.

Each deployment descriptor (or XML) file has a corresponding DTD file, which defines the elements, data, and attributes that the deployment descriptor file can contain. For example, the sun-application_1_4-0.dtd file defines the structure of the sun-application.xml file. The DTD files for the Sun Java System Application Server deployment descriptors are located in the install_dir/lib/dtds directory.

Note

Do not edit the DTD files; their contents change only with new versions of Sun Java System Application Server.

To check the correctness of these deployment descriptors prior to deployment, see “The Deployment Descriptor Verifier” on page 80.

For general information about DTD files and XML, see the XML specification at:

http://www.w3.org/TR/REC-xml

The following table lists the Sun Java System 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 Sun Java System 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” on page 40.

Superelements

client-container (sun-acc.xml)

Subelements

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

Table A-5  auth-realm subelement

Element

Required

Description

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” on page 40.

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. The cacheClassName Values table below lists possible values.

MultiLRUSegmentSize

4096

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

MaxSize

unlimited; Long.MAX_VALUE

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

Cache Class Names

The following table lists possible values of the cacheClassName property.

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


Note	Do not edit the DTD files; their contents change only with new versions of Sun Java System Application Server.

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 Sun Java System 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.


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.

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.

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.

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.

Attribute	Default	Description
name	none	Defines the name of this realm.
classname	none	Defines the Java class which implements this realm.

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.

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

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.

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.

Property	Default	Description
cacheClassName	com.sun.appserv.web.cache.LruCache	Specifies the fully qualified name of the class that implements the cache functionality. The cacheClassName Values table below lists possible values.
MultiLRUSegmentSize	4096	Specifies the number of entries in a segment of the cache table that should have its own LRU (least recently used) list. Applicable only if cacheClassName is set to com.sun.appserv.web.cache.MultiLruCache.
MaxSize	unlimited; Long.MAX_VALUE	Specifies an upper bound on the cache memory size in bytes (KB or MB units). Example values are 32 KB or 2 MB. Applicable only if cacheClassName is set to com.sun.appserv.web.cache.BoundedMultiLruCache.

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.

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.

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