<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="../../wtp.xsl"?>
<html>
	<head>
		<meta
			name="root"
			content="../../.." />
		<title>flexible project concepts</title>
	</head>

	<body>
		<a name="top" />

		<h1>jst j2ee</h1>

		<h2>Introduction</h2>
		<p>
			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.
		</p>
		<p>
			The contents of this document are representative of the future direction.
			However, some of this functionality described is representative of our
			current state.
		</p>
		<p>
			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.
		</p>
		<p>
			A
			<b>project</b>
			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.

		</p>
		<p>The scenario slides highlight the following types of use cases:</p>
		<ul>
			<li>
				<p>Simple Project (contains one module and one Deploy Scheme)</p>
			</li>
			<li>
				<p>
					Simple Container Project (contains one or more modules, possibly
					multiple Deploy Schemes)
				</p>
			</li>
			<li>
				<p>
					Application Project (application and modules contained in the
					same Simple Container project)
				</p>
			</li>
			<li>
				<p>
					Application Project Variation (application in one Simple
					Container Project modules may be in other Simple Container
					projects)
				</p>
			</li>
			<li>
				<p>Composed Modules (stay tuned (bum bum bum))</p>
			</li>
		</ul>
		<p>
			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.
		</p>
		<p>
			A
			<b>resource</b>
			is a abstraction which contains model elements. A
			<b>resource set</b>
			is a collection of related persistent resources. The resource set manages
			the collection of resources and produces notifications for changes to
			that collection. A
			<b>project resource set</b>
			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
			<b>relative URI</b>
			, which is a partial URI with respect to or relative to the project. A
			<b>WTP project resource set</b>
			is defined in terms of module resources, which contain abstract module
			models (defined later).
		</p>
		<p>
			A
			<b>URI converter</b>
			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.
		</p>
		<p>
			An
			<b>abstract module</b>
			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.
		</p>
		<p>
			A
			<b>J2EE abstract module</b>
			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
			<b>deployment descriptors</b>
			. 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:
		</p>
		<ul>
			<li>
				<p>Application</p>
			</li>
			<li>
				<p>Application Client</p>
			</li>
			<li>
				<p>EJB</p>
			</li>
			<li>
				<p>Web</p>
			</li>
			<li>
				<p>Resource Adapter for Java Connector</p>
			</li>
		</ul>
		<p>
			Vendor-specific deployment descriptors may be defined for different
			Enterprise application containers to provide additional information.
		</p>
		<p>
			Each deployment descriptor describes a set of contained objects which are
			represented through
			<b>module models</b>
			. The root abstract module model object for the deployment descriptor is
			the associated J2EE abstract module type object.
		</p>
		<ul>
			<li>
				<p>
					The
					<b>Application</b>
					is the root object for an EAR module.
				</p>
			</li>
			<li>
				<p>
					The
					<b>EJBJar</b>
					is the root object for an EJB module.
				</p>
			</li>
			<li>
				<p>
					The
					<b>WebApp</b>
					is the root object for a Web module
				</p>
			</li>
			<li>
				<p>
					The
					<b>ApplicationClient</b>
					is the root object for an Application Client module.
				</p>
			</li>
			<li>
				<p>
					The
					<b>Connector</b>
					is the root object for a JCA Connector module.
				</p>
			</li>
		</ul>
		<p>
			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
			<b>ModuleCore</b>
			.
		</p>
		<p>
			<b>ModuleCore</b>
			can be used to acquire, create, and destroy
			<b>abstract module contexts</b>
			. An
			<b>abstract module context</b>
			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).

		</p>

		<table
			cellspacing="10"
			cellpadding="10">
			<tr>
				<td>
					<p>
					<!-- Image does not exist.
						<img src="../images/modulecore_concepts.jpg" />
						-->
					</p>
				</td>
			</tr>
			<tr>
				<td>
					<p>
						<i>
							Figure 1: Overview of ModuleCore, ModuleContext, and
							Abstract Module relationships.
						</i>
					</p>
				</td>
			</tr>
		</table>
		<p>
			Meanwhile,
			<b>edit models</b>
			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.
		</p>
		<p>
			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.
		</p>
		<p>
			Edit models are created via an extension which defines the
			<b>edit model factory</b>
			. The lifecycle of how edit models are created and destroyed will be
			covered in the API Concepts document.
		</p>
		<p>
			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
			<b>target EARs</b>
			. 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.
		</p>
		<p>
			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).
		</p>
		<p>
			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
			<b>utility jars</b>
			. 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.
		</p>
		<p>
			An <b>extracted module</b> or <b>utility jar module</b> 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.
		</p>
		<p><i>Last updated 11/11/04</i></p>
	</body>
</html>