<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="../../../../../webtools/wtp.xsl"?>
<html>
	<head>
		<meta
			name="root"
			content="../../../../../" />
		<title>Flexible Project Api</title>
	</head>
 
	<body>
		<h1>Flexible Project Api and Usage</h1>
		<h2>Overview</h2>
		<p>
		The flexible project support in WTP has lead to creation of new api and deprecation of exisitng api. Consumers of existing api need to move on to the new api to get their functionality working. Even though the old api exists and is deprected, if it is still used the functionality will be broken as those deprecated api are not being used internally anymore. The major api usage shift is in J2EE Nature Runtime classes and J2EE Edit models. The following document provides an overview of the api changes and how they need to be used to get the old desired functionality using the new api.
		</p>
		<p>
		This document is an ongoing document and as and when new api are available for the flexible project support and old api deprecated this document will be updated.
		</p>
		<h2>Api and Usage</h2>
		<p>
		Using the Flexible project layout a single <b>ProjectComponent</b> that is the top level entity can be associated to multiple WorkbenchComponents. Each <b>WorkbenchComponent</b> can be associated to multiple <b>ComponentResources</b>. Each <b>WorkbenchComponent</b> can be associated with multiple <b>DependentComponents</b>. To access the structural model of these objects you need to use the api available in the <b>ModuleCore</b> class which in the past the api on *NatureRuntime classes were used. To access the the WorkbenchComponent content metamodel the api in the <b>*ArtifactEdit</b> classes which in the past was through accessing *EditModel classes. 
		</p>
		<br/>
		<h4>ModuleCore</h4>
		<p>
		 ModuleCore hides the management of accessing EditModels ({@see org.eclipse.wst.common.modulecore.ModuleStructuralModel}) correctly. Each project has exactly one ({@see org.eclipse.wst.common.modulecore.ModuleStructuralModel}) for read and exactly one for write. Each of these is shared among all clients and reference counted as necessary. Clients should use ModuleCore when working with the WTP Modules Strcutrual Model. The Api on ModuleCore class has well documented with JavaDoc and to get feel about the usage of these api, check for the references of the api's.
 		</p>
 		<p>
		Each ModuleCore edit facade is designed to manage the EditModel lifecycle for clients. However, while each ModuleCore is designed to be passed around as needed, clients must enforce the ModuleCore lifecycle. The most common method of acquiring a ModuleCore edit facade is to use {@see #getModuleCoreForRead(IProject)} or {@see #getModuleCoreForWrite(IProject)}.
		</p>
		<p>
		When clients have concluded their use of their ModuleCore instance adapter , clients must call {@see #dispose()}.
		</p>
		<br/>
		<h4>ArtifactEdit</h4>
		<p>
		 Provides a Facade pattern for accessing Module Content Metamodels for WorkbenchComponents. ArtifactEdit hides the management of accessing edit models ({@see ArtifactEditModel}) correctly. Each project may have multiple ({@see ArtifactEditModel})s depending on the number of modules contained by the project. Clients should use ArtifactEdit or an appropriate subclass when working with the content models of WTP modules.
		 </p>
		<p>
		Each ArtifactEdit facade is designed to manage the EditModel lifecycle for clients. However, while each ArtifactEdit is designed to be passed around as needed, clients must enforce the ArtifactEdit lifecycle. The most common method of acquiring a ArtifactEdit instance facade is to use {@see #getArtifactEditForRead(WorkbenchComponent)}; or {@see #getArtifactEditForWrite(WorkbenchComponent)}. When clients have concluded their use of the instance, clients must call {@see #dispose()}
		</p>
		<p>
		The current api that is available on each j2ee artifact edit is listed below. More api on each j2ee artifact edit will exposed out subsequently as needed by code that is consuming the old api through natures and edit models.
		</p>
		<br/>
		<h4>WebArtifactEdit</h4>
		<p>
		The WebArtifactEdit class provides the api that were available on J2EEWebNatureRuntime and WebEditModel class. The J2EEWebNatureRuntime and WebEditModel classes and all the api in these classes will be deprecated. Any consumers of the api in J2EEWebNatureRuntime have to migrate their code to use the api on WebArtifactEdit. The list of old and corresponding new api are listed below with examples.
		<pre>
		
		J2EEWebNatureRuntime.getWebAppEditModelForRead(Object)->WebArtifactEdit.getWebArtifactEditForRead(WorkbenchComponent)
		J2EEWebNatureRuntime.getWebAppEditModelForWrite(Object)->WebArtifactEdit.getWebArtifactEditForWrite(WorkbenchComponent)
		J2EEWebNatureRuntime.hasRuntime(IProject project)->WebArtifactEdit.isValidWebModule(WorkbenchComponent)
		J2EEWebNatureRuntime.setContextRoot(String newContextRoot)->WebArtifactEdit.setServerContextRoot(String)	
		J2EEWebNatureRuntime.getDeploymentDescriptorPath()->WebArtifactEdit.getDeploymentDescriptorPath()
		J2EEWebNatureRuntime.getDeploymentDescriptorRoot()->WebArtifactEdit.getDeploymentDescriptorRoot()
		J2EEWebNatureRuntime.getJ2EEVersion()->WebArtifactEdit.getJ2EEVersion()
		J2EEWebNAtureRuntime.getJSPLevel()->WebArtifactEdit.getJSPVersion()
		J2EEWebNatureRuntime.getLibModules()-> WebArtifactEdit.getLibModules()
		J2EEWebNatureRuntime.getContextRoot()->WebArtifactEdit.getServerContextRoot()
		WebEditModel.getJ2EEVersion()->WebArtifactEdit.getServletVersion()
		WebEditModel.addWebAppIfNecessary(XMLResource res)->WebArtifactEdit.addWebAppIfNecessary(XMLResource)
		WebEditModel.makeDeploymentDescriptorWithRoot()-> WebArtifactEdit.createModelRoot(), WebArtifactEdit.createModelRoot(IProject, IPath, int)
		WebEditModel.getDeploymentDescriptorResource()->WebArtifactEdit.getDeploymentDescriptorResource()

		
	The following piece of code shows how to access a WebArtifactEdit for read to get the servlet version of a Web module
			
		private int getServletVersion(){
    		WebArtifactEdit webEdit = null;
    		int nVersion = 22;
   			try{
   				webEdit = WebArtifactEdit.getWebArtifactEditForRead( wbModule );
   				if(webEdit != null) {
   				nVersion = webEdit.getServletVersion();
   			}
   		}	
  			catch(Exception e){
        		e.printStackTrace();
   			} finally {
   				if(webEdit != null)
   					webEdit.dispose();
   		}       
   			return nVersion;
		}
		</pre>
		</p>
		<br/>
		<h4>EARArtifactEdit</h4>
		<p>
		The EARArtifactEdit class provides the api that were available on EARNatureRuntime and EAREditModel classes. The EARNatureRuntime and EAREditModel classes and all the api in these classes  will be deprecated. Any consumers of the api in EARNatureRuntime and EAREditModel have to migrate their code to use the api on EARArtifactEdit. The list of old and corresponding new api are listed below with examples.
		</p>
		<pre>
		EARNatureRuntime.getJ2EEEditModelForRead(Object)->EARArtifactEdit.getEARArtifactEditForRead(WorkbenchComponent)
		EARNatureRuntime.getJ2EEEditModelForWrite(Object)->EARArtifactEdit.getEARArtifactEditForWrite(WorkbenchComponent)
		EARNatureRuntime.hasRuntime(IProject)->EARArtifactEdit.isValidEARModule(WorkbenchComponent)
		EARNatureRuntime.makeRoot(Resource)->EARArtifactEdit.createModelRoot()
		EAREditModel.getApplication()->EARArtifactEdit.getApplication()
		EAREditModel.getApplicationXmiResource()->EARArtifactEdit.getApplicationXmiResource()
		EAREditModel.getDeploymentDescriptorResource()->EARArtifactEdit.getDeploymentDescriptorResource()
		EARNatureRuntime.getJ2EEVersion()->EARArtifactEdit.getJ2EEVersion()
		EARNatureRuntime.uriExists(String)->EARArtifactEdit.uriExists(String)
	
	The following piece of code shows how to access a EARArtifactEdit for read to get the j2ee version on the enterprise application module
		
		private void preFillSelectedEARProject() {
			WorkbenchComponent earModule = getSelectedEARModule();
			EARArtifactEdit earEdit = null;
			int j2eeVersion = 0;
			if (earModule != null &amp;&amp; model != null) {
				try {
					earEdit = EARArtifactEdit.getEARArtifactEditForRead(earModule);
					j2eeVersion = earEdit.getJ2EEVersion();
				} finally {
					if (earEdit != null)
						earEdit.dispose();
				}
				model.setIntProperty(ServerTargetDataModel.J2EE_VERSION_ID, j2eeVersion);
				model.setIntProperty(J2EEComponentCreationDataModel.J2EE_VERSION, j2eeVersion);
				model.setProperty(J2EEComponentCreationDataModel.EAR_MODULE_NAME, earModule.getName());
			}
		}
		</pre>
		<br/>
		<h4>AppClientArtifactEdit</h4>
		<p>
		The AppClientArtifactEdit class provides the api that were available on ApplicationClientNatureRuntime and AppClientEditModel classes. The ApplicationClientNatureRuntime and ApplClientEditModel classes and all the api in these classes  will be deprecated. Any consumers of the api in ApplicationClientNatureRuntime and AppClientEditModel  have to migrate their code to use the api on AppClientArtifactEdit. The list of old and corresponding new api are listed below with examples.
		
	<pre>
		ApplicationClientNatureRuntime.getAppClientEditModelForRead(Object)->AppClientArtifactEdit.getAppClientArtifactEditForRead(WorkbenchComponent)
		ApplicationClientNatureRuntime.getAppClientEditModelForWrite(Object)->AppClientArtifactEdit.getAppClientArtifactEditForWrite(WorkbenchComponent)
		ApplicationClientNatureRuntime.hasRuntime(IProject)->AppClientArtifactEdit.isValidApplicationClientModule(WorkbenchComponent)
		AppClientEditModel.makeDeploymentDescriptorWithRoot()->AppClientArtifactEdit.createModelRoot()
		ApplicationClientNatureRuntime.createNewModule()->AppClientArtifactEdit.createNewModule()
		AppClientEditModel.getApplicationClient()->AppClientArtifactEdit.getApplicationClient()
		ApplicationClientNatureRuntime.getApplicationClientXmiResource()->AppClientArtifactEdit.getApplicationClientXmiResource()
		AppClientEditModel.getDeploymentDescriptorResource()->AppClientArtifactEdit.getDeploymentDescriptorResource()
		ApplicationClientNatureRuntime.getDeploymentDescriptorRoot()->AppClientArtifactEdit.getDeploymentDescriptorRoot()
		ApplicationClientNatureRuntime.->AppClientArtifactEdit.getJ2EEVersion()
	<br/>
	The following piece of code shows how to access an AppClientArtifactEdit for write to create the deployment descriptor for an application client module
	<br/>
		protected void createDeploymentDescriptor(IProgressMonitor monitor) throws CoreException, InvocationTargetException, InterruptedException {
	        AppClientArtifactEdit artifactEdit = null;
	        try {
	            WorkbenchComponent wbModule = getWorkbenchModule();
	            artifactEdit = AppClientArtifactEdit.getAppClientArtifactEditForWrite(wbModule);
	            IProject rootProject = getDataModel().getTargetProject();
	            URI metainfURI = URI.createURI(rootProject.getName() + IPath.SEPARATOR + getModuleName() + ".jar");
	            IPath absMetaRoot = ProjectUtilities.getJavaProjectOutputAbsoluteLocation(rootProject).append(metainfURI.toString());
	            createFolder(absMetaRoot);
	
	            artifactEdit.getDeploymentDescriptorRoot();
	            AppClientModuleCreationDataModelOld dataModel = (AppClientModuleCreationDataModelOld) operationDataModel;
	            if (dataModel.getBooleanProperty(AppClientModuleCreationDataModelOld.CREATE_DEFAULT_MAIN_CLASS)) {
	                NewJavaClassDataModel mainClassDataModel = new NewJavaClassDataModel();
	                mainClassDataModel.setProperty(NewJavaClassDataModel.PROJECT_NAME, dataModel.getProjectDataModel().getProject().getName());
	                mainClassDataModel.setProperty(NewJavaClassDataModel.CLASS_NAME, "Main"); //$NON-NLS-1$
	                mainClassDataModel.setBooleanProperty(NewJavaClassDataModel.MAIN_METHOD, true);
	                mainClassDataModel.getDefaultOperation().run(monitor);
	                dataModel.getUpdateManifestDataModel().setProperty(UpdateManifestDataModel.MAIN_CLASS, mainClassDataModel.getProperty(NewJavaClassDataModel.CLASS_NAME));
	            }
	        } finally {
	            if (artifactEdit != null)
	                artifactEdit.dispose();
	            artifactEdit = null;
	        }
	    }
    </pre>
    </p>
		<br/>
		<h4>EJBArtifactEdit</h4>
		<p>
		The EJBArtifactEdit class provides the api that were available on EJBNatureRuntime and EJBEditModel classes. The EJBNatureRuntime and EJBEditModel classes and all the api in these classes will be deprecated. Any consumers of the api in the EJBNatureRuntime or EJBEditModel classes have to migrate their code to use the EJBArtifactEdit. The list of old and corresponding new api are listed below
		<pre>
		
		EJBNatureRuntime.getEJBEditModelForRead(Object) ->EJBArtifactEdit.getEJBArtifactEditForRead(WorkbenchComponent)
		EJBNatureRuntime.getEJBEditModelForWrite(Object) ->EJBArtifactEdit.getEJBArtifactEditForWrite(WorkbenchComponent)
		EJBNatureRuntime.hasRuntime(IProject)->EJBArtifactEdit.isValidEJBModule(WorkbenchComponent)
		EJBNatureRuntime.createNewModule()->EJBArtifactEdit.createNewModule()
		EJBEditModel.getDeploymentDescriptorResource()->EJBArtifactEdit.getDeploymentDescriptorResource()
		EJBNatureRuntime.getDeploymentDescriptorRoot()->EJBArtifactEdit.getDeploymentDescriptorRoot()
		EJBNatureRuntime.getDeploymentDescriptorType()->EJBArtifactEdit.getDeploymenyDescriptorType()
		EJBNatureRuntime.getEJBClientJARProject()->EJBArtifactEdit.getEJBClientJarModule(IProject)
		EJBNatureRuntime.getEJBJar()->EJBArtifactEdit.getEJBJar()
		EJBNatureRuntime.getEjbXmiResource()->EJBArtifactEdit.getEJBJarXmiResource()
		EJBNatureRuntime.getJ2EEVersion()->EJBArtifactEdit.getJ2EEVersion()
		EJBNatureRuntime.hasEJBClientJARProject()->EJBArtifactEdit.hasEJBClientJARProject(IProject)
	<br/>
	The following piece of code shows how to access an EJBArtifactEdit for read to check if the EJB module has an EJB client jar associated with it.
	<br/>
		private void handleHasClientJar() {
			EJBArtifactEdit edit = null;
			try {
				if (module != null) {
					edit = EJBArtifactEdit.getEJBArtifactEditForRead(module);
					if (edit != null &amp;&amp; edit.hasEJBClientJARProject(ModuleCore.getContainingProject(module.getHandle())));
						enableAllSections(false);
					} else
						enableAllSections(true);
			} catch(UnresolveableURIException e) {
					Logger.getLogger().logError(e);
			  } finally {
				  if(edit != null)
					  edit.dispose();
					  
			  }
		}
		</pre>
		</p>
		
		
	</body>
</html>