     [file shared-setup.texi not included]

Get application working with WAS
********************************

The goal is just to get your application to successfully build a .ear that can run under WAS, without depending on anything from iPlanet.

Maybe this section could be skipped, and these iPlanet->WAS problems corrected at the same time as the port to WSAD, but I think it is far easier to attack one problem at a time.  This way, when porting to WAS, you do not need to be concerned about WSAD requirements; and when you get to the WSAD port below, you do not have to worry about WAS requirements.

Don't rearrange directories or locations of files at this point, because that should be done in WSAD (since the goal of the rearrangement is to satisfy WSAD).

  * If you want to use my build files, or any of the (important) features of Ant v. 1.5, then you will want to upgrade ant.

          [file ant-upgrade.texi not included]

  * Update your application to all utility jars as dependency libs. By utility jar, I mean any jar file that your application bundles but that you not use J2EE resources (like ejb's) from. If your team does not develop the jar, then just stick the jar file into the ear file and add Class-Path: entries to the MANIFEST.MF files of your depending modules. For example, if your application uses ejbCore.jar java classes, but doesn't use any J2EE components (like ejb's, servlets or datasources) that are inside of that .jar, then just stick it into the ear file. Your project will keep a copy of the binary .jar file in your PVCS project.

     If your team develops the jar, then do the same thing, but keep in mind when we get to WSAD that this will be represented as a Java project. Your project will keep the source files for this Java project in PVCS.

     Dependency jars reduce unnecessary interdependencies and simplify everything.

          Create a manifest file with contents like

               Class-Path: coreEjb.jar

          where you replace coreEjb.jar with the library that modules depend upon. You can put multiple Class-Path records in the file, or you can put multiple file names on the same Class-Path line (separated with spaces). Continuation lines begin with a space. N.b.  If you use continuation lines, be aware that the newline and single leading space are gobbled up, so you must supply an additional space to separate the last entry on the previous line from the continuation line.

       * Edit the war and ejb jar targets of your ant build file to use the file you created as the MANIFEST.MF file. (Most of the edits to the build file are below. To make things more clear, I'm putting all the dependency lib instructions here though.)

       * Edit the ear target of your ant build file to include the dependency library at the root level of the .ear.

  * Update the deployment descriptors to satisfy J2EE 1.3 and IBM, and to conform with Nextel conventions.

       * Update J2EE descriptors. Replace the XML headers with the J2EE 1.3 versions. Add ID's, remove unnecessary labels and login elements, remove <ejb-link> elements, etc., using the template descriptors (see below) as a guide.

       * Add the IBM-specific deployment descriptors to the directories that currently contain ias*.xml files.

       * Add references for all ejb's and data sources used in your Java code (below, you will have to update the Java code correspondingly). Unlike iPlanet, you can not get a data source or EJB without the reference records in the descriptor files.

          Ejb reference names should begin with ejb/. This is not a J2EE requirement, but if you violate this J2EE recommendation you will get validation warnings (for those in ejb-jar.xml).

          JNDI reference names should begin with jdbc/. I don't recall whether violation causes any warnings, but just follow the convention.

          N.b.  There is an equivalent convention for JNDI names, but don't confuse reference names and JNDI names. These are independent name spaces. Example:  coded reference name ejbc/alpha (coded as java:comp/env/ejbc/alpha) refers to JNDI resource ejbc/uno. Even though ejbc/alpha and ejbc/uno both start with "ejbc", the first is following the reference naming convention, and the latter is following the JNDI naming convention.

       * Bind reference ID's (defined in the J2EE descriptors) to JNDI names in the ibm-*-bnd.xmi files. Please begin all ejb JNDI names with ejb/. Please begin all data source JNDI names with jndi/. (The template descriptor files indicate this).

       * See Blaine's template deployment descriptors (http://admc.com/blaine/howtos/ws_desc).

       * Check your JNDI names. Grep through your descriptor files for each JNDI name that you are using. Each data source JNDI name should occur only once in ibm-*-bnd.xmi files (these say which JNDI resource that references point to; the resources to which the names are bound are defined in the WAS server itself). Each ejb JNDI name should occur twice in ibm-*-bnd.xmi files (these say which JNDI resource that references point to; and which ejb the name is bound to).

       * Follow the bean and reference naming conventions described at Blaine's WAS Primer (http://admc.com/blaine/howtos/ws50.html#Development).

  * To simplify things, remove the iPlanet descriptor files ias*.xml.

  * You can update and create descriptors graphically by using assembly.sh (aka AAT). In that case, start up assembly.sh and open the individual module .jar's and .war's. Get all modules to validate successfully (with the exception of the validator bug about "internal error".  See the WSAD Primer HOWTO about that). Then it's a simple matter to assemble the modules into an ear manually or with assembly.sh. I recommend that you do not use assembly.sh so that assembly.sh does not add classpath or other dependencies that you don't know about.

  * Edit the ant build file.

       * Add WAS-specific tasks, like for validating, creating stubs and skeletons, deploying. You can cut & paste these targets from Blaine's http://admc.com/blaine/howtos/nextelapp-build.xml (an ant build file). You'll also need this jacl script (http://admc.com/blaine/howtos/nextel-util.jacl) for the deployment targets (it is normally available at /app/iws/was/scripts/nextel-util.jacl on our development servers).

       * Use WSAD-supplied libraries where possible, and eliminate all iPlanet-supplied libraries. (In particular, I find that some XML-related Nextel Java code is satisfied by the WAS-supplied xerces.jar file.)

       * Eliminate all iPlanet stub/skel commands (ejbc) with ejbdeploy commands. ejbdeploy is easier to use since it takes a .jar or .ear as input, and it figures out for itself the names and types of the beans inside, and generates a new .jar or .ear. Therefore, the location of the ejbdeploy calls will be different than the ejbc calls you are removing.

       * Modify the ejb-jar and war file tasks to include the ibm .xmi descriptors instead of the ias .xml descriptors.

  * Update java code.

       * Make sure all objects passed by value are serializable.

       * Change data references to match those you set in the descriptor files.

       * Remove all throws of RemoteExceptions from all Bean implementation classes. Methods coded in bean interface files should declare

          N.b.  Our current strategy is for NOLConfiguration_en.properties to include the java:comp/env/jdbc/ prefix with the data source values. So, if you are using data source values obtained from the NOL configuration file, you can dereference that string directly. throws RemoteException, but not the methods in the implementation class. Code in a bean method may catch a RemoteException exception from the invocation of methods of other beans, but these have to be translated to some other exception type since implementation methods may not throw RemoteExceptions in EJB 2.0.

  * Make sure each class file is only bundled into one jar/war file. If you don't recognize the cause, this causes extremely puzzling symptoms. Unlike iPlanet, if you add a class to both an ejb jar and to a war file, you will get visibility problems which normally show up as class not found exceptions. If you need visibility to a class from both web and ejb module, then bundle it in the ejb jar file (since web modules have visibility into ejb jars) or into a dependency jar.

  * Invoke ant with the command ws_ant (or just ant if you are not using IBM-supplied ant tasks), not build. build is an iPlanet program which, primarily, sets iPlanet classpaths-- we definitely do not want iPlanet classpaths.

When you can deploy an ear to WAS and run it, it is in good enough to start working with WSAD. You probably want to put off detailed unit testing until you get things running in WSAD.

Get application working with WSAD
*********************************

To make your life easier

  * If you haven't already done so, read the Concepts section of my Making a new Nextel WSAD workspace HOWTO at http://admc.com/blaine/howtos/wsad-workspace-init.html#Concepts and http://admc.com/blaine/howtos/wsad-workspace-init.html#Conventions.

  * Stick to the J2EE Navigator view. This navigator makes it very easy to see your J2EE projects and subcomponents, and you will have all the necessary toolbar items available.

  * If you are new to WSAD, close editor windows whenever you finish your intended edits (not just code editors, but descriptor and other editors too). The problem with leaving them open is, you can't tell whether your changes have been saved or not. WSAD is very inconsistent about checking for open items when generating, building and compiling, so you could very well accidentally build with old code. In addition, some commands are disabled when certain editors are open (and WSAD gives you no clue as to why the commands are unavailable). It is a very common occurrence for new WSAD users to waste hours working on non-problems because they have editors open. Keep your workspace clean!

Set up NEXTEL_EXTLIBS directory for non-WSAD and non-JVM external libraries.

In most cases, you will bundle all of your non-WSAD and non-JVM libraries inside of your final ear. In that case, these are not "external" libraries, and you can skip the following sub-list. You will be instructed farther on when there are other instructions that you can skip (because you have no extlibs).

  * We shall set up WSAD to look for Nextel-specific external jar files in a specific directory, hereafter called NEXTEL_EXTLIBS. Jars not bundled in your .ear live here, like a log4j jar file (if it is not bundled in your .ear). Dependency libraries, or any jar files that will be bundled inside of your final .ear file are not external, they are internal--- so don't put them here. If you don't have a directory made for external jar files, then make one. Download, copy, or move external jars to this directory.

     There is a good chance that the jar files you need are available at /app/iws/was/extlibs on one of our UNIX servers.

  * Your application may use other external libraries supplied by your JVM or by WSAD. They are used where they are installed, so don't move them to NEXTEL_EXTLIBS.

  * The NEXTEL_EXTLIBS directory should not be inside of any WSAD workspace, since the goal is for this directory to be administered independently of any workspace.

  * IMPORTANT: Since multiple WSAD workspaces will use this external library directory, you must rename the jar files to contain a version number if there is any possibility that different projects will require different versions of that library. Example:  You could rename a version 1.2.8 of log4j.jar to log4j-128.jar

If your project co-develops any J2EE modules or utility jars that are bundled into your application ear, but that are stored under a different PVCS project than yours, then those modules should already be converted to WSAD. Check them out into your workspace as any developer would (see the Making a WSAD Workspace howto). (Later you will import these projects). In WSAD, these applications look exactly like the WSAD projects for modules from your own PVCS project. The big difference is, you are not converting them at this time and you will not check them into PVCS.

If your resultant ear is to include (meaning that it will be bundled inside of your resultant ear) an externally developed ejb jar or war file, and if your application will use J2EE component(s) from it, then you will use them exactly as imported by the ear file below, and you will not check anything in them into PVCS.

Non-development modules you bundle, and which do not have J2EE components which you are using, will be taken care of automatically. (They will be imported as binary jars within your ear module).

Start WSAD with a brand new workspace name.

Import the modified binary ear for your main project. This is the one that you created (and were able to deploy) in the Get application working with WAS section less the depended-upon development jars. We do not import the depended-upon development jars in this way because we want to retrieve them directly from PVCS. Besides creating most of your directory structure, this will automatically perform modifications to deployment descriptors to satisfy the requirements of WSAD (like adding id attributes).

  * Name the new WSAD project like "x-ear" (note that we use a hyphen, not a dot).

  * Accept all defaults, except on the screen "EAR Module and Utility JAR Projects" (and the exception in the next item below), rename each project so that every module name ends with one of the following extensions.

     -web
          For web projects

     -ejb
          For ejb jar projects

     -ear
          For ear projects

     -jar
          For utility jar projects

  * Important exceptions for utility projects. For development utility jar projects, do everything just like for ejb-jar and web projects, except

          At the Import Defaults screen during the import, change the Utility JARs and web libraries setting to import the utility jar as a development project. (Hopefully you don't have both binary and development dependency libs!)

       * Notice that it creates a directory named source. This is where you will add the packages that will contain your source files and other deliverable resources.

       * Also notice that it puts the META-INF directory inside the source directory. Don't try to move it-- WSAD will choke.

       * If you are going to provide a binary copy of the utility jar to outside developers, then go ahead and export a jar from this Java project. Write it to the "bin" subdirectory of the project. In the Jar contents window, make sure to de-select the META-INF directory. On the last screen, make sure you select the imported MANIFEST.MF file (which resides in the source/META-INF directory) as the manifest file.

  * FYI, besides the directories and folders that WSAD shows you, it also mades "Web Content/classes" for Web projects and "bin" for Java projects, both of which it keeps hidden.

  * Manifest Class-Paths should automatically be set correctly from your manifests, but do check them all. WSAD very frequently removes Class-Path entries from manifest files, and sometimes completely screws up the entries.

Use the J2EE Navigator.  Click on each imported_classes folder within each development project and delete. Leave binary projects exaclty as they are. (These are projects for which you will not have source code).

Import source code from the modules you are porting.

  * Somehow, download your source code tree, containing only source code. Remove all properties files, jsp, and static resources like image files, since these items import automatically via the ear import above. Do not download any deployment descriptors or anything under your scripts or samples directories. When you imported the .ear file, the deployment settings were imported. We do not develop scripts or samples with WSAD. (For leadgen, all this stuff is just everthing under src other than src/leadgen--- the latter containing the directories metadata, scripts and samples). You need to preserve the directory structure, so, when you download, use something like rsync, a tar ssh pipe, or zip and restore an archive.

  * Use WSAD to Import the Filesystem.

  * For "Directory", select the parent directory of all of your source (typically the parent directory of the directory "com").

  * Click "Select All"

  * For "Folder", select the "ejbModule", "Java Source" or "source" directory for the target module which should contain most of the classes (for ejb, web and java modules, respectively). If prompted about overwriting existing files, click "...No to all...".

  * This should make a "package" for each directory containing java file(s) (and .xml files, I think).

  * It will make a "folder" for each directory containing non-java file(s) (and non-.xml files, I think), like properties files.

  * BUG:  If everything doesn't show up, close and restart WSAD.

Move files around.  In the J2EE Navigator...

  * Create "packages" in "ejbModule", "Java Source" and "source" folders where you need to put source files and resources (with "Names" like "com.nextel.profile.frontend"). (Sometimes WSAD shows the non-.java file resources in "folders" instead of in the packages, but I think these are just duplicate views of the same directories... perhaps just with some specific navigators... I hope so).

     TODO:  Do some testing with non-.java resources.

  * Click and drag files (or entire packages/folders) from your import target's packages/folders to the desired packages and folders You know the desired target module by the ejb-jar file or war file that you need the final resource (class file, property file, etc.) to end up in. If you are moving a file to an equivalent package (i.e. from package a.b.c in one module to package a.b.c in another WSAD directory branch), then tell WSAD to not update the references. WSAD assumes (incorrectly) that your package name is changing just because you are moving files to a different directory. To move an entire package or folder, click and drag the package or folder onto the target containing ejbModule, JavaSource or source item.

  * Using the navigator, delete any empy packages or folders. Specifically, ibm.ibm.* and org.omg.*.

IMPORTANT:  When specifying external libararies, do not use the Add External JARs button.  That would add a non-portable dependency about your local filesystem.

Tell each module about needed WSAD- or JVM-supplied libraries (e.g. xerces.jar).

  * Right-click on the module name and click "Properties".

  * Select "Java Build Path" in left panel.

  * Click the "Libraries" tab and use the "Add Variable" button.

  * Select an item if it's there. (Say No if WSAD suggests that you rebuild everything).

  * If not, select an existing directory variable like WAS_50_PLUGINDIR and "Extend" it by supplying the rest of the path to the resource. (Most WAS libraries can be found at WAS_50_PLUGINDIR/lib. WAS_50_PLUGINDIR is the directory runtimes/base_v5 under your WSAD installation base.) (Say No if WSAD suggests that you rebuild everything).

     (If adding xerces.jar, be aware that WSAD has two of them. I have had better success with WAS_V5_XERCES, the one in WAS_50_PLUGINDIR, and that is the one available with WAS server. The pre-defined variables for xerces libraries are for an older version which will generally not be available on our UNIX servers.)

Define variable NEXTEL_EXTLIBS.

You can skip this and the next sub-list if you have no extlibs.

  * Right-click on a module name (of a modules that needs an external Nextel jar) and click "Properties".

  * Select "Java Build Path" in left panel.

  * Click the "Libraries" tab and use the "Add Variable" button.

  * Click the "New" button.

  * Enter NEXTEL_EXTLIBS and a path to the directory.

  * You still can't save the variable until you use this variable to add a specific .jar file to the build classpath by using the "Extend" button. (Say No if WSAD suggests that you rebuild everything).

  * FYI, libraries which use a variable for the path are shown with a ball icon instead of a jar icon.

  * Classpath variable definitions that you make are stored at $PROJHOME/.metadata/.plugins/org.eclipse.jdt.core/pref_store.ini

Tell each module where to find all libraries that it needs from NEXTEL_EXTLIBS.

  * Right-click on the module name and click "Properties".

  * Select "Java Build Path" in left panel.

  * Click the "Libraries" tab and use the "Add Variable" button. Select NEXTEL_EXTLIBS and Extend it to add the desired .jar file. (Say No if WSAD suggests that you rebuild everything).

For each web module, you will have a folder named Java Source. In the J2EE navigator, right-click on every Java Source folder and rename the folder to JavaSource (with no space between the two words).

Tell modules which ejb modules are depended upon (in order to build successfully).

  * In the J2EE navigator, right-click on the module name and click "Properties".

  * Select "Java Build Path" in left panel.

  * Click the "Projects" tab and click the individual modules that you need). (Other modules should not be dependent upon web modules).

If you downloaded any development modules from other PVCS projects (as instructed above), then import them as Existing Applications into your workspace. Use the same module name as the module directory in PVCS. This procedure is explained in the Making a WSAD Workspace howto. Then edit the following items in WSAD.

     application.xml descriptor for your .ear
          Make sure that the development module is included in the .ear. For wars, specify a context root.

     module properties
          For each module that uses a co-developed modules, right click on its name in the J2EE Navigator, bring up the properties window, select Java Build Path and the Projects tab and click the checkbox for the depended-upon project.

If you downloaded jars and/or wars to install as binary project(s) (as described above), then import them now.

  * Import the .jar or .war file into a new binary project in your workspace. Name the new PVCS project exactly as the module directory is named in PVCS, like "x-web", "y-ejb" or "z-jar".

  * N.b.  I have run into a bug more than once, that after importing a binary jar file, WSAD wipes out all of the .class files (perhaps when building the first time). The work around is to go into the new .bin directory and extract from the jar file manually. This will restore the .class files, and WSAD behaves itself thereafter.

     Then you need to edit the following items (perhaps by double-clicking them in the J2EE Navigator).

     application.xml descriptor for your .ear
          Make sure that the binary module is included in the .ear. For wars, specify a context root.

     module properties
          For each module that uses the binary project, right click on its name in the J2EE Navigator, bring up the properties window, select Java Build Path and the Projects tab and click the checkbox for the binary project.

Your goal is to successfully build everything and export a good ear file.

You need to get the pulldown menu Project/Rebuild All to work without producing any errors in the Task window.

Select the -ear module in the Navigator window and use the Generate EJB Deployed Code toolbar button before you export the ear.

Fix problems as they arise. Your task bar will probably have a long list of errors when you start.

  * Select items in a sequence determined by project dependencies and severity.

  * Fix high severity items which are needed by other items first.  On a large scale, this means to fix Errors in utilities first, utility ejbs, other ejbs, wars.

     If ejb A depends on ejb B, then fix ejb B first. (There should not be circular dependencies).

     You can take care of warning and informational tasks after the errors are taken care of.

  * Double-click items in the "Task" window.

In many cases, WSAD doesn't preserve the classpath dependencies to binary jars within the ear. In that case, select the desired jar file(s) from Properties Editor / Java Build Path / Libraries / "Add JARs". If you add dependency libraries to your ear manually (as opposed to importing in the dependency lib or the project for it), then, for each depending module, you will have to update the MANIFEST.MF (as well as Adding the jars as just explained).

Make your work available to others
**********************************

Get your new PVCS repository set up
-----------------------------------

Our purpose is to upload stuff specific to your project. If you have WSAD projects (whether binary or development) that you made by importing from existing PVCS projects, just ignore those projects and directories for the purposes of this section. (I.e., if you downloaded some other team's module, you surely don't want to upload those artifacts to your project). The only exceptions to this are binary dependency libs that you use, jar files that you are providing for others' use, and externally assembled jars/wars to be included in a war's WebContent/WEB-INF/lib directory. In that case, you will check the utility .jar into PVCS in the following locations.

binary dependency libraries that you use
     Check them into PVCS right where you use them from--- the -ear directory.

binary libraries that you use in WebContent/WEB-INF/lib
     Check them into PVCS right where you use them from--- WebContent/WEB-INF/lib.

wars and/or jars that you need to make available for outside developers.
     To make these, you use WSAD to Export the Jar/War/Ejb-jar the jar to the "bin" subdirectory of the same project. You will check these binaries into PVCS like the rest of your source code.

You should have a new PVCS repository project made. You will not want to continue working with the PVCS archive files that were used for IWS, because all of the files need to reside in different locations (based on the WSAD directory tree layout).

Make a list of the the directories you will need. You can see my list for the leadgen project at http://admc.com/blaine/howtos/pvcs-add.txt. Note that only directories that really contain files need to be added to this list. E.g., for leadgen, there are files in com/nextel/profile, but not in com nor com/nextel. You'll need to look ahead to the Check in your workspace files subsection to see exactly which files need to be stored in PVCS.

If other parties will use binary wars or jars from your project directly (i.e., they will not get source and rebuild them), then create a "bin" subdirectory off of each module directory which will contain the war/jar, for example mymodule-ejb/bin.

Make sure that you add directories scripts and samples off of the project root to your list.

For any web modules which contain externally assembled jars or wars that you use out of WebContent/WEB-INF/lib, you must have a PVCS directory for WebContent/WEB-INF/lib, so that you can check in those files. (If you have a development project in your workspace for that library, you will keep these jar/wars in PVCS only if you need to provide them for other development teams, since your development project will create them-- In this case, just make sure to add the development project names to the 'weblib-modules' setting in the module.properties file, as explained below).

Include the directory list in your request to your PVCS manager.

Make sure that you also ask the PVCS manager for permission to create labels in depended-upon projects (see the Label subsection below).

After the PVCS project and the directories are created, the VM interface is used to create PVCS VM folders with names that match 1:1 to the directories in the list. (Depending on your situation, it could be you or your PVCS manager that does this. If the PVCS manager does it, make sure that they understand how the folders need to be mapped to the directories). The VM folder name should be exactly the same as the directory name AFTER the archive directory (with the exception explained in the following paragraph). E.g., for leadgen I made a folder /leadgen.ear/META-INF to correspond to the archive directory /prj/nol/projects/leadgen_leadgen/archive/leadgen.ear/META-INF. Later on you will use the VM interface to add your files into the folders. (Since they are mapped 1:1 to the archive directories, your files will end up in the corresponding archive directories).

There is one exception to the rule that VM "folder names" should exactly match the PVCS directory name. For each directory in your WSAD workspace like "*-web/Web Content", you remove the space from the corresponding PVCS folder name. I.e., the corresponding PVCS folders are named like "*-web/WebContent". Therefore, the VM folders for these directories must map PVCS directories named "WebContent" to VM folders named "Web Content". (We should create the PVCS directory with name "Web Content", but VM can not handle that).

Check in Scripts and Samples
----------------------------

Scripts and samples are not developed using WSAD. The scripts and samples files should not exist in your WSAD workspace. Just check all the samples and scripts files out from your original iPlanet PVCS project (not into any WSAD workspace!), then use VM to check them in to the scripts and samples folders your new project.

External non-WSAD and non-JVM jars
----------------------------------

By non-WSAD and non-JVM, I mean jars that are not supplied with WSAD nor your Java JVM.

Upload the external jars needed by the app, i.e. all the jars in NEXTEL_EXTLIBS to /app/iws/was/extlibs on our development servers, and make sure you name them uniquely as documented at /app/iws/was/extlibs/README.TXT. Do not overwrite an existing file in that directory!

module.properties files
-----------------------

Every WSAD development project that you have (i.e. every -ear, -web, -ejb, -jar project that is not a binary project) must have a module.properties file to specify project dependencies (as well as several other things needed by the ant builds).

It is vitally important that you update every module.properties file with accurate lists of depended-upon modules and needed jar files. When new WSAD developers download your ear module, they will look into the module.properties file to see what other modules they need to check out and what jar files they need to download.

     [file modprops.texi not included]

Your module.properties files must contain the following values. Multiple entries must be separated with commas (and optional spaces).

depend-on-modules.dev
     Modules that this module depends on, and for which you will have source (.java file) access. A depended-upon dev module may reside in PVCS under your main PVCS project or it may be a co-developed project that lives under some other PVCS project. (I repeat for emphasis-- you must even list the depended-upon modules which live in the same PVCS project).

depend-on-modules.bin
     Modules that this module depends on, and for which you will no have source (.java file) access. These normally come from the bin directory in some other PVCS project, but could possibly be generated from a war/jar file at /app/iws/was/bundledlibs on a development server.

extlibs
     Jar files needed by this module which reside in NEXTEL_EXTLIBS.

waslibs
     Jar files needed by this module which reside in WAS_50_PLUGINDIR (i.e., runtime/base_v5 under your WSAD installation directory).

weblib-modules  (for -web modules only)
     Development modules whose output jar/war file should be bundled in this module's WebContent/WEB-INF/lib directory. (These modules should also be included in depend-on-modules.dev, since this module depends on them). There is no corresponding property for binary modules, because, if you want to include an externally generated jar/war file in WebContent/WEB-INF/lib, you just check that file into PVCS in that location.

warfile or jarfile or ejb-jarfile or earfile
     The name of the file assembled from this module.

Label depended-upon resources
-----------------------------

Decide on a label for the first production release of your ear file. You probably want to increase the major revision number from the current iPlanet label (e.g., LEADGEN_2_3 on iPlanet to LEADGEN_3_0 on WAS). When you eventually do release a production ear, you will label all component PVCS artifacts with this label (under your PVCS project, and in other depended-upon projects).

IMO, it is easier to do development work using the tip (i.e., null label), just creating labels when you are ready to make a jop.  But you do need to create labels right now to identify what version to retrieve of depended-upon binary projects (and depended-upon development projects for which you want non-tip versions). Typically, you will not want to get the tip of depended-upon binary projects, because the success of your builds will then be dependent upon the vicissitudes of release schedules of external projects.

For all depended-upon binary projects, and desired depended-upon binary projects, label all used artifacts with your first anticipated label (the label you will use when you label your own source code the first time). For development projects, you will normally tell PVCS to label everything labelled with an existing label (e.g., label everything that has label CORE_4_3 with label LEADGEN_3_0).

Check in your workspace files
-----------------------------

You check all this into the PVCS folder that corresponds to the directory in your WSAD workspace.

For all of the development projects now in your workspace (which correspond to modules that you are putting into PVCS under your main project), check in all source files, dependency libraries, externally-created web utility libraries, properties files, deployment descriptors, module.properties, metainf files and the following four WSAD "dot files" into PVCS.

.project (one for every web, ejb and ear project)
     Contains project names

.modulemaps  (one for every ear project)
     References id's in application.xml

.classpath   (one for every web and ejb project)
     Paths seem to be

       * Relative to the module home

       * Relative to the ear home (if path begins with /)

       * Relative to a leading variable (if kind is "var")

.websettings (one for every web project)
     Duplicates info in application.xml

It is critically important that you do not check the following files into PVCS. These items should not be under change control.

binary projects
     Nothing at all in any binary project. Binary projects are just copies of projects managed by some other development team.

co-developed projects
     These should already have a home in PVCS somewhere.

.metadata/...
     The .metadata directory and anything underneath it.

derived files
     Files derived from other files that you are checking in, like .class files. You should not have any .war, .jar, or .ear files in your workspace that are derived from your source. This includes derived dependency libraries and jars/wars in binary projects and in WebContent/WEB0-INF/lib directories (Normally, WSAD only writes these files to disk when you explicitly export them).

stub/skel source (or class) files
     These files are of the form  _EJS*.java, EJS*.java, *_Stub*.java, *Tie.java.

Build your application on server from PVCS sources
**************************************************

See the WAS Ant Builds at Nextel HOWTO at http://admc.com/blaine/howtos.