View source for ClasspathEntriesPublishExportSupport

= Publish/Export Support for Classpath Entries =

This WTP feature (first released in version 2.0) allows the resolved contributions from Java classpath
entries (including classpath containers) to be added to the published
(or exported) structure of Java EE module projects. Resolved JARs are 
added to either the /WEB-INF/lib directory of web
modules or the root of EAR modules. Resolved class folders are added to the /WEB-INF/classes folder of web modules or to the root of 
other modules. The set of classpath entries to publish/export can be managed
using the standard "J2EE Module Dependencies" properties
page. Classpath entries that are valid to publish/export are
listed along with other potential dependencies for
(de)selection. Selected classpath entries are marked using a special 
classpath entry attribute ("org.eclipse.jst.component.dependency"); removal of
this attribute is also supported via the Java Build Path properties page.

An API is available for adopters requiring a tighter integration with
this functionality: "org.eclipse.jst.j2ee" plugin,
"org.eclipse.jst.j2ee.classpathdep" package.

== Standalone Web Project Example ==

Goal: Include the JARs referenced by a classpath container in
the /WEB-INF/lib directory of a deployed/exported dynamic web project.
<br/>
Steps:
<br/>
* Create a "User Library" (Window-Preferences-Java-Build Path-User Libraries) that references a collection of JARs (note: any non-WTP classpath container can be used).
* Create a dynamic web project.
* Add the user library to the project (Properties-Java Build Path-Libraries-Add Library). This will add a classpath container entry to the web project for the user library.
* Switch to the "J2EE Module Dependencies" (the Java build path changes must be applied first)
* A selection will be visible for the classpath container entry just added (will be prefixed by "(Classpath) ")). Select this and click "OK" (the special dependency attribute will be added to the classpath entry and the value for the attribute will be the runtime path for the resolved JARs, "/WEB-INF/lib").
* Export or publish the web project. The JAR contents of the user library will be added to the /WEB-INF/lib directory.

== EAR Project Example ==

Goal: Include the JARs referenced by a classpath container in the root
an EAR and reference, via the MANIFEST.MF classpath, from multiple EAR
modules.
<br/>
Steps:
<br/>
* Create a "User Library" (Window-Preferences-Java-Build Path-User Libraries) that references a collection of JARs.
* Create an EAR project with multiple child dynamic web projects.
* For each child dynamic web project:
** Add the user library to the Java build path (Properties-Java Build Path-Libraries-Add Library). This will add a classpath container entry for the user library.
** Switch to the "J2EE Module Dependencies" (the Java build path changes must be applied first) and select the "J2EE Modules" tab.
** A selection will be visible for the user library classpath container entry just added (will be prefixed by "(Classpath)")). Select this and click "OK" (the special dependency attribute will be added to the classpath entry and the value for the attribute will be the special value "../" indicating that the resolved JARs should be added into the parent module at the same location as the web module).
* Open the "J2EE Module Dependencies" for the EAR project. The resolved JARs from the classpath container will be shown as grayed entries in the table and the "Project" column will contain a list of each referencing project.
* Export or publish the EAR project. The JAR files resolved by the classpath container will be added into the root of the EAR and the MANIFEST.MF classpath for each child web project will be dynamically modified to include all of the resolved classpath container JARs.

== Support for Utility Projects Referenced Only by a Dynamic Web Project ==

For WTP 2.x and earlier, the J2EE Module Dependencies UI is not displayed for Utility
projects not referenced by an EAR project (it is displayed in 3.0 M4), so users must enable/disble
publish/export as follows:
<br/>
* To enable: In the Problems view, find the warning problem marker for the classpath entry (indicating that the entry will not be published/exported) and select the QuickFix to enable publish/export support.
* To disable: On the Java Build Path properties page, select the "Publish/export dependency" attribute for the desired classpath entry and select the "Remove" button.

== Filtering Custom Classpath Containers ==

For adopters that provide classpath containers whose contents will be available
at runtime and should therefore not be considered for inclusion in the
published/exported structure of the module, an extension point is available
that allows that classpath container entry to be filtered out of the list of
entries available for dependency selection: 
"org.eclipse.jst.j2ee.classpathdep"

See the plugin.xml in the org.eclipse.jst.j2ee plugin for an example.

== Filtering Specific Classpath Entries ==

If you want to exclude a specific raw classpath entry from publish/export dependency consideration (i.e. you know it will be accessible at runtime and don't want to see the "XXX will not be exported or published" warning), you can do the following:
* On WTP 3.0 M4, select the Quick Fix for the "XXX will not be exported or published" warning and select the fix "Exclude the associated raw classpath entry from the set of potential publish/export dependencies". This will add the "org.eclipse.jst.component.nondependency" attribute to that cp entry and will eliminate the warning as well as exclude it from future dependency consideration (i.e. it won't clutter the J2EE module dependencies UI list).

== Features Added in WTP 3.0 M4 ==

* Support for library classpath entries that reference class folders (https://bugs.eclipse.org/bugs/show_bug.cgi?id=189943)
* Way to turn off "XXX will not be exported or published" (https://bugs.eclipse.org/bugs/show_bug.cgi?id=190783)
* UI support for utility projects referenced only by a dynamic web project. 

== Future Enhancements ==

* Support for project classpath entries (https://bugs.eclipse.org/bugs/show_bug.cgi?id=184125)
* Consolidation of Java build path with Java EE module dependencies (https://bugs.eclipse.org/bugs/show_bug.cgi?id=116856)
* Preferences to support behavior of ClasspathDependencyValidator (https://bugs.eclipse.org/bugs/show_bug.cgi?id=185112)
* Extension point for filtering custom classpath variables (https://bugs.eclipse.org/bugs/show_bug.cgi?id=200989)

[[Category:Eclipse Web Tools Platform Project]]