[[WildFly_and_WildFly_Preview]]
= WildFly and WildFly Preview
WildFly authors;
:revnumber: {version}
:revdate: {localdate}
:toc: macro
:toclevels: 3
:toc-title: WildFly and WildFly Preview
:doctype: book
:icons: font
:source-highlighter: coderay

ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]

// ifndef::ebook-format[:leveloffset: 1]

ifdef::basebackend-html[toc::[]]
:numbered:

= Different flavors of WildFly

Beginning with the WildFly 22 release, the WildFly project began producing two variants of
its landmark application server -- the standard "WildFly" variant and the newer "WildFly Preview".

The standard "WildFly" variant is the classic server that users have been familiar with for many
years now. It's a very mature server, with a lot of care taken to ensure new features are fully
realized and to limit the number of incompatible changes between releases.

WildFly Preview is a tech preview variant of the server. The goal of WildFly Preview is to give
the WildFly community a look at changes that are likely to appear in future releases of the standard
WildFly server. The aim is to get feedback on in-progress work, so it is more likely that features
will not be fully realized, and a greater number of incompatible changes may appear from release
to release. The amount of testing WildFly Preview undergoes will generally not be as high as the
standard WildFly variant.

The expectation is on any given release date, both standard WildFly and WildFly Preview will be released.

[WARNING]
====

A WildFly Preview release will have the same version number and suffix (Beta, Final, etc.) as the
main WildFly release, but regardless of the suffix, a WildFly Preview release should be treated
as a Technical Preview release.
====

== Getting WildFly Preview

The zip or tar.gz file for WildFly Preview is available at link:https://wildfly.org/downloads[https://wildfly.org/downloads]
right next to the main WildFly release files for the same version.

For wildfly-maven-plugin users and Galleon CLI users, we provide a Galleon feature pack for WildFly Preview. The
Galleon feature pack location for the feature pack is ``wildfly-preview@maven(org.jboss.universe:community-universe)`` and the Maven coordinate is ``org.wildlfly:wildfly-preview-feature-pack``.
This feature pack is the WildFly Preview analogue to main WildFly's ``wildfly@maven(org.jboss.universe:community-universe)`` (Maven coordinate ``org.wildfly:wildfly-galleon-pack``).

== WildFly Preview and Jakarta EE

Often, but not always, a key difference between standard WildFly and WildFly Preview is support for different versions of Jakarta EE. The WildFly project uses WildFly Preview to showcase full or partial support for new versions of Jakarta EE, including releases like EE 11 that are not yet released for general availability.

Note that formally certifying WildFly Preview as a compatible implementation of Jakarta EE is not a priority
for the WildFly project and may not happen at the time of a release, or ever. Users interested in formal EE
compliance of WildFly Preview should check the https://github.com/wildfly/certifications/tree/EE10[WildFly Certifications repository].

[[wildfly-preview-ee11]]
=== EE 11 Support in WildFly Preview

The 32 release introduced a significant inflection in how we are using WildFly Preview. Beginning with this release we are starting to use WildFly Preview to provide a look at what we're doing for Jakarta EE 11 support.  EE 11 is now GA, but standard WildFly won't support EE 11 before the WildFly 39 release, at earliest. But there are milestone, release candidate and final releases of many EE 11 specs and implementations available, so we decided to provide those in WildFly Preview. This means for a number of EE APIs, WildFly Preview no long provides an EE 10 compatible implementation.

However, for a number of specifications that are planning changes for EE 11 we are still offering the EE 10 variant. In future releases we'll shift those to the EE 11 variants.

The following table lists the various Jakarta technologies offered by WildFly Preview, along with information about which EE platform version the specification relates to. Note that a number of Jakarta specifications are unchanged between EE 10 and EE 11, while other EE technologies that WildFly offers are not part of EE 11. Jakarta Data is a new specification added in EE 11.

[cols=",,",options="header"]
|=======================================================================
|Jakarta EE Technology |Specification Version| EE Version

|Jakarta Activation| 2.1 |10 & 11

|Jakarta Annotations| 3.0 |11

|Jakarta Authentication| 3.1 |11

|Jakarta Authorization| 3.0 |11

|Jakarta Batch| 2.1 |10 & 11

|Jakarta Concurrency| 3.1 |11

|Jakarta Connectors| 2.1 |10 & 11

|Jakarta Contexts and Dependency Injection| 4.1 |11

|Jakarta Data
(_xref:Admin_Guide.adoc#Feature_stability_levels[preview stability] only_)| 1.0 |11 xref:note2[^2^]

|Jakarta Debugging Support for Other Languages| 2.0 |10 & 11

|Jakarta Dependency Injection| 2.0 |10 & 11

|Jakarta Enterprise Beans| 4.0 |10 & 11

|Jakarta Enterprise Web Services| 2.0 |10 xref:note1[^1^]

|Jakarta Expression Language| 6.0 |11

|Jakarta Faces| 4.1 |11

|Jakarta Interceptors| 2.2 |11

|Jakarta JSON Binding| 3.0 |10 & 11

|Jakarta JSON Processing| 2.1 |10 & 11

|Jakarta Mail| 2.1 |10 & 11

|Jakarta Messaging| 3.1 |10 & 11

| Jakarta MVC
(_xref:Admin_Guide.adoc#Feature_stability_levels[preview stability] only_)| 2.1| N/A xref:note3[^3^]

|Jakarta Pages| 3.1 |10

|Jakarta Persistence| 3.2 |11

|Jakarta RESTful Web Services| 4.0 |11

|Jakarta Security| 4.0 |11

|Jakarta Servlet| 6.1 |11

|Jakarta SOAP with Attachments| 3.0 |10 xref:note1[^1^]

|Jakarta Standard Tag Library| 3.0 |10 & 11

|Jakarta Transactions| 2.0 |10 & 11

|Jakarta Validation| 3.1 |11

|Jakarta WebSocket| 2.2 |11

|Jakarta XML Binding| 4.0 |10 xref:note1[^1^]

|Jakarta XML Web Services| 4.0 |10 xref:note1[^1^]
|=======================================================================

Notes:

. [[note1]]This Jakarta EE 10 technology is not part of EE 11 but is still provided by WildFly Preview.
. [[note2]]Jakarta Data is a new specification in EE 11.
. [[note3]]Jakarta MVC is an independent specification that is not part of the Jakarta EE Platform or the Web or Core Profile.

=== Jakarta Persistence 3.2+

In https://jakarta.ee/specifications/persistence/3.2/[Jakarta Persistence 3.2] and https://jakarta.ee/specifications/platform/11/[Jakarta EE 11+],
there is a requirement to produce the following types for CDI injection:

* `CriteriaBuilder`
* `EntityManager`
* `EntityManagerFactory`
* `Metamodel`
* `PersistenceUnitUtil`
* `SchemaManager`

WildFly Preview implements this requirement.

As noted in the https://jakarta.ee/specifications/platform/11/jakarta-platform-spec-11.0#a441[specification], the
`EntityManager` has a default scope of `@TransactionScoped`. The `EntityManagerFactory` has a scope of `@ApplicationScoped`.
All other types have a scope of `@Dependent`.

In the `persistence.xml`, each persistence unit can define their own scope and own qualifiers. It's important to note
if you choose to use CDI for your Jakarta Persistence application, you must create CDI qualifiers if you have more than
one persistence unit defined in your `persistence.xml` file. Without this you will likely see deployment failures due
to ambiguous beans.

.Example persistence.xml
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns="https://jakarta.ee/xml/ns/persistence"
             xsi:schemaLocation="https://jakarta.ee/xml/ns/persistence
        https://jakarta.ee/xml/ns/persistence/persistence_3_2.xsd"
             version="3.2">
    <persistence-unit name="auth">
        <jta-data-source>java:jboss/datasources/AuthDS</jta-data-source>
        <qualifier>org.wildfly.example.AuthDb</qualifier>
    </persistence-unit>
    <persistence-unit name="default">
        <jta-data-source>java:jboss/datasources/defaultDS</jta-data-source>
    </persistence-unit>
</persistence>
----

At most one persistence unit is allowed to have no qualifier defined in the `persistence.xml`. This will be the default
scoped `EntityManagerFactory` and `EntityManager`.

NOTE: If you already have CDI producers defined in your application to inject any of these types, they should continue
to work. However, you may be able to remove these producers and rely on the default behavior.

==== Special Notes

It should be noted that there is some ambiguity in the Jakarta EE 11 specification when defining beans for the
`EntityManagerFactory`. It's noted that bean name is given by the name of the persistence unit. In most cases this
should be fine. However, if multiple persistence units with the same name exist in a deployment,
we've opted to not give the bean a name. This will only affect you if you want to use Jakarta Expression Language to
get the `EntityManagerFactory` and you've got more than one persistence unit with the same name.

=== WildFly Preview Support for EE 8 Deployments

The APIs that WildFly Preview exposes to deployments are the EE 10 or 11 APIs, so all the classes and interfaces are in the
jakarta.* packages. But you _may_ be able to run an existing EE 8 application on WildFly Preview.

What we've done is we've added to the server's handling of _managed_ deployments a bytecode and text file transformation
process to convert EE 8 content into EE 9.  It bytecode transforms deployment jars to alter
references to EE 8 packages in the class file constant tables to change from javax.* to jakarta.*. The transformation
goes beyond simple package renames; a number of other known differences between EE 8 and EE 9 are handled. We owe a
great deal of thanks to the community behind the link:https://projects.eclipse.org/projects/technology.transformer[Eclipse Transformer]
project for their work on the underlying transformation tool.

As noted above, this handling is only applied to _managed_ deployments. A managed deployment is one where a management
client (the CLI, HAL console or the deployment scanner) presents deployment content to the server and the server makes
a copy of it in its internal deployment content repository. The content that gets installed into the runtime is that internal copy.
Unmanaged deployments that use EE 8 APIs will not work. We transform managed deployments when we copy the deployment
content into the internal content repo. For unmanaged deployments we use the original content file(s) the user provides,
and WildFly Preview won't modify those files as we don't regard them as being 'owned' by the server.

Note that the deployment transformation feature will not update the deployment to adapt to any API differences between
Jakarta EE 9 and EE 10 or later. It only covers the javax to jakarta name changes that came with EE 9.

In the long run it's better for users if they either convert their application source to EE 10 or 11 APIs, or use build-time
tooling that the Jakarta ecosystem provides to do transformation at build time.  But some
applications just can't be changed, so the server-side solution WildFly Preview provides can handle those cases.

This deployment transformation feature will be removed from WildFly Preview in a future release. However, it is likely
that the WildFly developers will offer a separate Galleon feature pack that can be used to add this behavior into both
standard WildFly and WildFly Preview.

== BOMs

WildFly provides BOMs that users can use when developing applications. We provide different BOMs for standard WildFly and WildFly Preview, with different Maven artifact ids.

We provide the following BOMs for developing applications to deploy in the server:

[cols=",,,",options="header"]
|=======================================================================
|BOM| Maven GroupId |Standard WildFly ArtifactId| WildFly Preview ArtifactId
|EE| `org.wildfly.bom` |`wildfly-ee`|`wildfly-ee-preview`
|EE With Tools| `org.wildfly.bom` |`wildfly-ee-with-tools`|`wildfly-ee-preview-with-tools`
|Expansion| `org.wildfly.bom` |`wildfly-expansion`|`wildfly-expansion-preview`
|Expansion With Tools| `org.wildfly.bom` |`wildfly-expansion-with-tools`|`wildfly-expansion-preview-with-tools`
|=======================================================================

The 'EE' BOMs cover technologies that in standard WildFly are provisioned when the `wildfly-ee` Galleon feature pack is used. (All standard WildFly installations use this feature pack).

The 'Expansion' BOMs cover additional technologies that in standard WildFly are only provisioned when the `wildfly` Galleon feature pack is used. (Most standard WildFly installations would use this feature pack, including the zips/tars that are available link:https://wildfly.org/downloads[for download].) This includes things like MicroProfile, Micrometer and Open Telemetry.

The 'With Tools' variants incorporate additional dependencies for tools that may be helpful when developing or testing applications.

For standard WildFly we also provide BOMs for developing applications that act as various kinds of external clients to a WildFly server. There are no WildFly Preview variants of these.

[cols=",,,",options="header"]
|=======================================================================
|BOM| Maven GroupId |Standard WildFly ArtifactId| WildFly Preview ArtifactId
|Jakarta Enterprise Beans Client| `org.wildfly` |`wildfly-ejb-client-bom`|N/A
|Jakarta Messaging Client| `org.wildfly` |`wildfly-jms-client-bom`|N/A
|Jakarta XML Web Services Client| `org.wildfly` |`wildfly-jaxws-client-bom`|N/A
|=======================================================================

== Other Differences in WildFly Preview

WildFly Preview is intended to help get community exposure for other changes we plan to
make in the server. Here are the key differences between standard WildFly and WildFly Preview:

* WildFly Preview is not a Jakarta EE 10 compatible implementation. It also is not a MicroProfile platform compatible
implementation. Most EE 10 and MicroProfile applications are expected to run well on WildFly Preview, but it is not
certified compatible.
* The standard configuration files do not configure an embedded messaging broker. Instead, they configure the
link:Admin_Guide{outfilesuffix}#Messaging[`messaging-activemq` subsystem] to provide connections to a remote ActiveMQ Artemis broker. (It's a task for the user to
run such a broker or to update the config to integrate with a different broker.) We want WildFly out-of-the-box to be
more of a cloud native appserver and having an embedded messaging broker in the default configuration is not cloud native.
A WildFly container in the cloud running an embedded broker is not scalable, as multiple broker instances need separate
configuration to act as a primary or backup. An embedded messaging broker also has more advanced persistent storage
requirements than a server primarily dedicated to handling HTTP requests would have. Note however that running an
embedded broker is still supported. We've added to the $WILDFLY_HOME/docs/examples/configs folder an example
``standalone-activemq-embedded.xml`` configuration showing its use.
* WildFly Preview provides the link:Admin_Guide{outfilesuffix}#Micrometer_Metrics[`micrometer` subsystem] in its out-of-the-box `standalone.xml`, `standalone-ha.xml`, `standalone-full.xml` and `standalone-full-ha.xml` configuration files, while standard WildFly instead provides the basic link:Admin_Guide{outfilesuffix}#MicroProfile_Metrics_SmallRye[`metrics` subsystem].
* WildFly Preview includes the `jakarta-data` subsystem in its out-of-the-box `standalone.xml`, `standalone-ha.xml`, `standalone-full.xml`, `standalone-full-ha.xml`, `standalone-microprofile.xml` and `standalone-microprofile-ha.xml` configuration files. It also include the subsystem in the out-of-the-box `domain.xml` configuration file's `default`, `ha`, `full` and `full-ha` profiles. Standard WildFly includes support for the `jakarta-data` subsystem but does not include it in any out-of-the-box-configuration file. link:https://jakarta.ee/specifications/data/[Jakarta Data] is a new Jakarta specification that is part of Jakarta EE 11.
* WildFly Preview includes a new xref:Admin_Guide.adoc#Feature_stability_levels[`preview` stability] `org.wildfly.extension.vertx` extension and its `vertx` subsystem, along with a new `vertx` Galleon layer so you can provision it in a slimmed server. This subsystem can be used to configure the Vert.x instance used by our OpenTelemetry integration.
* The Hibernate ORM integration used by the link:Developer_Guide{outfilesuffix}#JPA_Reference_Guide[JPA subsystem's] Hibernate Search feature supports using outbox polling as a coordination strategy for automatic indexing.


