     [file shared-setup.texi not included]

This document explains how to retrieve needed resources using PVCS VM-Inet. If you are using CVS instead of PVCS, see the Nextel at CVS HOWTO at http://admc.com/blaine/howtos.

Concepts
********

WSAD Workspace Layout
---------------------

Your WSAD workspace will hold a variety of different objects.  If you understand the difference between these different type of objects, things will make much more sense to you.

In a normal WSAD setup, the workspace directory contains the following immediate subdirectories.

.metadata
     The .metadata directory is managed by the WSAD program and is specific to your computer. You never copy data from another workspace or computer into a .metadata directory. You will probably never want to manually change anything under .metadata.

PVCS Project Directories
     Each immediate subdirectory of your workspacce directory, other than .metadata, is a root directory for a PVCS project. Be aware that you could have PVCS project directories in other places also (especially for Server and other configuration projects).

This document concentrates on Nextel's use of WSAD Java and J2EE projects. Here at Nextel, we name our WSAD Java projects like "w-jar", our web projects like "x-web", our ejb jar projects like "y-ejb", and our ear projects like "z-ear". These project are rooted in directories of the same exact name, which normally live right in the workspace directory.

PVCS projects
-------------

Here at Nextel, our PVCS projects do not correspond directly to WSAD projects. I repeat-- our PVCS projects do not correspond directly to WSAD projects. On the contrary a Nextel PVCS project corresponds to a set of WSAD projects-- normally an ear application and some component J2EE and Java modules.  For example, the PVCS project leadgen consists of the following modules:  leadgen-ear + parampasser-web + profileentry-ejb. The top-level directory for the leadgen PVCS project contains the directories leadgen-ear, parampasser-web and profileentry-ejb, each of which is the root of the named module. (Note that the leadgen project could also depend on other modules which are controlled under different PVCS projects).

In this context, we call ear and java utility subprojects modules, even though they are not J2EE modules. When we are discussing Nextel PVCS or WSAD layout, we consider all Java, Ear, Web and Ejb jar projects to be modules.

Development vs. Binary WSAD projects
------------------------------------

WSAD Development Project
     As explained above, if a module is under source code control, then it will live in a subdirectory name like *-web, *-jar or *-ear immediately under the main PVCS directory for the PVCS project.

     If your team develops or uses a module with source code, then you will create a PVCS Development Project for that module. You will check out the source code and other artifacts from PVCS into a directory of the same exact name right in your main workspace directory. You will then import it with WSAD to make a WSAD development project out of it.

     Note that the module that you check out may be under your main PVCS project, or under some other PVCS project. We have many modules which are developed jointly by multiple development teams, and those jointly developed projects have to live under just one PVCS project.

WSAD Binary Project
     If your application uses some other module, but you do not compile that other module, then you will not make a development project for that module. If you use the other module just as a utility library, then see the next item. If you use J2EE components of the other module, then you must create a binary project for it. You obtain a binary jar/war file and import it into WSAD as a binary project. Normally, these jar/war files are made available in the "bin" subdirectory of the PVCS project module where that module lives.

Shared Development Project
     A Shared Development Project is just a WSAD Development Project that is developed by more than one application development team. This is an important distinction only because these projects should not have dependencies on any particulat application, because they would then not work with other applications. Shared dev projects may depend on other shared dev projects, as long as this dependency is understood (i.e., anybody developing one shared project will have to check out all the depended-upon dev projects too), but they should not depend on any application.

Utility Libraries
-----------------

Utility librares are utility libraries by virtue of how you use them, not of what they contain. If you use J2EE components like servlets or EJB's from a war or jar file, then you are using it as a J2EE component. If you are not using any J2EE components from a war or jar, then you are using it as a utility library. If your team compiles the utility library, then you will create a development WSAD Java project for it, just like you would for a web or ejb-jar development project. But if you just use a utility library compiled and assembled by some outside party, then everything is greatly simplified. We call these binary utility libraries. You do not need WSAD projects for binary utiliity libraries at all-- the using module stores the library in PVCS just as if it were a source file.

We support the two recommended means of using utility libraries in J2EE 1.3.

web utility library
     This is a jar (or possibly war) file that lives in the .../WEB-INF/lib directory within a web application .war file. If you develop a utility library, then you will check out the module and import it as a development project, like you would a J2EE module--- WSAD will know to generate a war or jar file and put it into the using web app's WEB-INF/lib directory. If you use a binary utility library, the jar/warfile will get checked out to WEB-INF/lib automatically when you check out your module.

dependency library
     This is a jar (or possibly war) file that lives in an ear module, and which is referenced by Class-Path statements in the modules that use it. If you develop a utility library, then you will check out the module and import it in as a development project, like you would a J2EE module--- WSAD will know to generate a war or jar file and put it into your ear file. If you use a binary utility library, the jar/warfile will get checked out to the *-ear directory  automatically when you check out your ear module.

Change Control Labels
---------------------

When a release is cut, all of the PVCS artifacts will be be labeled with the same exact label.  For example, version 2 of the webcare ear is built with PVCS artifacts from different PVCS projects, and all of these artifacts are labelled with the single label WEBCARE_2_0. There are source files in the modules under the webcare_websphere PVCS project, as well as the coreEJB.jar file kept in the core-ejb module of the core_websphere PVCS project.  To accomplish this, somebody on your project needs permission to create the labels on your own source files, as well as permission to create labels in depended-upon projects (either the development directories or the bin directories, depending on whether you use it as a development or binary project).

Usually, developers work with the tip (aka head) branch, i.e., the null label, for the modules under their main PVCS project.  But for depended-upon binary projects, we typically want to work with the latest version labelled for our project. For example, if the last production release of webcare was 2_1, and I am developing with the tip of webcare, I would check out all of the tip code from the webcare_websphere PVCS project, and the WEBCARE_2_1 versions of depended-upon binary projects. Depending on what a developer is working on, they may or may not want the tip version of depended-upon development projects. When you use VM to check out depended-upon projects, remember to get the right versions by specifying the appropriate label.

Since jops are typically built and assembled using a single label from your main project, all depended-upon projects normally have labels for all depending projects.

Prerequisites
*************

  * You need access to the PVCS repository with privileges to check out all of the files for the PVCS project.

  * You need access to the external libraries which you will need to download for your application. (External meaning that they won't be bundled inside of your final .ear file). These are typically available at /app/iws/was/extlibs on our development servers.

  * Excepting dependency libraries (which will be retrieved along with the source code from your prject), you need access to all jars/wars to be bundled inside of your application .ear file (and which are not derived from your source code).

     These are normally available in PVCS in the "bin" directory of the module directory of the containing project. If the jar/war is not available in PVCS, then it may be located at /app/iws/was/bundledlibs on a development server.

WSAD Workspace Initialization
*****************************

  * Make a new directory for your workspace (perhaps a peer directory to other WSAD workspaces that you have). The name doesn't matter, other than it'll make things a little simpler if you don't use spaces or other funny characters in it. (You don't actually have to create the directory, since VM can make it in the next step... but do decide on a directory name).

  * Use the PVCS VM web interface to check out all of the files for your project into the new workspace directory. The files should be retrieved in the same directory hierarchy as that of the VM folders.

     PVCS v. 6.x
          Go to the Project Contents page for your project in VM and select all folders other than samples and scripts and click the Check Out button. (Wouldn't hurt anything to retrieve the samples and scripts folders, but that just makes more unnecessary files to keep track of). On the Checkout page, in the Workfile Directory section, enter the absolute path to your new workspace; and check the Remember workfile... checkbox. In the Make Workfile section, select Read-Only. Select Yes to all if asked about creating non-existing directories. (You will normally not specify a label when checking out from your base PVCS project, because you want to work with the tip, or head, branch).

     PVCS v. 7.5

  * Take a look at all of the files named module.properties in each direct subdirectory of your new workspace directory. You will notice that each module.properties files has a (possibly empty) setting for depend-on-modules.dev. You need to compile a list of the union of the depend-on-modules.dev values across all of your modules (i.e. across all of the module.properties files). Exclude from the depend-on-modules.dev list the modules which got downloaded with your PVCS checkout.

  * Repeat the checkout procedure above for all development modules needed for your application. These are the depend-on-modules.dev, less those that are modules within your main PVCS project. You'll have to log into the PVCS project containing the desired module with VM, then select the desired module and check it out. You will typically not enter a label, but if you want to work with a frozen version of this depended-upon source code, you can enter the latest label for your project. For example, if your project is leadgen and you are checking out a depended-upon development module, you could use the latest LEADGEN_X_Y label in the depended-upon module.

  * Go through the module.properties files for the development modules that you downloaded in the previous step. Go ahead and use VM to checkout any more development modules listed in the depend-on-modules.dev for these modules (that you don't already have) and repeat until you have no more unsatisfied depend-on-modules.dev.

  * Now go through all of the module.properties files in your workspace and make a union of all of the depend-on-modules.bin values. Your union list of depend-on-modules.bin tells you all of the binary projects that you need. These are J2EE modules that you will bundle into your application, but which you do not need development access to. If your depend-on-modules.bin list isn't empty, then download the jars/wars to a temporary location (later on you'll import them).

     These are normally available in PVCS in the "bin" directory of the module directory of the containing project. Note that, unlike with development projects, you are just downloading the files from bin directories in PVCS, not whole modules. When you check out, enter the latest label for your project. For example, if your project is leadgen, then you should enter the latest LEADEN_X_Y label when checking out from all depended-on binary projects. If a jar/war is not available in PVCS, then it may be located at /app/iws/was/bundledlibs on a development server.

  * Now go through all of the module.properties files in your workspace and make a union of all of the extlibs values. Add to this a union of the depend-on-modules.dev and depend-on-modules.bin of (just) your shared development projects (see the definition above). This tells you all of the external libraries that you need. If you don't need any extlibs, then skip the rest of this item. Download all external libraries to a directory hereafter known as NEXTEL_EXTLIBS. Go ahead and make a new directory if you don't already have one for the purpose. These are typically available at /app/iws/was/extlibs on our development servers. These are the external libraries needed by your application, but not included with your JVM nor with your WSAD software. They are normally available at /app/iws/was/extlibs on our development servers. The NEXTEL_EXTLIBS directory on your workstation should not be inside of any WSAD workspace, since the goal is for this directory to be administered independently of any workspace.

  * Start up WSAD with the new workspace. Close the Welcome view in the main editor frame (with the "x" in the tab).

  * Use the J2EE perspective and the J2EE Navigator when working with J2EE projects. (This makes it easy to see exactly what is in the workspace, and you will have the needed toolbar available). Right now, the J2EE Navigator should show no projects at all (because you haven't imported your projects yet).

  * IF YOU HAVE NO EXTLIBS, THEN SKIP DOWN TO THE ITEM BEGINNING WITH "Import all *-web,...". You only need to do the next four items if you have extlib(s).

     Create a temporary "Java project".  (You are only doing this so that your source-controlled projects do not get modified when you make the temporary setting below).

  * On the first screen, enter any name and ENTER (or click "Finish").

  * Close the perspective opened for the Java project and return to the J2EE perspective with the J2EE Navigator.

  * Define variable NEXTEL_EXTLIBS.

       * Right-click on your temporary project name 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.

       * Pick a jar file of any type (or a zip file) in the directory. (If there's not one there, then just touch a new file name. Contents of the file make no difference at all).  You can then "Ok" to save the new variable.

       * Do NOT rebuild when prompted to do so.

       * 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

  * Delete the temporary Java project.  (Click "Also delete contents under..."). We just needed it in order to define the variable.

  * Import all *-web, *-jar and *.ejb modules in your main workspace directory as "Existing Project"s. Run File/Import/Existing-Project... for each of these. (These are the development projects from your main PVCS project plus all of the depend-on-modules.dev projects).

  * If your project needs any binary projects, then you need to create them with the jars/wars that you downloaded for this purpose earlier (according to your depend-on-modules.bin union list).

       * First, you must use some outside means (like Windows Explorer or the DOS or Cygwin command line) to make the following files writable.

            * *-ear/.project

            * *-ear/META-INF/.modulemaps

            * *-ear/META-INF/application.xml

          Do not check these files out of PVCS with a lock! We need them writable just to satisfy some unreasonable requirements of WSAD-- we will restore the original 3 files when we are finished.

       * Import the .jar or .war file into a new project in your workspace, naming the project exactly the same as the module directory in PVCS. This name will have a suffix of -web, -jar or -ejb. On your EJB Import screen, you will set EJB project to New with the name just describe; and set Enterprise application project to Existing, using the Browse... button to select your ear project. Then click Finish, since we want the defaults for all the following screens. The import will probably produce error tasks-- they should go away when you restart WSAD later on. (You will repeat this procedure for every binary project, of course).

       * 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 -xxx directory and extract from the jar file manually. This will restore the .class files, and WSAD behaves itself thereafter.

       * When you are finished with your import(s), re-check-out the three files above. On the VM Check Out page, set Make Workfile to Read Only, and set Overwrite Workfile to Always.

  * Exit WSAD and restart with the same project. (This is a workaround for a bug, and also has the benefit of causing WSAD to see changes to files that you may have made outside of WSAD).

  * Use pulldown menu Project/Rebuild-All. Fix any errors that come up.

  * If you have any shared development modules with any depended-on-modules.devs, export those jars and/or ejb jars to your extlib directory. (You will have a module for each depended-upon-module.dev in this workspace). The purpose is just to make sure the jars in extlib, which are used when you do builds, are up-to-date.

  * Select the *-ear module in the Navigator window, and hit the "Generate EJB Deployed Code" toolbar button.

At this point you can successfully export a fully functional .ear file that will run on a WAS server. In order to run this application (or pieces of it) on your local lightweight WAS server, you need to create a Server Configuration and set up your data sources. You start this process with Ctrl-N / Server / Server&Configuration / Next.

iPlanet Plugin Configuration
****************************

(This section contributed by Larry Hileman. larry.hileman@nextel.com).

Installing iPlanet plugin for Websphere Studio (Windows 2000) using iPlanet Web Server 6.

Step 1
------

Create new web server instance.

In the magnus.conf for the web instance created  add the following two lines to end of file:

        Init fn="load-modules" funcs="as_init,as_handler,as_term" shlib="C:/Program Files/WebSphere/AppServer/bin/ns41_http.dll"

        Init fn="as_init" bootstrap.properties="C:/Program Files/IBM/WebSphere Studio/runtimes/base_v5/config/cells/plugin-cfg.xml"

In the obj.conf  add one line within the <Object name=default>:

         Service fn="as_handler"

Step 2
------

Install WebSphere App server v5.0.

 1. Select custom install

 2. Check only Web Server plugin for iPlanet only.

 3. During installation, give web server info for instance created above.

Step 3
------

Modify  runtimes\base_v5\bin\setupCmdLine.bat to point to your WSAD v5 runtime path:  for example -

     SET WAS_HOME=C:\Program Files\IBM\WebSphere Studio\runtimes\base_v5
     SET JAVA_HOME=C:\Program Files\IBM\WebSphere Studio\runtimes\base_v5\java

Step 4
------

Copy  plugin-key.*  (4 files) from where you installed the WebSphere plugin.

     C:\Program Files\WebSphere\AppServer\etc\plugin-key.*
     to
     C:\Program Files\IBM\WebSphere Studio\runtimes\base_v5\etc

subsection Step 5

From DOS command prompt run

     C:\Program Files\IBM\WebSphere Studio\runtimes\base_v5\bin\GenPluginCfg.bat
     This will create
     C:\Program Files\IBM\WebSphere Studio\runtimes\base_v5\config\cells\plugin-cfg.xml

subsection Step 6

Port 10080 is the port for the web instance created in step 1.

Modify C:\Program Files\IBM\WebSphere Studio\runtimes\base_v5\config\cells\plugin-cfg.xml

     Add  <VirtualHost Name="*:10080"/>   to VirtualHostGroup.
     Add  <Uri AffinityCookie="JSESSIONID" Name="/coreWar/*"/>  to UriGroup.

subsection Step 7

Port 10080 is the port for the web instance created in step 1.

In WSAD, go to server configuration view,  ports tab. Add entry to cell settings (host alias list):

        hostname -  localhost
        port          -  10080

Conventions
***********

     [file conventions.texi not included]

Updating Binary Modules
***********************

For development modules, updates are very easy.  You just use VM to check out everything from the corresponding module from whatever PVCS project it belongs to.

You have to do some manual work to update binary projects. In particular, WSAD demands to make changes to our stuff during intermediate states (i.e. after we remove the old but before we add the new), so we must work around that.

  * First check in all work to PVCS (from your other projects, since we don't want WSAD's useless modifications to those projects to get mixed in with your intentional changes).

  * Remove the binary project and resources beneath.

  * Say to not update links.

  * Download binary jar/war file from the binary project (it should reside in the bin subdirectory of the module in PVCS).

  * Open up write perms on all files in your workspace.

  * Import the ejb jar or jar file file, specifying a new destination project of the same exact name that you removed earlier.

  * Use VM to check out all of your dev projects again, overwriting your current files.