Web Tools Platform Release 3.0 Requirements/JavaCPvsJavaEEModDeps

Java Classpath vs Java EE Module Dependencies

One of the major usability goals for the Java EE component during WTP 3.0 will be a rationalization of the Java classpath and Java EE module dependencies. This work is covered under the following bugzilla: https://bugs.eclipse.org/bugs/show_bug.cgi?id=116856. This wiki page contains initial design ideas for how such a rationalization might be implemented during the 3.0 timeframe.
A constant source of user confusion has been the distinction between a Java EE module project's classpath and the published/exported structure of that module. In this context, the Java classpath and J2EE module dependencies currently support overlapping (and often conflicting/confusing) sets of metadata and UI functionality. Specific points of confusion:

• Some aspects of the classpath need to be managed directly using the Java Build Path UI (e.g. Java src paths). The necessary component file settings then happen automatically.
• Most classpath entry types (project, library, etc.) cannot be directly manipulated via the Java Build Path UI if those entries need to be reflected in the module's published/exported structure. Instead, the dependency must first be added via the J2EE Module Dependency UI (and persisted via a component file entry or MANIFEST.MF classpath) and exposed to the Java classpath using the WTP "Ear Libraries" classpath container (or "Web App Libraries" cp container).
• Some types of classpath entries could not be exposed for publish/export at all until very recently (e.g. classpath containers, library dependencies of utility projects).
• Some classpath entries can now be handled directly via the Java Build Path (library entries, cp containers) but the user must go to the J2EE Module Dependencies UI to enable the WTP-specific attribute before the entry will be included in the published/exported content of the module.
• The J2EE Module Dependencies UI is used on both projects with the Java Nature (i.e. all module projects except static web) and EAR projects which lack the Java Nature. The fact that settings on a non-Java EAR project impact the contents of the "Ear Libraries" classpath container on distinct projects (which themselves have no Java classpath dependency on the EAR project) is not necessarily intuitive.

Overall goals:

• Manage the classpath using the JDT tooling and have those classpath entries automatically contribute to the assembled module structure (add publish/export support for both project and class folder cp entries). Use the WTP tooling to customize how the classpath impacts the structure of the assembled module.
• Simplify the current "J2EE Module Dependencies" UI (for EAR, Dynamic Web and non-Web module projects).
• Support backward compatibilty with existing 2.0-level functionality and metadata.
• Optional upgrade of non-classpath dependencies contained in 2.0 module projects
• (Nice to have) For all Java EE Module project types (but esp. EAR and Dynamic Web), add ability to visualize structure/content of assembled module.

The following sections outline the design details for EARs, module projects in general and dynamic web projects.

EAR Projects

• For EAR projects, assembly information must still be stored in the component file and specified fully using a Java EE Module Dependencies UI.
• The design and functionality of this UI should be simplified
• The EAR-level UI must support:
  • Specification of child module projects
  • Specification of external archives that will not be referenced on the classpath of any other child module project.
  • Other features should be removed/simplified (see table below)
• (Desirable) Support for visualizing the structure/content of the assembled EAR (see task below).

EAR Project Dependency Management Tasks

Task	Current UI/Metadata	Proposed UI/Metadata
Create dependency between EAR project and child module project	J2EE Mod Dep UI; component file	Simplified "EAR Modules" UI; component file
Create dependency between EAR project and plain Java project (without changing into utility)	not possible now	Simplified "EAR Modules" UI; component file
Create dependency between EAR project and external/Workspace archive	J2EE Mod Dep UI, two separate commands; component file	Simplified "EAR Modules" UI (one button and then pick between external vs Workspace?); component file (if on classpath of child module, no need for EAR-level setting)
Create dependency between EAR project and cp variable	J2EE Mod Dep UI; component file	Existing support is needed for backward compat, however, it would be ideal to remove this from the EAR UI and just require the addition of cp var entry to each child project as desired (is there a need for unreferenced cp variables archives in EAR?). If really needed, could combine into single archive dependency button with "variable" another location option.
Auto dependency between EAR project and archives in EarContent	visible in J2EE Mod Dep UI; not stored explicitly	Could still show in UI view of assembled EAR; no need for explicit storage
See contents/structure of assembled EAR	somewhat supported by J2EE Mod Dep UI (does show child mod cp entries) but structure not clear	Should include view (tree perhaps) of assembled EAR indicating all contents and origin (Workspace/external)

