Elements of the Deployment Descriptor Files

This page is a reference for extra and changed elements added to the GlassFish proprietary deployment descriptors

classloading-delegate

With this option its possible to enable/disable class loading delegation. This allows deployed application to use libraries included on them, overriding the versions included on the server.

For more information about how class delegation can be configured on Payara Server, see the Enhanced Class loading section.

clustered-attach-postconstruct

Whether to call @PostConstruct each time the bean is created on a different node. Will result in multiple calls.

Valid values are true or false. The default value is true.

clustered-bean

Whether this bean should be a Clustered Singleton. Can be applied only to singleton EJBs.

Valid values are true or false. The default value is false.

clustered-detach-predestroy

Whether to call @PreDestroy when the singleton is destroyed on an instance while still being available on another. Will result in multiple calls.

Valid values are true or false. The default value is true.

clustered-key-name

The key used for replication of clustered beans. Applies to singleton EJBs when clustered-bean is set to true.

This element is optional. If not set, the default value is the value of the ejb-name element.

clustered-lock-type

The type of distributed locking to be performed.

For EJB beans, only INHERIT and LOCK_NONE are valid.

For CDI beans, valid values are LOCK and INHERIT, which is equivalent to using LOCK_NONE.

Default value is INHERIT

whitelist-package

Used to whitelist packages on extreme class loading isolation. Whitelisted packages are taken into account by the server when scanning libraries.

For more information about how extreme class loading isolation works on Payara Server, see the Enhanced Classloading section.

enable-implicit-cdi

In a WAR file, it is possible to set the property bean-discovery-mode equal to none to turn off implicit scanning of the archive for bean defining annotations, as defined by the CDI 1.1 specification. The default value of this setting is defined as annotated in the specification, so the archive is scanned for any bean-defining annotations, which can cause unwanted side effects.

In the glassfish-application.xml deployment descriptor for an EAR file, the property enable-implicit-cdi can be set to false to achieve the same goal for all modules inside the EAR assembly. The default value is true, in line with the default value for WAR files.

If implicit CDI scanning causes problems for an EAR assembly, the value false will disable implicit CDI scanning for all CDI modules inside the EAR assembly:

<glassfish-application>
  <enable-implicit-cdi>false</enable-implicit-cdi>
</glassfish-application>

The default behavior of the admin console is for the Implicit CDI checkbox to be enabled, but this will not override the application configuration.

When implicit CDI is configured by using either the enable-implicit-cdi property in the glassfish-application.xml or the attribute bean-discovery-mode="none" from the beans.xml file in a WAR, the admin console checkbox *is always ignored*.

scanning-exclude and scanning-include

Modern WAR and EAR files very often include a number of 3rd party JARs. In situations where some JARs require CDI scanning and others may break if scanned, these can now be explicitly included or excluded from such component scanning.

Both the glassfish-application.xml and the glassfish-web.xml files support the following directives:

<scanning-exclude>*</scanning-exclude>
<scanning-include>ejb*</scanning-include>
<scanning-include>conflicting-web-library</scanning-include>

In the above example, all JARs will be excluded by default, then all JARs beginning with ejb will be scanned along with the JAR named conflicting-web-library.

container-initializer-enabled

This property configures whether to enable or disable the calling of ServletContainerInitializer component classes defined in JAR files bundled inside a WAR assembly.

For performance considerations, you can explicitly disable the servlet container initializer by setting the container-initializer-enabled element to false. This can help solve the deployment of web applications that can suffer from conflicts with a custom bootstrapping process.

The default value for this configuration element is true.

default-role-mapping

With this property, you can set whether to enable the default group to role mappings for your application’s security settings. This element is set up as a property element with a Boolean value attribute like this:

<property name="default-role-mapping" value="true">
  <description>Enable default group to role mapping</description>
</property>

Enabling the default group to role mappings will cause all named groups in the application’s linked security realm to be mapped to a role of the same name. This will save you the time of having to redefine the same roles and map them to the realm groups each time they are modified.

This will have the same effect as executing the following asadmin command:

asadmin set configs.config.server-config.security-service.activate-default-principal-to-role-mapping=true

Except its effect will only limit itself to the application instead of all applications deployed on the server. This setting is configured by default to true on the production-ready-domain

The default value of this property is false. This property can be set in the glassfish-web.xml, glassfish-ejb-jar.xml and glassfish-application.xml deployment descriptors.

In an EAR assembly, only the property set in the glassfish-application.xml will take effect and if set in the glassfish-web.xml and glassfish-ejb-jar.xml, it will be ignored. Setting this configuration property in any of these files will always take precedence over any setting configured on the server.

