Visit Azul.com Support

Azul Payara Deployment Descriptor Files

Table of Contents
Need help?
Schedule a consultation with an Azul performance expert.
Contact Us

This appendix describes the element hierarchies in the Azul Payara deployment descriptors that are supported on top of the standard Jakarta EE deployment descriptors.

About the Azul Payara Deployment Descriptors

Each deployment descriptor XML file has a corresponding Document Type Definition (DTD) file, which defines the elements, data, and attributes that the deployment descriptor file can contain.

For example, the payara-application_11_0-0.dtd file defines the structure of the payara-application.xml file. The DTD files for the Payara Server deployment descriptors are located in the as-install/lib/dtds directory.

The Platform Server deployment descriptor files must be readable and writable by the file owners. In each deployment descriptor file, sub-elements must be defined in the order in which they are listed under each Sub-elements heading, unless otherwise noted.

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

Important
 Do not edit the DTD files; their contents change only with new versions of Payara Server.

The following table lists the Azul Payara deployment descriptors and their DTD files.

Table 1. Azul Payara Deployment Descriptors and DTDs
Deployment Descriptor DTD File Description

glassfish-application.xml (deprecated)

payara-application.xml

glassfish-application_6_0-1.dtd

payara-application_11_0-0.dtd

Configures an entire Jakarta EE application (EAR file).

glassfish-web.xml (deprecated)

payara-web.xml

glassfish-web-app_3_0-1.dtd

payara-web-app_4.dtd

Configures a web application (WAR file).

glassfish-ejb-jar.xml (deprecated)

payara-ejb-jar.xml

glassfish-ejb-jar_3_1-1.dtd

payara-ejb-jar_4_0-0.dtd

Configures an enterprise bean (EJB JAR file).

glassfish-application-client.xml (deprecated)

payara-application-client.xml

glassfish-application-client_6_0-1.dtd

payara-application-client_11_0-0.dtd

Configures an Application Client Container (ACC) client (JAR file).

glassfish-resources.xml (deprecated)

payara-resources.xml

glassfish-resources_1_5.dtd

payara-resources_1_8.dtd

Configures application-scoped resources.

sun-acc.xml (deprecated)

glassfish-acc.xml (deprecated)

payara-acc.xml

sun-application-client-container_1_2.dtd

glassfish-application-client-container_1_3.dtd

payara-application-client-container_1_4.dtd

Configures the Application Client Container.

This is more of a configuration file than a deployment descriptor. Payara Server provides a default file in the domain-dir/config directory.

Specifying a different file is optional.
Important
 Deployment descriptors whose names start with the glassfish- prefix are referred as "original" deployment descriptor files from Eclipse GlassFish, since these files names and DTDs were created while supporting Eclipse GlassFish and their support has been inherited by Azul Payara.

The Payara-application.xml File

Important
 glassfish-application.xml is deprecated and support will be removed in a future release. It is recommended to use payara-application.xml instead.

The payara-application.xml file configures an entire Jakarta EE application (EAR file). The element hierarchy is as follows:

 
payara-application
.  web
.  .  web-uri
.  .  context-root
.  pass-by-reference
.  unique-id
.  security-role-mapping
.  .  role-name
.  .  principal-name
.  .  group-name
.  realm
.  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-ref
.  .  message-destination-ref-name
.  .  jndi-name
.  message-destination
.  .  message-destination-name
.  .  jndi-name
.  archive-name
.  compatibility
.  keep-state
.  version-identifier
.  classloading-delegate
.  enable-implicit-cdi
.  whitelist-package
.  scanning-exclude
.  scanning-include
sample payara-application.xml file:
 
<!DOCTYPE payara-application PUBLIC "-//Payara.fish//DTD
Payara Application Server 7 Jakarta EE Application 11//EN"
"https://raw.githubusercontent.com/payara/Payara-Documentation/main-7/docs/modules/ROOT/pages/Appendix/Schemas/payara-application_11-0.dtd">
<payara-application>
   <unique-id>67488732739338240</unique-id>