Module Projects

• Except for backward compatibility support (see below), the project classpath will not be influenced by the contents of the Manifest classpath or component file. This means that the "Ear Libraries" cp container will not be added to new 3.0 module projects.
• Except for backward compatiblity support (see below), the structure of assembled EE projects with the Java nature will be controlled only by the project classpath (selection of the parent EAR will not be required). The set of entries that contribute to the assembled module will be determined as follows:
  • The existing extension point will be used to filter out certain classpath containers (e.g. JRE, server runtime libraries, etc.)
  • The existing WTP "dependency" and "non-dependency" classpath entry attributes will be used to specify whether an entry should or should not contribute to the assembled structure. Project and class folder cp entries will now be supported as well.
  • A project-level boolean property (e.g. "publish-classpath-by-default", set in the component file) will be used to control the behavior for classpath entries that lack either the "dependency" or "non-dependency" attribute. If set to true, all classpath entries that do not have a WTP attribute (minus auto-filtered cp containers) will be assumed to have the "dependency" attribute. If set to false, all classpath entries lacking a WTP attribute will be assumed to have the "non-dependency" attribute.
  • The "publish-classpath-by-default" property will be specified on all new module projects created using WTP 3.0 (the default value will be "true"). The value will be modifiable post-creation using a check box on the new Java EE Modules Dependencies UI prop page.
  • If the "publish-classpath-by-default" property has not be specified on a project, classpath entries lacking the WTP attribute will be assumed to have the "non-dependency" attribute specified. This is the current functionality so covers the backward compatibility case.
  • Users can then customized these default settings using the Java EE Module Dependencies UI to include or exclude a specific classpath entry (this will add/remove the "dependency" or "non-dependency" WTP attribute to/from the classpath entry as appropriate). This UI will not require selection of the parent EAR.
• Backward compatibility support:
  • The old non-classpath dependencies from 2.0 projects (manifest cp and component file) will continue to be returned as dependencies via the virtual component API.
  • If a module project contains the "Ear Libraries" classpath container, it is assumed to have old non-classpath 2.0 dependencies and a UI command will be displayed to "upgrade" the project to the new classpath-based model. This upgrade action will do the following:
    • Remove the "Ear Libraries" cp container
    • Add explicit classpath entries (with the "dependency" attribute) for all dependencies previously exposed via the "Ear Libraries" cp container.
    • Remove dependency entries from the MANIFEST.MF classpath.
  • Read-only display of the old dependencies will can still be supported via the new "Java EE Module Dependencies" UI by displaying the resolved contents of the "Ear Libraries" classpath container (actual publish/export logic will continue to ignore this cp container since the exposed items are already referenced at the EAR level and have Manifest classpath references)
  • (Nice to have) Write access to old dependencies: could enable this via a UI associated with the "Ear Libraries" cp container (would be a UI similar to the existing UI)

Module Project Dependency Management Tasks

