jst j2ee
flexible project concepts
WTP LogoWTP Home

The goal of this document is to share some initial ideas that will help shape the Eclipse Web Tools (WTP) J2EE project application model and its implementation. We initially planned to pursue this effort as a formal requirements gathering and documentation process. But once we began analyzing the problem space it was clear that there is no common J2EE project model used within the J2EE development community. Stated another way, all current J2EE project models are ad hoc. At most, the J2EE application deployment model, defined in the J2EE specification, is the only common reference structure and it only specifies to the runtime archive form of valid J2EE applications. With that as our starting point, we concluded that rather than attempt to draft a conventional requirements document, it would be more beneficial to initiate a discussion of ideas among the key WTP participants that can serve as the catalyst for a J2EE application project requirements and subsequent architecture and implementation.


The contents of this document are representative of the future direction. However, some of this functionality described is representative of our current state.


There are several use cases described in the Use Case Scenario Powerpoint Slides. Where relevant, the relationship of the concepts described in this document and the scenario slides are highlighted.


A project is a type of resource which groups resources into buildable, reusable units - Java project resources are defined in terms of Java elements such as package fragments, types, methods and fields.


The scenario slides highlight the following types of use cases:

  • Simple Project (contains one module and one Deploy Scheme)

  • Simple Container Project (contains one or more modules, possibly multiple Deploy Schemes)

  • Application Project (application and modules contained in the same Simple Container project)

  • Application Project Variation (application in one Simple Container Project modules may be in other Simple Container projects)

  • Composed Modules (stay tuned (bum bum bum))


The J2EE module definitions build on the use case concepts. As discussed in the use cases, a module is a collection of files in a project. However, for the remainder of this document, the term abstract module will refer to an intangible concept (to be defined more explicitly later on). The abstract module concept represents the abstraction of a physical module in terms that can be understood programmatically. The specifics of how these projects are constructed is not important to the discussion of modules.


A resource is a abstraction which contains model elements. A resource set is a collection of related persistent resources. The resource set manages the collection of resources and produces notifications for changes to that collection. A project resource set is a resource set defined at the project level, meaning the project resource set manages the collection of resources for that project. There is only one project resource set per project, ensuring each resource is only loaded once within the workspace. Each resource contained in the project resource set has a relative URI , which is a partial URI with respect to or relative to the project. A WTP project resource set is defined in terms of module resources, which contain abstract module models (defined later).


A URI converter may be configured on a resource set to normalize relative URIs for comparison and to monitor access to the backing store. The resource set will use this converter to produce an input or output stream for a URI, during serialization or deserialization of a resource, and during a load to check for a resource URI match to one of its known resources.


An abstract module is a logical, abstracted, first-class model of a deployable artifact. The initial assumption will be that abstract modules must be contained within one project and thus use one project resource set. However, a project and the associated project resource set may contain more than one abstract module.


A J2EE abstract module is a collection of one or more components, organized by a standard layout, targeted for the same container upon deployment, and which can be archived conforming to the J2EE specification. Modules always contain a set of files, but all J2EE modules also contain specialized files called deployment descriptors . Deployment descriptors describe the contents of deployment units and configure components and applications to their environment. They also externalize the relationships between components, so those relationships can be managed without writing or changing program code. There are five core types of J2EE deployment descriptors, each of which corresponds to a type of J2EE deployment unit:

  • Application

  • Application Client

  • EJB

  • Web

  • Resource Adapter for Java Connector


Vendor-specific deployment descriptors may be defined for different Enterprise application containers to provide additional information.


Each deployment descriptor describes a set of contained objects which are represented through module models . The root abstract module model object for the deployment descriptor is the associated J2EE abstract module type object.

  • The Application is the root object for an EAR module.

  • The EJBJar is the root object for an EJB module.

  • The WebApp is the root object for a Web module

  • The ApplicationClient is the root object for an Application Client module.

  • The Connector is the root object for a JCA Connector module.


Before proceeding, it should be noted that there are two distinct metamodels in the tooling environment. First, J2EE abstract models allow framework clients to understand the J2EE-specific deployment descriptors and their third-party extensions. The tooling frameworks are built primarily to modify and update these models. There is also a separate model for understanding how modules and their contained resources can be constructed for deploying to server environments, which is referred to as ModuleCore .


ModuleCore can be used to acquire, create, and destroy abstract module contexts . An abstract module context is used to manage multiple abstract modules per project. In the first implementation, an abstract module context will not span multiple projects. Each abstract module context identifies a unique custom defined abstract module using a module handle (see Server Tooling), server target type (see Server Tooling), an edit model (to be discussed later).


Figure 1: Overview of ModuleCore, ModuleContext, and Abstract Module relationships.


Meanwhile, edit models provide a shared, reference counted, read/write controlled amalgamation of a related set of resources. Primarily, resources and Java working copies are wrapped by an Edit Model in order to represent a coherent and consistent view for clients. Managing these resources as a group, allows changes to be committed or rolled back as a consistent unit of work.


Typically, specialized types of edit models have aforementioned knowledge of their expected or required resources for a given type of abstracted module. Not surprisingly, clients may wish to add capabilities and additional known resources to existing edit model. The edit model will attempt to load these resources so that they may be managed with the existing, known resources.


Edit models are created via an extension which defines the edit model factory . The lifecycle of how edit models are created and destroyed will be covered in the API Concepts document.


Typically, J2EE components are built on a regular schedule (e.g. daily) and packaged as Enterprise Archives (EARs). Collaboration between teams and individual members is facilitated by these build artifacts which are used to back current development. These are referred to as target EARs . Developers set up their development environments so the components they are actively working on are loaded directly from a source repository and the other components are loaded from the Target EARs.


The use of target EARs is analogous to self-hosting in Eclipse. The idea is to only have abstract modules that are currently being developed in the workspace. All other dependencies will be loaded from a target EAR. Changing target EARs would simply be a matter of adjusting some abstract module property (just like PDE). Loading projects from the repository, or deleting them from the workspace would change where they were loaded from as well (also like PDE).


Rather than using target EARs, EAR files may be extracted to a structure which represents its contained abstract modules. The remaining non-module jar archives are called utility jars . Utility jars are regular jars which the various abstract modules can depend on. Utility jars may exist as jar files within the EAR abstract module which is useful when a developer is not currently working on the contents of the utility jar. All abstract module archives must (utility jars have the option) be handled in separate abstract modules.


An extracted module or utility jar module is simply a module containing the extracted contents of the archive. The benefit of using extracted modules is all the artifacts can be modified. This would be useful if a developer did not have access to the source repository. Typically, however, instead of using extracted modules, a developer would connect to a source repository. Jars within WARs can be extracted as modules within Eclipse projects (like utility jar modules) or can remain in the WAR in binary form.


Last updated 11/11/04