J2EE Server API changes

This document describes the J2EE Server API changes made on the 'ddbean_removal' branch.


The initial motivation for the J2EE Server API changes is migration to Retouche, a new NetBeans Java infrastructure. The new Java infrastructure does not supply the old deployment descriptor model with fine-grained change notification anymore. Thus, a new Merged deployment descriptor model infrastructure is being created instead.

Since the architecture of the new Merged deployment descriptor model is essentially different from the old deployment descriptor model infrastructure, the model can no longer be wrapped in the JSR-88 DDBean wrapper, which was the basis of all server-specific deployment configuration APIs. Therefore, the part of the J2EE Server API regarding the deployment configuration had to be redesigned.

Because the redesign already introduced number of incompatible changes, we used this opportunity to fix couple of other API issues requiring incompatible changes. Firstly, the server plug-in part of the API was split into API and SPI. So far, there was no clear distinction between API and SPI and it was not obvious what a server plug-in writer is required to implement. Secondly, throws ConfigurationException clause was added to every server-specific configuration-related method. It should allow to inform a client about a problem which might have occurred while reading or writing to server-specific configuration files.

Because the mentioned API changes will break a lot of J2EE Server clients, we tried to avoid any big design changes to minimize required amount of work for fixing the clients.

DeployableObject replaced with J2eeModule

JSR-88 DeployableObject was replaced with J2eeModule. For example, all occurrences of DeployableObject in IncrementalDeployment interface were simply replaced with J2eeModule.

J2eeModule has the same purpose as DeployableObject; it represents a server-neutral description of a J2EE module. Additionally, it contains some extra information, which could not have been added to the JSR-88 DeployableObject interface, like the location of resources directory, the ability to listen to J2EE module version changes, the location of server-specific deployment descriptor files within the model, etc. This extra information was scattered in various places, where it doesn't belong to.

It is important to notice that J2eeModule interface had already existed before this API redesign. It was used by module providers (e.g. J2EE projects) to describe a J2EE module to J2EE Server and it was completely hidden from server plug-ins.

From the API point, the biggest difference view between the the old and new version of the J2eeModule is that the new version is a final class while the old version was an interface. To create an instance of the J2eeModule class, an instance of the J2eeModuleImplementation has to be created first and then passed to J2eeModuleFactory. Advantage of J2eeModule being a final class is that it is extensible in a compatible fashion.

The above description about replacement of DeployableObject with J2eeModule applies analogically for replacement of J2eeApplicationObject with J2eeApplication. The predecessor of J2eeApplication was J2eeModuleContainer.

J2eeModuleProvider is still used to provide a J2eeModule instance. J2eeAppProvider was renamed to J2eeApplicationProvider for the consistency sake, yet its purpose remains the same.

DeploymentConfiguration replaced with ModuleConfiguration

JSR-88 DeploymentConfiguration interface, which represents a server-specific deployment configuration, was replaced with ModuleConfiguration. Again, you may notice that for example in the IncrementalDeployment interface one for one replacement of all of the DeploymentConfiguration occurrences with ModuleConfiguration.

All it needs to be done now to create an instance of ModuleConfiguration is to use ModuleConfigurationFactory. In order to create a DeploymentConfiguration instance, however, it was needed to call DeploymentManager.createConfiguration() factory method and then to initialize the created instance with the ConfigurationSupport.initConfiguration() call, to provide the DeploymentConfiguration with some extra info.

Addition of FileJ2eeModuleQuery

In some cases the server plug-in needs to find out part of which J2EE module a given server-specific configuration file is and it may also need to get server-neutral description of the module in such case. There was an API ConfigurationSupport.requestCreateConfiguration() which allowed to request creation and initialization of DeploymentConfiguration of a J2EE Module for a particular server-specific configuration file, but it was really awkward to use.