</payara-application>

The glassfish-web.xml and payara-web.xml Files

The glassfish-web.xml file configures a web application (WAR file). It is an original Eclipse GlassFish deployment descriptor.

The payara-web.xml is a matching Azul Payara variant which is recommended to be used whenever possible.

Important
 glassfish-web.xml is deprecated and support will be removed in a future release. It is recommended to use payara-web.xml instead.

Their element hierarchy is as follows:

 
payara-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
.  .  .  debugging-enabled
.  .  .  property (with attributes)
.  .  .  .  description
.  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
.  message-destination-ref
.  .  message-destination-ref-name
.  .  jndi-name
.  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
.  parameter-encoding
.  property (with attributes)
.  .  description
.  valve
.  message-destination
.  .  message-destination-name
.  .  jndi-name
.  webservice-description
.  .  webservice-description-name
.  .  wsdl-publish-location
.  keep-state
.  version-identifier
.  jaxrs-roles-allowed-enabled
.  scanning-exclude
.  scanning-include
.  whitelist-package
A sample payara-web.xml file:
 
<!DOCTYPE payara-web-app PUBLIC "-//Payara.fish//DTD Payara Server 7 Servlet 6.1//EN" "https://raw.githubusercontent.com/payara/Payara-Documentation/main-7/docs/modules/ROOT/pages/Appendix/Schemas/payara-web-app_6_1-0.dtd">
<payara-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/>
</payara-web-app>

The payara-ejb-jar.xml File

Important
 glassfish-ejb-jar.xml is deprecated and support will be removed in a future release. It is recommended to use payara-ejb-jar.xml instead.

The payara-ejb-jar.xml file configures an enterprise bean (EJB JAR file). The element hierarchy is as follows:

 
payara-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
         clustered-bean
.  .  .  clustered-key-name
.  .  .  clustered-lock-type
.  .  .  clustered-attach-postconstruct
.  .  .  clustered-detach-predestroy
.  .  .  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-ref
.  .  .  .  message-destination-ref-name
.  .  .  .  jndi-name
.  .  .  pass-by-reference
.  .  .  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
.  .  .  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
.  .  .  .  .  realm
.  .  .  .  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
.  .  .  .  debugging-enabled
.  .  .  .  property (with subelements)
.  .  .  .  .  name
.  .  .  .  .  value
.  .  .  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
.  .  .  per-request-load-balancing
.  .  pm-descriptors
.  .  message-destination
.  .  .  message-destination-name
.  .  .  jndi-name
.  .  webservice-description
.  .  .  webservice-description-name
.  .  .  wsdl-publish-location
.  .  property (with sub-elements)
.  .  .  name
.  .  .  value
.  compatibility
.  disable-nonportable-jndi-names
.  keep-state
.  version-identifier
   webservice-default-login-config
Note
 If any configuration information for an enterprise bean is not specified in the payara-ejb-jar.xml file, it defaults to a corresponding setting in the EJB container if an equivalency exists.
A sample payara-ejb-jar.xml file:
 
<!DOCTYPE payara-ejb-jar PUBLIC "-//Payara.fish//
DTD Payara Application Server 7 EJB 4.0//EN"
"https://raw.githubusercontent.com/payara/Payara-Documentation/main-7/docs/modules/ROOT/pages/Appendix/Schemas/payara-ejb-jar_4_0-0.dtd}">
<payara-ejb-jar>
    <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>
    </enterprise-beans>
    <keep-state>true</keep-state>
</payara-ejb-jar>

The payara-application-client.xml File

Important
 glassfish-application-client.xml is deprecated and support will be removed in a future release. It is recommended to use payara-application-client.xml instead.

The payara-application-client.xml file configures an Application Client Container (ACC) client (JAR file). The element hierarchy is as follows:

 
payara-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-ref
.  .  message-destination-ref-name
.  .  jndi-name
.  message-destination
.  .  message-destination-name
.  .  jndi-name
.  java-web-start-access
.  .  context-root
.  .  eligible
.  .  vendor
.  .  jnlp-doc
.  version-identifier
A sample payara-application-client.xml file:
 
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE payara-application-client PUBLIC "-//Payara.fish//DTD Payara Application Server 7 Jakarta EE Application Client 11//EN" "/payara-community/appendix/schemas/payara-application-client_11-0.dtd">
<payara-application-client>
  <message-destination-ref>
    <message-destination-ref-name>ClientQueue</message-destination-ref-name>
    <jndi-name>jms/security_mdb_OutQueue</jndi-name>
  </message-destination-ref>
</payara-application-client>

The glassfish-resources.xml and payara-resources.xml Files

Important
 glassfish-resources.xml is deprecated and support will be removed in a future release. It is recommended to use payara-resources.xml instead.

The glassfish-resources.xml file configures application-scoped resources. It is an original Eclipse GlassFish deployment descriptor.

The payara-resources.xml is a matching Azul Payara variant that supports additional elements.

Their element hierarchy is as follows:

 
resources
.  custom-resource
.  .  description
.  .  property (with attributes)
.  .  .  description
.  external-jndi-resource
.  .  description
.  .  property (with attributes)
.  .  .  description
.  jdbc-resource
.  .  description
.  .  property (with attributes)
.  .  .  description
.  mail-resource
.  .  description
.  .  property (with attributes)
.  .  .  description
.  admin-object-resource
.  .  description
.  .  property (with attributes)
.  .  .  description
.  connector-resource
.  .  description
.  .  property (with attributes)
.  .  .  description
.  resource-adapter-config
.  .  property (with attributes)
.  .  .  description
.  jdbc-connection-pool
.  .  description
.  .  log-jdbc-calls
.  .  property (with attributes)
.  .  .  description
.  connector-connection-pool
.  .  description
.  .  security-map
.  .  .  principal
.  .  .  user-group
.  .  .  backend-principal
.  .  property (with attributes)
.  .  .  description
.  work-security-map
.  .  description
.  .  principal-map
.  .  group-map
.  managed-executor-service (*)
.  managed-scheduled-executor-service (*)
.  managed-thread-factory (*)
Important
 The elements marked as (*) are only supported in the payara-resources.xml deployment descriptor variant.

  1. A sample payara-resources.xml

<!DOCTYPE resources PUBLIC "-//Payara.fish//DTD Payara Server {release-id} Resource Definitions//EN" "{payaraResourcesDtd}">
<resources>
    <!-- Connects to MySql database called 'test' on a server called 'database' -->
    <jdbc-connection-pool name="jdbc/testConnPool"
                          res-type="javax.sql.DataSource"
                          datasource-classname="com.mysql.jdbc.jdbc2.optional.MysqlDataSource"
                          pool-resize-quantity="2"
                          max-pool-size="32"
                          steady-pool-size="8">
        <property name="URL" value="jdbc:mysql://database:3306/test"/>
        <property name="User" value="root"/>
        <property name="Password" value="password"/>
    </jdbc-connection-pool>
    <jdbc-resource enabled="true" jndi-name="jdbc/testDS" object-type="user" pool-name="jdbc/testConnPool">
        <description>Test DataSource jdbc/testDS for Connection Pool jdbc/testConnPool</description>
    </jdbc-resource>
</resources>

The Sun-acc.xml File

The sun-acc.xml file configures the Application Client Container. This is more of a configuration file than a deployment descriptor.

Payara Server provides a default file in the domain-dir/config directory. Specifying a different file is optional. The element hierarchy 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)

Deployment Descriptor Precedence Order

When multiple vendor deployment descriptors are present in the same module (including deployment descriptors of the original Eclipse GlassFish and of the old Sun Application Server), the descriptors are processed with the following precedence order in default mode:

 
Azul Payara > Eclipse GlassFish Server > Sun Application Server