jaxrs-roles-allowed-enabled

Since Payara Server 4.1.2.181; 5.181

Payara Server and Micro since versions 4.1.2.181 and 5.181 support @RolesAllowed out of the box to secure JAX-RS resources.

In some cases this may clash with existing code that interprets the same annotation using custom code.

The out-of-the-box support of @RolesAllowed for JAX-RS resources can be switched off by setting the <jaxrs-roles-allowed-enabled> tag in WEB-INF/glassfish-web.xml of a war archive to false. E.g.

<jaxrs-roles-allowed-enabled>false</jaxrs-roles-allowed-enabled>

max-wait-time-in-millis

Since Payara Server 4.1.2.172

Payara Server has re-implemented a property of the glassfish-ejb-jar.xml descriptor that was available in GlassFish in versions prior to 4.0.

The bean-pool element allows users to specify controls on a per-EJB basis for pooled stateless EJBs. Payara Server has reintroduced max-wait-time-in-millis to govern what happens when the number of requests for an EJB exceeds the number of beans available in the pool.

A value of -1 disables the property and means that, when the pool is at maximum usage and another request is made, a new EJB instance is created immediately, with no upper bound.

A value of 0 means the server will wait indefinitely for an existing EJB instance to be freed.

A value between 1 and MAX_INTEGER means that the server will wait for the given amount of milliseconds for an EJB to be freed. Only after this max-wait-time-in-millis is exceeded will the server create a new instance of the requested EJB.

For more detail, see the Enhanced EJB configuration section.

webservice-default-login-config

Since Payara Server 4.1.2.173

When declaring a secured Web Service based on an EJB using the glassfish-ejb-jar.xml deployment descriptor, it’s necessary to define the login configuration (authentication method, security realm name, etc.) for each EJB Web Service that is secured inside the assembly. For example, if an application contains 2 EJB web services called EJBWS1 and EJBWS2, and they need to be secured using BASIC authentication against the file security realm, the following configuration would be needed:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE glassfish-ejb-jar PUBLIC "-//GlassFish.org//DTD GlassFish Application Server 3.1 EJB 3.1//EN" "http://glassfish.org/dtds/glassfish-ejb-jar_3_1-1.dtd">
<glassfish-ejb-jar>
  <ejb>
    <ejb-name>EJBWS1</ejb-name>
    <webservice-endpoint>
      <port-component-name>EJBWS1Port</port-component-name>
      <endpoint-address-uri>EJBWS1/EJBWebService</endpoint-address-uri>
      <login-config>
        <auth-method>BASIC</auth-method>
        <realm>file</realm>
      </login-config>
    </webservice-endpoint>
  </ejb>
  <ejb>
    <ejb-name>EJBWS2</ejb-name>
    <webservice-endpoint>
      <port-component-name>EJBWS2Port</port-component-name>
      <endpoint-address-uri>EJBWS2/EJBWebService</endpoint-address-uri>
      <login-config>
        <auth-method>BASIC</auth-method>
        <realm>file</realm>
      </login-config>
    </webservice-endpoint>
  </ejb>
</glassfish-ejb-jar>

Notice that the login-config element is repeated exactly like it is in the 2 EJB definitions. Not only that, but if these Web services are defined using annotations for each EJB component, then the JAX-WS information (Port Component Name, Endpoint Address, etc.) would be duplicated too, which is too cumbersome for cases when there are lots of EJB Web service definitions.

For this scenario, the webservice-default-login-config has been introduced to simplify this configuration. When this element is declared, the login configuration inside it will apply to all of the EJB defined Web Services by default.

The previous example can be simplified like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE glassfish-ejb-jar PUBLIC "-//GlassFish.org//DTD GlassFish Application Server 3.1 EJB 3.1//EN" "http://glassfish.org/dtds/glassfish-ejb-jar_3_1-1.dtd">
<glassfish-ejb-jar>
  <webservice-default-login-config>
      <auth-method>BASIC</auth-method>
      <realm>file</realm>
  </webservice-default-login-config>
</glassfish-ejb-jar>
All sub-elements tags of the login-config can be used inside this element.
If an EJB Web service definition needs a different login configuration from the default, just redefine it as shown in the example and it will override the default configuration.

jsp-config

Since Payara Server 5.181

The default value of the compiler property for this element has changed from 1.5 to 1.8, denoting a change from JDK5 to JDK8.

You can change this to another value by editing the jsp-config element in the glassfish-web.xml file.