Skip to content

FISH-10759 Deprecate Deployment Descriptors (E5) #724

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Viii3 wants to merge 2 commits into
base: main-5
Choose a base branch
from
Open

FISH-10759 Deprecate Deployment Descriptors (E5) #724

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f5808d6
FISH-10759 Add deprecation notice for glassfish-web.xml
Viii3 Feb 12, 2026
67b020a
FISH-10759 Add deprecation notice to glassfish-resources.xml
Viii3 Feb 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions ...ion/Ecosystem/Connector Suites/Arquillian Containers/Payara Server Managed.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,6 +143,9 @@ If the component is packaged as a regular archive, do not set this option.
The context root that will be used to run the tests is also retrieved automatically from the DAS server. If the deployed application does have a `sun-web.xml`, `glassfish-web.xml` or `payara-web.xml` deployment descriptor, the container will use the name of your deployment without the extension as context root. +
The same rule is applied for enterprise applications if there is no `application.xml` file. The JAR test-deployments are treated as a web application.

IMPORTANT: glassfish-web.xml and sun-web.xml are deprecated and support will be removed in Payara 7.
It is recommended to use payara-web.xml instead.

[[examples]]
== Examples

Expand Down
3 changes: 3 additions & 0 deletions ...tion/Ecosystem/Connector Suites/Arquillian Containers/Payara Server Remote.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,9 @@ If the component is packaged as a regular archive, do not set this option.
The context root that will be used to run the tests is also retrieved automatically from the DAS server. If the deployed application does have a `sun-web.xml`, `glassfish-web.xml` or `payara-web.xml` deployment descriptor, the container will use the name of your deployment without the extension as context root. +
The same rule is applied for enterprise applications if there is no `application.xml` file. The JAR test-deployments are treated as a web application.

IMPORTANT: glassfish-web.xml and sun-web.xml are deprecated and support will be removed in Payara 7.
It is recommended to use payara-web.xml instead.

[[examples]]
== Examples

Expand Down
5 changes: 4 additions & 1 deletion docs/modules/ROOT/pages/Technical Documentation/MicroProfile/JWT.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -249,7 +249,10 @@ With `base` being the context where the application is deployed, e.g. `http://ex

== Switching off @RolesAllowed support in JAX-RS

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` to `false`. For more information see the documentation for the xref:/Technical Documentation/Payara Server Documentation/Server Configuration And Management/Application Deployment/Descriptor Elements.adoc#jaxrs-roles-allowed-enabled[jaxrs-roles-allowed-enabled] element.
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/payara-web.xml` or `WEB-INF/glassfish-web.xml` to `false`. For more information see the documentation for the xref:/Technical Documentation/Payara Server Documentation/Server Configuration And Management/Application Deployment/Descriptor Elements.adoc#jaxrs-roles-allowed-enabled[jaxrs-roles-allowed-enabled] element.

IMPORTANT: glassfish-web.xml is deprecated and support will be removed in Payara 7.
It is recommended to use payara-web.xml instead.

== Full examples

Expand Down
5 changes: 4 additions & 1 deletion ...icro Configuration and Management/Micro Management/Configuring An Instance.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -198,7 +198,10 @@ http://localhost:9080/test
--------------------------

Currently, this is *always* the case; including when a context root is specified
in a `glassfish-web.xml` deployment descriptor.
in a `payara-web.xml` / `glassfish-web.xml` deployment descriptor.

IMPORTANT: glassfish-web.xml is deprecated and support will be removed in Payara 7.
It is recommended to use payara-web.xml instead.

If the WAR file is renamed to `ROOT.war` and packaged as an Uber JAR, it will
be deployed to the root context:
Expand Down
10 changes: 8 additions & 2 deletions ...Configuration And Management/Application Deployment/Deployment Descriptors.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,10 @@ The `payara-web.xml` deployment descriptor can be used instead of `glassfish-web
<!DOCTYPE payara-web-app PUBLIC "-//Payara.fish//DTD Payara Server 4 Servlet 3.0//EN" "{payaraWebDtd}">
----

The `payara-resources.xml` can be used instead of `glassfish-resources.xml`. Its structure is exactly the same, and the schema is referenced by the following declaration:
IMPORTANT: glassfish-web.xml is deprecated and support will be removed in Payara 7.
It is recommended to use payara-web.xml instead.

The `payara-resources.xml` should be used instead of the deprecated`glassfish-resources.xml`. Its structure is exactly the same, and the schema is referenced by the following declaration:

[source,xml,subs=attributes+]
----
Expand All @@ -40,6 +43,9 @@ The following elements are supported in Payara Server on top of elements support
[[glassfish-web.xml]]
== _glassfish-web.xml_ and _payara-web.xml_

IMPORTANT: glassfish-web.xml is deprecated and support will be removed in Payara 7.
It is recommended to use payara-web.xml instead.

* `container-initialized-enabled`
* `default-role-mapping` (_property_)
* `jaxrs-roles-allowed-enabled`
Expand Down Expand Up @@ -68,7 +74,7 @@ The following elements are supported in Payara Server on top of elements support
[[payara-resources.xml]]
== _payara-resources.xml_

The structure of the payara-resources.xml is the same as glassfish-resources.xml with the following additional configurations:
The structure of the payara-resources.xml is the same as glassfish-resources.xml (deprecated) with the following additional configurations:

* `snapshot` (_property of transaction isolation, this isolation level is only supported by Microsoft SQL Server_)
* `log-jdbc-calls` (_attribute of `jdbc-connection-pool`_)
Expand Down
14 changes: 10 additions & 4 deletions ...er Configuration And Management/Application Deployment/Descriptor Elements.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ IMPORTANT: When implicit CDI is configured by using either the `enable-implicit-

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:
Both the `glassfish-application.xml` and the `payara-web.xml` / `glassfish-web.xml` (deprecated) files support the following directives:

[source, xml]
----
Expand Down Expand Up @@ -122,9 +122,12 @@ asadmin set configs.config.server-config.security-service.activate-default-princ

Except its effect will only limit itself to the application instead of all applications deployed on the server.

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.
The default value of this property is `false`. This property can be set in the `payara-web.xml` / `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.
In an EAR assembly, only the property set in the `glassfish-application.xml` will take effect and if set in the `payara-web.xml` / `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.

IMPORTANT: glassfish-web.xml is deprecated and support will be removed in Payara 7.
It is recommended to use payara-web.xml instead.

[[jaxrs-roles-allowed-enabled]]
== `jaxrs-roles-allowed-enabled`
Expand Down Expand Up @@ -217,7 +220,10 @@ IMPORTANT: If an EJB Web service definition needs a different login configuratio

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.
You can change this to another value by editing the `jsp-config` element in the `payara-web.xml` / `glassfish-web.xml` file.

IMPORTANT: glassfish-web.xml is deprecated and support will be removed in Payara 7.
It is recommended to use payara-web.xml instead.

[[cache-ttl]]
== `cacheTTL`
Expand Down
25 changes: 16 additions & 9 deletions ...ion/Server Configuration And Management/Classloading/Enhanced Classloading.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,17 +44,21 @@ It's possible to disable class loading delegation directly at the application le
[[on-war-applications]]
==== On WAR Applications

For *WAR* applications, you can include `<class-loader delegate="false"/>` element in the `glassfish-web.xml` deployment descriptor. Here's an example:
For *WAR* applications, you can include `<class-loader delegate="false"/>` element in the `payara-web.xml` / `glassfish-web.xml` deployment descriptor. Here's an example:

[source, xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE glassfish-web-app PUBLIC "-//GlassFish.org//DTD GlassFish Application Server 3.1 Servlet 3.0//EN" "http://glassfish.org/dtds/glassfish-web-app_3_0-1.dtd">
<glassfish-web-app error-url="">
<!DOCTYPE payara-web-app PUBLIC "-//Payara.fish//DTD Payara Server 4 Servlet 3.0//EN"
"https://docs.payara.fish/schemas/payara-web-app_4.dtd">
<payara-web-app error-url="">
<class-loader delegate="false"/>
</glassfish-web-app>
</payara-web-app>
----

IMPORTANT: glassfish-web.xml is deprecated and support will be removed in Payara 7.
It is recommended to use payara-web.xml instead.

With this, all libraries included on the `WEB-INF/lib/` directory will take precedence.

[[on-ear-applications]]
Expand All @@ -77,7 +81,7 @@ With this, all libraries included on the EAR's `lib/` directory will take preced
== Use other JSF implementation

In order to make the server use the bundled JSF implementation within the application, you need to set an additional configuration parameter; class loading delegation alone is not enough.
You need to indicate within the _payara-web.xml_ (or glassfish-web.xml) file that the server should use the bundled JSF implementation as follows:
You need to indicate within the _payara-web.xml_ (or glassfish-web.xml (deprecated)) file that the server should use the bundled JSF implementation as follows:

[source, xml]
----
Expand All @@ -98,19 +102,22 @@ IMPORTANT: If using an EAR you must bundle the JSF implementation within the emb

It's possible to configure an extreme isolation level on the class loading delegation for deployed applications. With this extreme isolation behavior, a deployed application can force the server to load only classes and resources from libraries included on Payara Server that belong to *whitelisted packages* defined on its deployment descriptors.

To configure whitelist packaging you can use the `<whitelist-package>` element on the _glassfish-web.xml_ (WAR artifacts) or the _glassfish-application.xml_ (EAR artifacts). This element can be included multiple times to whitelist multiple packages. Here is an example of whitelisting both the *Google Guava*, *Jackson* and *Faces Config* packages for a WAR application:
To configure whitelist packaging you can use the `<whitelist-package>` element on the `payara-web.xml` / `glassfish-web.xml` (WAR artifacts) or the `glassfish-application.xml` (EAR artifacts). This element can be included multiple times to whitelist multiple packages. Here is an example of whitelisting both the *Google Guava*, *Jackson* and *Faces Config* packages for a WAR application:

[source, xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE glassfish-web-app PUBLIC "-//GlassFish.org//DTD GlassFish Application Server 3.1 Servlet 3.0//EN" "http://glassfish.org/dtds/glassfish-web-app_3_0-1.dtd">
<glassfish-web-app error-url="">
<!DOCTYPE payara-web-app PUBLIC "-//Payara.fish//DTD Payara Server 4 Servlet 3.0//EN" "https://docs.payara.fish/schemas/payara-web-app_4.dtd">
<payara-web-app error-url="">
<whitelist-package>com.google.guava</whitelist-package>
<whitelist-package>com.fasterxml.jackson</whitelist-package>
<whitelist-package>com.sun.faces.spi.FacesConfigResourceProvider</whitelist-package>
</glassfish-web-app>
</payara-web-app>
----

IMPORTANT: glassfish-web.xml is deprecated and support will be removed in Payara 7.
It is recommended to use payara-web.xml instead.

The whitelist syntax is simple: Define the name of the package which contains the classes or resources in question. For example writing `com.google` would whitelist all Google libraries included on the server, while writing `com.google.guava` would only whitelist the Google Guava library instead.

IMPORTANT: To enable this extreme isolation behavior, at least one `whitelist-package` element must be defined in the appropriate descriptor.
Expand Down
4 changes: 2 additions & 2 deletions ... Management/Configuration Options/Variable Substitution/Usage of Variables.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,10 @@ Variable references can be used inside text values in the following configuratio
Variable references can be used inside text values also in the following places within deployed applications and modules:

* Package descriptors:
** web.xml / glassfish-web.xml
** web.xml / payara-web.xml / glassfish-web.xml (deprecated)
** ejb-jar.xml / glassfish-ejb-jar.xml
** application.xml / glassfish-application.xml
** glassfish-resources.xml
** payara-resources.xml / glassfish-resources.xml (deprecated)
* Framework descriptors:
** persistence.xml
** faces-config.xml
Expand Down
10 changes: 7 additions & 3 deletions ...mentation/Server Configuration And Management/HTTP Service/Virtual Servers.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -191,12 +191,16 @@ Defines additional properties for the configuration of a virtual server.
| 300
| *sso-reap-interval-seconds* | The number of seconds between purges of SSO records. | 60
| *setCacheControl* | Comma separated list of Cache-Control response directives (See section 14.9 of: https://www.ietf.org/rfc/rfc2616.txt). | none
| *allowLinking* a| If set to true, resources that are symbolic links will be served for all applications deployed to this virtual server. Can be overridden for an individual application in the glassfish-web.xml with:
| *allowLinking* a| If set to true, resources that are symbolic links will be served for all applications deployed to this virtual server. Can be overridden for an individual application in the payara-web.xml / glassfish-web.xml with:
----
<glassfish-web-app>
<payara-web-app>
<property name="allowLinking" value="false" />
</glassfish-web-app>
</payara-web-app>
----

IMPORTANT: glassfish-web.xml is deprecated and support will be removed in Payara 7.
It is recommended to use payara-web.xml instead.

====
Note: Setting this property to `true` on Windows systems exposes JSP source code.
====
Expand Down