Setting up a team development environment

In this topic ... Locate and layout a project for source control management Decide what artifacts to version Manage Code for distribution Learn more about source control and team development Related Topics... Working with Projects Project Configuration and WAR Deployment

Factory applications, whether they are portlets, stand-alone applications, or web services, are simply a coordinated set of files that are used to regenerate applications at design- or deployment-time.

Like any development effort, the Factory project and application files should be placed under a source control system such as CVS, SourceSafe, ClearCase, etc. Placing these files under source control will allow you to version them and protect them from loss.

 

Locate and layout a project for source control management

We can locate a project anywhere in the file system, though it is common to place it in the Eclipse workspace (".../eclipse/workspace/"). When you create a Factory project with the Designer, all required sub-directories and files are created for you with the proper structure. We can use two basic approaches when translating this project structure to source control:

• Individual Project Approach - Each team member has a separate area in source control for their project artifacts (models, Java classes, Builders, etc.). The shape of this area should mirror the project structure.

This approach is useful if the projects have only loose coupling (e.g. http connections). Artifact names should be chosen to avoid collisions if the created artifacts are to be brought more close together (in a common build). If there is to be a common build, a build process will be needed.

• Shared Team project - There is one shared source control area that captures all the artifacts created by the team members. This includes all source files, all generated files, and all Factory shipping files (such as WARs). The shape of this area should mirror the project structure.

This approach is useful when several people are working on different parts of one application. Each developer has a copy of the Factory and checks his work into a common source control area. Every team member can populate their project with all artifacts if necessary, and name collisions are easier to avoid.

In both cases, mirroring the structure of the project in source control allows easy traffic between your source control system and the project.

 

Decide what artifacts to version

If you want the ability to re-create the application over the long term, it is important to capture all of the artifacts used by the project. There is obviously a continuum of software layers involved, (OS, JVM, Eclipse, Designer, etc.). You should at least capture in some manner the critical software pieces needed to enable a modification several years down the road. Cutting Vendor Distribution CD s or custom CD s provides a way to capture a snapshot of most of these underlying layers as well as the project artifacts.

At a project level, you have two choices for what to place under version control:

• Entire Project - Check in the entire project. Here source control will exactly mirror your working directory structure. This approach is easy, but depending on the features and performance of your source control system, it may prove to be too slow or cumbersome to use. Also, if you have a very large development team, this approach will consume a lot of space on your server.

• New/modified Files - Check in only the files you create or modify in your project. The Factory WebApp is removed from (and restored to) a project, so it is easy to see at any time what you have created or modified. When you create a project, it includes Factory shipping files, source files and all generated files. We can remove all the Factory shipping files by right-clicking on the project and choosing Factory WebApp Project > Remove.

Only your source files and generated files will remain in the project. We can check in the generated files (not recommended) or they can be created from the source later if you are trying to reproduce this exact environment. Generated files are located in: WEB-INF/factory/generated/. Using this technique we can have source files in source control and have each developer install the same version of the Factory Factory and any other shipping software needed for the project.  

If you use a Shared Team Project in source control and check in only new or modified files, setup a Proto-Project in your source control system that contains all the artifacts you share across team members and don t expect to modify (Jars, Builder Defs, Properties). That way we can create a project for a new team member by simply combining the Proto-Project and the Shared Team Project. There are many variations across these two dimensions (what to capture and how to shape it), of course.

At the very least, these are the project artifacts you should capture in your SCS:   

• Model files in WEB-INF/models/*.model

• Profile set files in WEB-INF/profiles/*.xml

• HTML files (*.htm, *.html)

• JavaScript libraries, CSS and XSL stylesheets (*.js, *.css, *.xsl)

• Image files (*.jpg, *.gif)

• Configuration files (*.properties, *.xml, Java resource bundles, etc.) except at the top level of the project.

• Java source files in WEB-INF/work/source/*.java

• Custom (client-specific) JAR files

• Custom Builder Definitions in WEB-INF/builders/*.bdef

• Custom Profile Selection Handler files in WEB- INF/config/selection_handlers/*.xml

• Build scripts for the project

• Project documentation

Do not capture or source control:

• Generated project artifacts - It is not necessary and not recommended that you capture and control artifacts that are generated by the Factory regeneration process (JSP s, Java classes, schemas,...). These are exactly like the binary outputs of compilers. If you preserve the source files (Models, Profiles, Builders, etc.), the generated artifacts are always reproducible. Generated Java files are located in WEB-INF/factory/generated; generated JSPpages are located in the /genjsp directory; generated Java classes are located in WEB-INF/factory/generated/genjava.

• Property files - For Shared Team Projects, do not source control the property files at the top level of your project (.bowstreet, .classpath, .project, etc.). These are user and system specific.

 

Manage code for distribution

Like most web applications and portlets, Factory applications are distributed (or deployed) as WAR s. Everything needed to run the application is packaged in the WAR build process, including Profile sets. The self-contained WAR file can thus be distributed or deployed to any appropriate server and expected to run.