<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="../../../../wtp.xsl"?>
<html>
	<head>
		<meta name="root" content="../../../../../" />
		<title>wizards api overview</title>
	</head>
	
	<body>
		<h1>jst j2ee</h1>
		<h2>Intoduction</h2>
		<BR/>
		<p>
		The following document provides a high level overview of the J2EE Wizards
		made available as part of the WTP M2 release. Most of these wizards are
		meant to be consumed by actions or UI, but facilities are provided to implement
		your own custom J2EE wizards.
		</p>
		<h2>Overview</h2> 
			<BR/>
			<P > The purpose of
			the following document is to highlight the API exposed as part of the
			Web Tools Platform Project for the creation, import, and export of 
			<I>J2EE artifacts</I>. A <I>J2EE artifact</I> is any contained,
			deployable component that follows the J2EE specification in its
			structure and content.
			</P>
			
			<P >Each of the three general actions <B>creation</B>,
			<B>import</B>, and <B>export</B> provides a base class
			with common functionality which is designed to be exposed as public API.
			Each of these general classes is then extended for the specific J2EE
			module types: Enterprise Applications, Application Client Modules,
			Connector Modules, Enterprise Java Bean Modules, and Web Application
			Modules. The concrete implementations are not exposed to be extended,
			only to be consumed. The purpose of these wizards is to facilitate a
			reference implementation for the entry and exit story for J2EE
			artifacts. More specialized implementations can extend the general base
			classes as needed.
			</P>
			
			<H4 >The Creation Story</H4>
			<P > Clients that wish to build their own creation wizard can use one of two base classes.
			The <code>org.eclipse.jst.j2ee.ui.J2EEArtifactCreationWizard</code>
			is generic enough for any type of J2EE module (*.jar, *.war, *.rar) or
			application (*.ear) creation. The <code>J2EEArtifactCreationWizard</code> 
			provides template methods for initialization (#doInit()) and disposal
			(#doDispose()). In the <B>final</B>
			init() method, the wizard will store away the selection which was
			available when the wizard was created for use by subclasses
			(#getSelection()). Furthermore, some customized logic is available to
			override the final perspective that will be suggested to the user. Like
			other Eclipse creation wizards, upon completion an appropriate
			perspective will be suggested to the user. However, in the realm of the
			Web Tools Platform, some wizards may be used by different perspectives
			(e.g. a Web Perspective vs. a J2EE Perspective). The Web Tools Platform
			has extended this functionality to allow subclassed wizards to return a
			different final perspective ID which can be determined programmatically.
			SPI Clients should override getFinalPerspectiveID() to take advantage of
			this functionality.
			</P>
			
			<P >Clients that are focused on basic J2EE module types (*.jar, *.war, *.rar) and
			that use an Operation Data Model based on <code>org.eclipse.jst.j2ee.application.operations.J2EEModuleCreationDataModel</code>
			may <code>org.eclipse.jst.j2ee.ui.J2EEModuleCreationWizard.</code>
			</P>
			
			<P>The subclasses will have the actively selected Enterprise Application module
			automatically filled in their Operation Data Model using the
			<code>J2EEModuleCreationDataModel.EAR_PROJECT_NAME</code> property, in addition to
			the correct <code>ServerTargetDataModel.J2EE_VERSION_ID</code> and
			<code>J2EEModuleCreationDataModel.J2EE_VERSION</code>.
			</P>
			
			<P >The remaining creation wizard classes are not meant to be extended, but
			instead provide a reference implementation for clients that only wish to
			use the wizards in their UI or actions. The following wizards:
			</P>
			<P></P>
			<UL>
				<LI><code>org.eclipse.jst.j2ee.ui.EnterpriseApplicationCreationWizard</code></LI>
				<LI><code>org.eclipse.jst.j2ee.ui.AppClientModuleCreationWizard</code></LI>
				<LI><code>org.eclipse.jst.j2ee.jca.ui.ConnectorModuleCreationWizard</code></LI>
				<LI><code>org.eclipse.jst.ejb.ui.EJBModuleCreationWizard</code></LI>
				<LI><code>org.eclipse.jst.servlet.ui.WebModuleCreationWizard</code></LI>
			</UL>
			
			<P >define the basic functionality to use their corresponding Operation Data Models
			and Operations. Clients may use the default constructor to create these
			wizards, which will cause the Operation Data Model and Operation to be
			created as needed, or clients may supply an Operation Data Model with
			some values already set, which will be used to pre-populate widget
			values in the wizard.
			</P>
			
			<H4 >The Import/Export Story</H4>
			<P >The
			Import/Export story follows a pattern similar to the creation story. All
			general function is encapsulated into a generic base class (
			 <code>org.eclipse.jst.j2ee.ui.J2EEArtifactImportWizard</code> and
			 <code>org.eclipse.jst.j2ee.ui.J2EEArtifactExportWizard</code> 
			respectively). Each of these wizards ensures that open, dirty editors
			are saved before the operation executes. The selection is also made
			available to subclasses via <code>getSelection()</code>. Furthermore, the
			<code>J2EEArtifactImportWizard</code> provides functionality to override the
			suggested final perspective in the same way that the <code>J2EEArtifactCreationWizard</code> does.
			</P>
			
			<P >The <code>J2EEArtifactImportWizard</code> is subclassed into an abstract 
			<code>org.eclipse.jst.j2ee.ui.J2EEModuleImportWizard</code>which
			pulls together common functionality required by concrete module import
			wizards based on <code>org.eclipse.jst.j2ee.application.operations.J2EEModuleImportDataModel</code>.
			The <code>J2EEModuleImportWizard</code> does not use the same direct operation returned
			from <code>WTPWizard.createBaseOperation()</code>. Instead, the returned operation is
			wrapped in another WTP Operation that performs validation once the
			project has been imported. The specific module validators to be run are
			defined by the method <code>J2EEModuleImportWizard.getModuleValidatorStrings()</code>.
			</P>
			
			<P> The <code>J2EEArtifactExportWizard</code> is subclassed directly into concrete module export classes.
			</P>
			
			<P>	The concrete Import/Export wizards may be used by clients that wish to add
			import/export functionality into their UI or actions, but these classes
			are not meant to be extended. Any custom wizards should be built using
			the abstract J2EEArtifact&lt;Action&gt;Wizards. </P>


	</body>	
</html>