Skip to main content

skip to main content

developerWorks  >  WebSphere  >

Share and Share Alike

A New Project Interchange Feature for Eclipse and WebSphere Studio

developerWorks
Document options

Document options requiring JavaScript are not displayed

Sample code


Rate this page

Help us improve this content


Level: Introductory

Daniel Berg (danberg@us.ibm.com), Advisory Software Engineer, J2EE Tools Team Lead, IBM Research Triangle Park Lab, North Carolina
Ritchie Schacher (schacher@us.ibm.com), Advisory Software Engineer, J2EE Tools, IBM Research Triangle Park Lab, North Carolina

14 Sep 2003

This article explains several methods of repository and non-repository code sharing, and describes the advantages and disadvantages of each. The article also includes a new Project Interchange feature that provides an alternative way to share projects when a repository is not a viable option.

Introduction

Gone are the days when a "cowboy" programmer could write code in a vacuum. Sharing code is a necessity on virtually every major development project. Eclipse and IBM® WebSphere® Studio provide several methods for sharing your code with colleagues, each of which has advantages and disadvantages. In large development projects, the most common code sharing method is through a repository. At times, however, you may want to share your work without using a repository.

This article explains several different methods of repository and non-repository code sharing, and describes the advantages and disadvantages of each. The article also includes a new Project Interchange feature that provides an alternative way to share code when a repository is not a viable option.



Back to top


Setting up the environment

In order to follow along with the examples in this article, you will need to run two workspaces. There are two ways to do this:

  • Run workspaces on two separate machines
  • Run two workspaces on the same machine

You can run two workspaces on the same machine using the -data <workspaceLocation> startup parameter when running Eclipse or WebSphere Studio, where the value of workspaceLocation is the absolute path to the workspace on your local drive. On Windows® platforms, you can simply create a shortcut to the executable ( eclipse.exe or wsappdev.exe ) and add the parameter to the target field. Regardless of whether you use two machines or the same machine, we will refer to the workspace where projects are created as the source workspace , and the workspace where you'd like to load shared work as the target workspace .

First, you will need some projects in your source workspace. If you already have a set of projects with dependencies, you can use those, or alternatively you can use the samples, which you can add by following the steps below. This article will use the projects created by adding the Auction example, available with WebSphere Studio Application Developer, and then embellish it a bit further. To add these projects to your workspace:

  1. From the Workbench window, select File => New => Other , and Examples => Enterprise Applications 1.3 => Auction .
  2. Click Next , accept the defaults, and click Finish .

Three new projects are added to your workspace: AuctionExample, AuctionRunV5EJB, and AuctionRunV5Web . This is a good example for project sharing because you need to share all the projects as a group for them to be meaningful in another workspace. But just to keep things interesting, let's add a couple more dependencies. First, add a Project Utility JAR to the EAR:

  1. Create a new Java™#xa0Project named AuctionUtils .
  2. Open the Application Deployment Descriptor editor and go to the Modules page.
  3. In the Utility JARs section, click Add .
  4. In the dialog that opens, select the AuctionUtils project and click Finish :

Next, add a dependency from AuctionRunV5EJB to AuctionUtils:

  1. In either the Resource Navigator or J2EE Navigator, select the AuctionRunV5EJB project, open the pop-up menu, and select Properties.
  2. Select the Java JAR Dependencies page, and select AuctionUtils.jar as a dependency:

Now let's add some classpath variables to the AuctionUtils Java build path:

  1. Select the AuctionUtils project, open the pop-up menu, and select Properties.
  2. Select the Java Build Path page and select the Libraries tab.
  3. Click Add Variable .
  4. In the dialog that opens, scroll down the list, select the variable WAS_50_PLUGINDIR , and then select Extend .
  5. Select the two JARs lib/j2ee.jar and lib/xerces.jar .
  6. Click OK in the dialog and OK to save the build path:

Using classpath variables is a best practice that makes your projects more portable and shareable, as it avoids encoding absolute paths in your project metadata. For example, below is the contents of the .classpath file in the AuctionUtils project. Only the variable WAS_50_PLUGINDIR is referenced, and the absolute path of the referenced JARs is computed by the platform during startup: 

<?xml version="1.0" encoding="UTF-8"?>
<classpath>
<classpathentry kind="src" path=""/>
<classpathentry kind="var" path="JRE_LIB"
rootpath="JRE_SRCROOT" sourcepath="JRE_SRC"/>
<classpathentry kind="var" path="WAS_50_PLUGINDIR/lib/j2ee.jar"/>
<classpathentry kind="var" path="WAS_50_PLUGINDIR/lib/xerces.jar"/>
<classpathentry kind="output" path=""/>
</classpath>

Finally, add a utility class that requires the classpath variables for compilation:

  1. Create a package named test in the AuctionUtils project.
  2. Create a class DOMClient in the test package.
  3. Add the contents below to the DOMClient class: 
package test;
import java.io.IOException;
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.ParserConfigurationException;

import org.w3c.dom.Document;
import org.xml.sax.InputSource;
import org.xml.sax.SAXException;

/**
* @author schacher
*
* This class introduces a hard requirement on DOM APIs.
* Code is for illustrative purposes only.
*/
public class DOMClient {

public static DocumentBuilder getDefaultDocumentBuilder() throws
ParserConfigurationException {
javax.xml.parsers.DocumentBuilderFactory dbf =
javax.xml.parsers.DocumentBuilderFactory.newInstance();
return dbf.newDocumentBuilder();
}

public static Document parseDocument(InputSource inputSource)
throws ParserConfigurationException, IOException, SAXException
{
ClassLoader prevClassLoader =
Thread.currentThread().getContextClassLoader();
try {
Thread.currentThread().setContextClassLoader(
DOMClient.class.getClassLoader());
javax.xml.parsers.DocumentBuilder db = getDefaultDocumentBuilder();
return db.parse(inputSource);
} finally {
Thread.currentThread().setContextClassLoader(prevClassLoader);
}

       }
       }

Let's quickly review the set of projects you have in your workspace:

  • You have four projects that together compose an application, and which need to be shared together as a set.
  • Dependencies exist among the projects.
  • At least one external dependency exists, in the Java build path.
  • When sharing these projects, you want to share the data reliably and easily, preserve the project names and structure, preserve the dependencies between the projects, and preserve any other project-specific metadata and external dependencies as noted above.

The sections below review several methods of sharing these projects, and describe the implementation, advantages, and disadvantages of each method.



Back to top


Method 1: Use a repository

One of the most commonly used approaches to team development is to use a back-end repository in conjunction with native or third-party tools support. One example is the CVS support included with Eclipse and WebSphere Studio. Details on using the CVS feature are included in the WebShpere Studio and Eclipse online help:

In WebSphere Studio:

  1. Select Help > Help Contents .
  2. Select Application Developer Information => Workbench Basics => Tasks => Working in a team environment .

In Eclipse:

  1. Select Help > Help Contents .
  2. Select Workbench User Guide => Tasks => Working in a team environment .

Advantages

  • Version control
  • Differencing and merging capability
  • Full preservation of project structure, project names, and project metadata
  • Reliable way of sharing large numbers of projects

Disadvantages

  • Setup and administration of the back-end server is required. You may be interested in just prototyping a few projects and don't have the resources available for server administration.
  • If you are just prototyping, you may not want to clutter the production repository with your sandbox projects but nonetheless would like to share your work with colleagues.
  • It can be difficult to share projects with outside organizations because of firewalls.

We recommend using a repository for any large-scale project and for any project with a large amount of production code that requires version control and frequent backing up.



Back to top


Method 2: Share an entire workspace

This method of sharing takes a "brute force" approach. You either copy or ZIP up your entire workspace and make it available to another developer. On the target side, the workspace is copied or unzipped to a local disk, and the Workbench is started using the -data startup parameter as noted above. If you use this approach, be sure to shut down the Workbench before copying or zipping files, because metadata files may be in the process of being updated in background threads even when the Workbench appears to be idle.

Another thing to be aware of is that when you share a workspace, you share everything, including all of your preferences. This can be an advantage or a disadvantage, depending on your objectives, as discussed below. Also, if your projects are not in the default location, which is under the Workspace root directory, then sharing requires more work -- you must zip up the projects separately, and unzip them to the same physical path on the target machine.

Advantages

  • Full preservation of project structure, project names, and project metadata.
  • A simple way to share everything, and a useful way to share complex setups with teammates who are new to the team and just getting started. A default workspace can be made available on a shared server.
  • Can be used in conjunction with a team repository. For example, a default workspace setup can be published to a common location, and team members can pick up this workspace and synchronize only those projects they are actively developing.

Disadvantages

  • Workspace ZIP files can get very large, requiring extra time for zipping and unzipping, taking up significant space on a server, and sometimes causing problems if sent via e-mail. Much of the size may result not from the projects themselves, but from the metadata stored by the platform.
  • Extra work is required if the projects are in non-default locations.
  • You may only need to share a subset of the projects in the workspace, but this method requires you to share everything, including preferences.


Back to top


Method 3: Export an EAR file (WebSphere Studio only)

Using this method, you can use WebSphere Studio to generate a J2EE Enterprise Archive (EAR) file from a subset of projects in your workspace that compose an enterprise application. This method is used by many teams sharing J2EE applications like the sample we are working with, because of the ability to bundle the contents of all the projects required for the EAR. Here are the steps for this method, which reveal why it is not always optimal. Start by exporting an EAR file from your source workspace:

  1. From the WebSphere Studio Workbench window, select File => Export => EAR file , and click Next .
  2. From the drop down, select AuctionExample .
  3. Browse to or enter a file location.
  4. Select Export source files .
  5. Select Include project build paths and metadata files .
  6. Click Finish to complete the export:

Now import the EAR file you just created into your target workspace:

  1. Select File => Import => EAR file , and click Next .
  2. Browse to the file location of the EAR file, enter the project name AuctionExample , and click Next .
  3. Be sure to select Create a new Java project defined as a utility JAR or web library , to ensure that the JAR auctionUtils.jar is expanded into its own Java project, like it was in the source workspace.
  4. Click Finish to complete the import:

Now you're finished importing, and everything should be ready for development, because we included source and expanded the utility JAR, right? Almost, but not quite. Notice that there are compile errors in the utility JAR project:


Figure 1. Compilation errors
Compilation errors

Why do these errors exist? Recall that during the setup of the source project, we added the classpath variables to add visibility to the xercers.jar and j2ee.jar files. These variables are required in order to compile the code in the DOMClient class . However, during import, this information was lost. Notice, however, that the Web project compiled without any errors, because the import operation was able to derive the Java build path project dependencies from the dependencies specified by the MANIFEST.MF file in the web-app, as shown below: 

Manifest-Version: 1.0 Class-Path: AuctionRunV5EJB.jar

The EAR import does the best job possible at generating the Java build path based on the dependencies specified in the manifest files, but it cannot determine the external dependencies. You are probably asking, "What about that option to preserve metadata?" That option exists to support the binary project scenario for optimized builds (for more information on binary projects, see the online help). Several complexities are introduced when you try to preserve metadata and expand the EAR as source. For example, what if the original project structure contained multiple source folders in one project? Import cannot determine which files belong in which source folders. There are a number of ways, with limitations, that this problem could be fixed in another release, but this is probably not a good tactic. People have used EAR import/export as an interchange format as a matter of convenience, because until now there was no better method for sharing the projects. However, an EAR file is a deployable artifact for an application server, and normally it should not include source code and tool-specific metadata.

Advantages

  • Simple way to compute all the projects associated with an enterprise application and bundle the code into a single file.

Disadvantages

  • Original project structure and external dependencies are not fully preserved.
  • EAR file is polluted with extraneous data.


Back to top


Method 4: Export a ZIP file

You have now seen three independent methods for sharing projects between developers. Using a repository is the best approach, but sometimes you may need to share projects with a developer who does not have access to your repository. You could share the entire workspace as described above, but that usually requires sharing a great deal of unnecessary metadata. If it's a J2EE application, you can export an EAR file, which is better than sharing an entire workspace. But as described above, EAR export does not preserve the exact project structure. This brings us to a fourth method of sharing projects -- using a ZIP file.

To begin this method of project sharing, a set of projects needs to be exported to a ZIP file:

  1. Select File => Export to open the Export Wizard:
  2. Select Zip file and click Next .
  3. Select all of the projects that you need to share, which means you must know the relationships among the projects so that you share a complete set of them. Enter a ZIP file location (such as D:\temp\AuctionProjects.zip ):
  4. Click Finish to export the projects.

As we just showed, exporting the projects to a ZIP file is fairly easy. However, importing the projects into a target workspace is not so simple:

  1. Unzip the AuctionProjects.zip file to a directory. This directory will be the actual location of the project, so you may want to unzip the contents into your existing workspace. For the purpose of this demonstration, export the contents to a temporary location (such as D:\temp\AuctionProjects ).
  2. Select File => Import to open the Import Wizard:
  3. Select Existing Project into Workspace and then click Next .
  4. Click Browse to browse to the location of the first project directory ( AuctionExample ) from the temporary location in step 1:
  5. Click Finish . This will create the AuctionExample project within the workspace with the same location from step 4.
  6. Repeat steps 2 through 5 for each project that you want to share.

Advantages

  • Project structure is maintained.
  • A subset of projects can be shared without sharing the whole workspace.

Disadvantages

  • All required projects must be selected manually during export.
  • Care must be taken where you unzip the projects ZIP file because this will be the location of the shared projects.
  • Each project must be imported into another workspace one at a time.


Back to top


Method 5: Use Project Interchange ZIP files

None of the previous methods provides a good mechanism for easy project sharing without using a repository. What would be ideal is a method of project sharing that maintains the entire project structure, including metadata files, as in the workspace sharing method, but also has the convenience of computing a set of required projects for an entire application, as in exporting an EAR file. In addition, projects should be easy to import into another workspace with a single action and should not require several actions for each project, as in exporting a ZIP file.

This capability does not currently exist in Eclipse or WebSphere Studio. Therefore we have developed the Project Interchange feature, which provides new import and export wizards for sharing a set of projects easily in one step. Before using this new feature, you will need to add it to your version of Eclipse or WebSphere Studio.

Installing the Project Interchange feature

  1. Unzip com.ibm.etools.project.interchange.feature.zip to your WebSphere Studio or Eclipse install directory.
  2. Start WebSphere Studio or Eclipse. You should be prompted that you have pending changes. Click Yes . If a prompt does not appear, select Help => Software Updates => Pending Changes .
  3. Expand the tree in the Pending Configuration Changes window that opens. Select the top level date, which includes the Project Interchange feature (it should be the first and only entry).
  4. Click Finish .
  5. Click Yes when prompted to restart so the changes will take effect.

The project interchange feature shares projects via a ZIP file very similar to the ZIP file you exported earlier. However, it provides a more powerful Export Wizard for creating the ZIP file. To export a set of related projects:

  1. Select File => Export to open the Export Wizard:
  2. Select Project Interchange and then click Next :
  3. Select the AuctionExample project and click Select Referenced . This will automatically select all projects that are required by the selected projects.
  4. Enter a ZIP file in the To ZIP file field (for example, D:\temp\AuctionProjects2.zip ).
  5. Click Finish to create the ZIP file.

Now you have a ZIP file of the necessary projects as in the export ZIP file section, except that you did not need to know all the project dependencies. To import these projects into another workspace using the Project Interchange feature:

  1. Select File => Import to open the import wizard:
  2. Select Project Interchange and then click Next :
  3. Browse to the ZIP file that was just exported ( D:\temp\AuctionProjects2.zip ). The list of projects will be refreshed based on the projects that are in the selected ZIP file.
  4. The Project location root defaults to your workspace, but you may change it to any location that you want to serve as the directory where the projects will be unzipped.
  5. Select the AuctionExample project. Click Select Referenced to have all required projects automatically selected.
  6. Click Finish to have all of the selected projects unzipped from the ZIP file into the project location root directory and then imported into the workspace.

As the steps above show, it is quite simple to share projects using the new Project Interchange feature. However, this method of project sharing also has disadvantages and is not ideal for all cases. You can avoid these disadvantages by using a repository to share code, and the project interchange method is not intended to replace a repository for sharing projects on a development team.

Advantages

  • Simple to use
  • Preserves exact project names, structures, and classpaths
  • Computes referenced projects for both export and import
  • Allows import of multiple projects at one time, and will copy from the ZIP file to a workspace location or to any other selected location

Disadvantages

  • No version control
  • No code merge capability -- replacement only if a collision is detected


Back to top


Conclusion

This article has described five distinct methods for sharing projects within Eclipse or WebSphere Studio. For a development team that requires version control and merge capabilities, it is best to use a repository to share projects. However, you may need to share projects with a developer who lacks access to your repository, or you may not be using a repository. If these cases, any of the remaining four methods will work.

Sharing an entire workspace can be cumbersome, and it forces you to adopt an entirely new workspace. If you are using WebSphere Studio and you want to share an application project and all of its module projects, you may be tempted to export an EAR file and import it and its contents into another workspace. But EAR export with metadata was never intended as a way to share application projects and it will not necessarily have the desired results. A better solution is to export the projects into a ZIP file and then import the contents back into a workspace, but then the import requires you to first unzip the contents and then import each project individually.

This article also described the new Project Interchange feature, which provides the best method for sharing projects when a repository is not feasible. Its simplicity, ease of use, and rich function make it an excellent solution for sharing projects.

Top of page




Back to top


Download

NameSizeDownload method
com.ibm.etools.project.interchange.feature.zip53 KBFTP|HTTP
Information about download methods


About the authors

Daniel Berg is a software engineer at IBM Research Triangle Park Lab in Durham, North Carolina. He is the lead architect for J2EE tools in WebSphere Studio Application Developer. You can reach Dan at danberg@us.ibm.com.


Ritchie Schacher is a software engineer at IBM Research Triangle Park Lab in Durham, North Carolina. He is a developer of J2EE tools for WebSphere Studio Application Developer. You can reach Ritchie at schacher@us.ibm.com




Rate this page


Please take a moment to complete this form to help us better serve you.



 


 


Not
useful		Extremely
useful
 


Share this....

digg Digg this story del.icio.us del.icio.us Slashdot Slashdot it!



Back to top