Task	Current UI/Metadata	Proposed UI/Metadata
Control whether classpath entries are published/exported by default or excluded by default	always excludeed by default	new "Java EE Module Dep" UI (potentially new project wizard), component file
Create Manifest classpath dependency on module project associated with parent EAR	J2EE Mod Dep UI; MANIFEST.MF	JDT UI to create project cp entry, new "Java EE Module Dep" UI to add/remove "dependency"/"non-dependency" attribute on project cp entry (if necessary)
Create Manifest classpath dependency on module project not associated with parent EAR (don't require conversion to utility if plain Java)	not possible	JDT UI to create project cp entry, new "Java EE Module Dep" UI to add/remove "dependency"/"non-dependency" attribute on project cp entry (if necessary)
Create Manifest classpath dependency on archive associated with parent EAR	J2EE Mod Dep UI; MANIFEST.MF	JDT UI to create lib cp entry, new "Java EE Module Dep" UI to add/remove "dependency"/"non-dependency" attribute on project cp entry (if necessary)
Create Manifest classpath dependency on archive contained in EarContent of parent EAR	J2EE Mod Dep UI; MANIFEST.MF	JDT UI to create lib cp entry, new "Java EE Module Dep" UI to add/remove "dependency"/"non-dependency" attribute on project cp entry (if necessary)
Mark library or container classpath entry for publish/export in parent module (manifest cp ref)	JDT UI to add entry, J2EE Mod Dep or QuickFix; .classpath	JDT UI to add entry, new "Java EE Module Dep" UI (or QuickFix) to add/remove "dependency"/"non-dependency" attribute on project cp entry (if necessary)
Upgrade 2.0 non-classpath dependencies to classpath dependencies	NA	A button will exist if the "Ear Libraries" cp container exists on the project

Dynamic Web Projects (all Module Project items above apply)

• "Web App Libraries" cp container only exposes loose JARs in WEB-INF/lib (backward compatibility is exception).
• For Dynamic Web Projects, there must be the ability to control whether classpath entries are packaged in WEB-INF/lib or into the EAR root with MANIFEST.MF classpath references (users currently control this by selecting the dependency on either the "J2EE Modules" or "Web Libraries" tab). This will be controlled as follows:
  • If the web project is a child of an EAR, the new Java EE Modules UI include a feature that allows the specification of either an EAR root/Manifest classpath dependency or a /WEB-INF/lib dependency (the appropriate classpath attribute value will be created based on the UI selection). As mentioned above, this new UI will only be displayed for projects identified as projects that support the new WTP 3.0 classpath-based model (see EAR section above).
  • Matching current functionality, the value of the "dependency" attribute will control where the resolved contents of the entry will be packaged; two values are used "/WEB-INF/lib" and "../" (the later indicates that the entry should be packaged in the same folder in the parent module as this module).
  • If the classpath attribute is not specified, a default value for the location is computed as follows:
    • Project cp entries: "../" if project part of same EAR, "/WEB-INF/lib" otherwise (and dependent project packaged as JAR).
    • Library cp entries: "../" if project part of EAR, "/WEB-INF/lib" otherwise.
    • Container cp entries: "../" if project part of EAR, "/WEB-INF/lib" otherwise.
• Backward compatibility support:
  • The old non-classpath dependencies from 2.0 projects (WEB-INF/lib dependencies specified in component file) will continue to be returned as dependencies via the virtual component API.
  • "Web App Libraries" classpath container will continue to expose both WEB-INF/lib WEB-INF/classes content and component file references.
  • If a module project contains the WEB-INF/lib dependencies in the component file, it is assumed to have old non-classpath 2.0 dependencies and a UI command will be displayed to "upgrade" the old WEB-INF/lib refs to the new classpath-based model. This upgrade action will do the following:
    • Add explicit classpath entries (with the "dependency" attribute) for all WEB-INF/lib references previously specified in component file.
    • Remove dependency entries from the component file.
  • Read-only display of the old dependencies will can still be supported via the new "Java EE Module Dependencies" UI by displaying the resolved contents of the "Web App Libraries" classpath container (actual publish/export logic will continue to ignore this cp container since the exposed items are already referenced in the component file)
  • (Nice to have) Write access to old component file-based WEB-INF/lib dependencies: could enable this via a UI associated with the "Web App Libraries" cp container (would be a UI similar to the existing UI)
• (Nice to have) If a web project that is part of an EAR is exported as a WAR, it would be nice to support an option (selected at export time) that turned all MANIFEST.MF refs into WEB-INF/lib refs and thereby ensured that all required classes were accessible to the WAR.
• (Nice to have) Support for visualizing the structure/content of the assembled WAR

Dynamic Web Project Dependency Management Tasks

Task	Current UI/Metadata	Proposed UI/Metadata
Create WEB-INF/lib dependency to project with Java nature (do not convert to utility)	Web Libraries tab of J2EE Mod Dep UI; component file (plain Java projects not supported)	JDT UI to create project cp entry, "Java EE Module Dep" UI to enable/disable for attribute on project cp entry for publish/export as WEB-INF/lib dep
Create WEB-INF/lib dependency to JAR archive associated with EAR	Web Libraries tab of J2EE Mod Dep UI; component file	JDT UI to create project cp entry, "Java EE Module Dep" UI to enable/disable for attribute on project cp entry for publish/export as WEB-INF/lib dep
Mark library or container classpath entry for publish/export in WEB-INF/lib	J2EE Mod Dep or QuickFix; .classpath	JDT UI to add cp entry, "Java EE Module Dep" UI (or QuickFix) to enable/disable cp entry attribute for publish/export in WEB-INF/lib
Publish/export loose libs in WEB-INF/lib	Web App Libraries cp container	same
Upgrade component file WEB-INF/lib dependencies to classpath dependencies	NA	A button will exist if these dependencies exists in the project