A new FileJ2eeModuleQuery class replaces the old hack kind of API and allows to comfortably get a J2eeModule for a given server-specific configuration file, which is exactly what the serve plug-in needs.


In order to eliminate J2EE Server configuration related APIs dependency on JSR-88 completely, javax.enterprise.deploy.spi.exceptions.ConfigurationException was replaced with org.netbeans.modules.j2ee.deployment.common.api.ConfigurationException.

Changes in Common and Devmodules APIs

Classes layout changes

org.netbeans.modules.j2ee.deployment.common.api.ConfigurationException N
org.netbeans.modules.j2ee.deployment.common.api.SourceFileMap M

org.netbeans.modules.j2ee.deployment.devmodules.api.J2eeApplication N
org.netbeans.modules.j2ee.deployment.devmodules.api.J2eeModule M
org.netbeans.modules.j2ee.deployment.devmodules.api.J2eeModuleContainer R

org.netbeans.modules.j2ee.deployment.devmodules.spi.J2eeApplicationImplementation N
org.netbeans.modules.j2ee.deployment.devmodules.spi.J2eeApplicationProvider N
org.netbeans.modules.j2ee.deployment.devmodules.spi.J2eeAppProvider R
org.netbeans.modules.j2ee.deployment.devmodules.spi.J2eeModuleFactory N
org.netbeans.modules.j2ee.deployment.devmodules.spi.J2eeModuleImplementation N
org.netbeans.modules.j2ee.deployment.devmodules.spi.J2eeModuleProvider M


R - The class was removed
N - New class was added 
M - The class was modified

ConfigurationSupport split-up

The org.netbeans.modules.j2ee.deployment.plugins.api.ConfigurationSupport class was some kind of J2EE Server extension of the JSR-88 DeploymentConfiguration class. The abstract class was now spit up into several Configuration interfaces to make the API better extensible in a compatible way. If a new functionality will be needed a new interface will be introduced, without breaking anyone.

Another good reason for the split-up was to logically separate the interfaces. Some of the interfaces are relevant only to certain J2EE module types and therefore implementing those interfaces should be optional. After the split-up, the Tomcat (a pure web container) plug-in for example, will not have to implement EJB related interfaces anymore.

Below is a list of all the new Configuration interfaces. The DeploymentPlanConfiguration interface is an exception here, since it does not replaces any part of the ConfigurationSupport abstract class but a part of the DeploymentConfiguration class.


API split-up into API and SPI

All the SPI interfaces from the org.netbeans.modules.j2ee.deployment.plugins.api package were moved to a new org.netbeans.modules.j2ee.deployment.plugins.spi package. Below you can see also a new org.netbeans.modules.j2ee.deployment.plugins.spi.config package, where all the server-specific deployment configuration related SPI interfaces should be placed.

Classes layout changes

org.netbeans.modules.j2ee.deployment.plugins.api.ConfigurationSupport R
org.netbeans.modules.j2ee.deployment.plugins.api.FileJ2eeModuleQuery N

org.netbeans.modules.j2ee.deployment.plugins.spi.DatasourceManager M
org.netbeans.modules.j2ee.deployment.plugins.spi.IncrementalDeployment M

org.netbeans.modules.j2ee.deployment.plugins.spi.config.ContextRootConfiguration N
org.netbeans.modules.j2ee.deployment.plugins.spi.config.DatasourceConfiguration N
org.netbeans.modules.j2ee.deployment.plugins.spi.config.DeploymentPlanConfiguration N
org.netbeans.modules.j2ee.deployment.plugins.spi.config.EjbResourceConfiguration N
org.netbeans.modules.j2ee.deployment.plugins.spi.config.MappingConfiguration N
org.netbeans.modules.j2ee.deployment.plugins.spi.config.ModuleConfigurationFactory N
org.netbeans.modules.j2ee.deployment.plugins.spi.config.ModuleConfiguration N


R - The class was removed
N - New class was added 
M - The class was modified
Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo