Grouper Developers Forum

Apologies for cross posting. The message below was posted to the new 

 mailing list. If you have any comments please make them to that list.

At the recent conference call discussing UI methodology I took on an action 
item to 'draft conventions for directory layout of and build procedures for 
I2MI source code packages'.

Below, I will outline the conventions I have currently adopted for the 
Grouper UI and how I normally set up my development environment.

I use Ant for my build scripts so I can use them on Windows and Unix 
platforms.

My Grouper UI development environment consists of 4 separate 'projects' 
maintained as separate CVS modules:

grouper-0.5     The grouper API
grouper-ui      The core Grouper UI
uob-grouper-ui  Bristol customisation of core Grouper ui
i2mi-subject    Bristol implementation of I2MI Subject interface for 'person'

The build process must combine files from all 4 projects into a directory 
structure defined for Web applications in the Servlet specification:

<webapp name>     Usually the first part of the URL by which the web 
application is referenced
                  content which can be accessed directly e.g. images and html 
files are placed here
                  or in sub directories

    WEB-INF       Resources needed by the web application which are not 
directly accessible
                  from a URL are placed here e.g. web.xml
       
        classes   Compiled Java classes and other resources which are 
intended to be found on
                  the web application class path are located here
                 
        lib       JAR files containing necessary Java Libraries and resources 
are located here

The majority of JSP files for the Grouper ui are not intended to be accessed 
directly - a Struts' action should be called first. For this reason JSPs are 
located in a WEB-INF/jsp directory in Grouper.

grouper-ui has a directory structure which resembles the web application 
directory structure.

grouper-ui
    java
        src
        lib
    resources
        grouper
        i2mi
    webapp
        grouper
        i2mi
        WEB-INF
            classes
                resources
            lib
            jsp

webapp and below conform to the web application directory structure.

Running the build script:
  1) compiles java classes to WEB-INF/classes
     for development I compile the grouper-0.5 sources
     for deployment I should copy the JAR files
  2) copies JAR files from java/lib to WEB-INF/lib
  3) copies ui resources from resources to WEN-INF/classes/resources
     they are copied because Eclipse might otherwise delete them and 
     some configuration files may have tokens substituted when the are 
     copied - filtering in Ant speak
  4) copies grouper configuration files to WEB-INF/classes
     build.properties has a property 'grouper.folder' which defines where 
Grouper is installed
  5) If 'additional.web.xml' is configured in build.properties
     i.e. 
additional.web.xml=${basedir}/../uob-grouper-ui/webapp/WEB-INF/web.uob.xml
     merge the specified file with the grouper-ui file.


Of my 4 projects:

grouper-0.5
grouper-ui
uob-grouper-ui
i2mi-subject

grouper-ui can reasonably expect to know something of the directory structure 
for grouper-0.5,however, unless I impose a directory structure on the other 
projects (which I don't want to do), we should make no assumptions about the 
structure (or even number) of other projects which the build script may need 
to combine into a single web application.

To this end the grouper-ui/build.xml script checks for a property (derived 
from grouper-ui/build.properties):
additional.build=${basedir}/../uob-grouper-ui/additional-build.xml

If set, the value for additional.build is taken to be the location of another 
build script which should be called at the appropriate point. This build 
script is responsible for building any additional projects and moving files, 
as appropriate, to the build directory.

This configured build script must specify some equivalent targets to those in 
the grouper-ui/build.xml file (so that partial builds can be run), and must 
build to a directory specified by the property 'webapp.folder'.

This approach ensures loose coupling of Grouper to other components.

Although I don't want to impose a directory structure, some principles should 
be followed:
1) Don't copy files over existing grouper-ui source files - use the extension 
mechanisms
2) Place resource and content files in new subdirectories so that it is 
obvious where files originate

The grouper-ui structure above has subdirectories for grouper and i2mi. The 
i2mi directory was added with a view to sharing some components across 
Internet2 Middleware projects, particularly Signet. It was decided at the UI 
conference call that a separate CVS module be created for shared resources. 

The directory structure could be something like:

i2mi-ui
    java
        src
        lib
    resources
        i2mi
    webapp
        i2mi
        WEB-INF
            classes
                resources
            lib
            jsp
                i2mi

In this case the grouper-ui build script might be expected to 'know' the 
structure, but could equally well be configured to call a build script which 
builds to a configured directory.


----------------------------------------
Development environment
----------------------------------------

I am an active developer so the directory layout and build scripts I use are 
designed to facilitate development as well as final deployment.

I normally use Eclipse as a Java IDE and so some choices I have made are 
biassed to 'cope' with the way Eclipse works. 

Ideally, the directory layout ought to work with other IDEs, so comments on 
applicability from those using other IDEs are welcome.

I usually have all the CVS checkout directories as subdirectories at the same 
level, though this is not a requirement e.g.

GrouperComplete
    grouper-0.5
    grouper-ui
    uob-grouper-ui
    i2mi-subject

During development I may need to debug source code from any of the projects. 
I may also want to make code changes in the appropriate CVS checkout areas.

In my ideal development environment I would be able to edit any source files 
and instantly see changes in the web application. A typical build script for 
a web application might create the web application directory structure in a 
'build' 
directory and then either copy or make into a WAR (web application archive 
file) and deploy to a Servlet container e.g. Tomcat. Using this approach 
every change requires a build and potential restart of the web application. 
Admittedly Eclipse will allow an ant script to be called when source files 
are modified, however, this can be overkill for a simple change to a JSP. 

For a project where the whole directory structure neatly fits the structure 
above an IDE may happily run an internal servlet engine which picks up source 
code changes instantly. I prefer to use an external Tomcat instance and debug 
remotely.

In Eclipse I create one 'project' and pull in the java/src directories from 
each of the 4 projects listed above. I can then set a single output directory 
where compiled Java classes are placed whenever I save a Java source file.    
                

JSP and other 'content' files are trickier since they are saved in situ and 
not compiled to a separate destination. Normally I will be working on either 
the core Grouper UI or on Bristol customisations (where I use a similar 
directory structure). I elect to have the webapp directory of grouper-ui or 
uob-grouper-ui be the web application root (configured in Tomcat), and 
Eclipse compiles Java classes to the appropriate webapp/WEB-INF/classes 
directory.

Any changes I make to the 'local' JSPs are immediately picked up by Tomcat, 
however, I would need to run an ant script to move changes from the other 
project i.e. uob-grouper-ui to grouper-ui.

A disadvantage of this approach is that it 'pollutes' the CVS checkout area 
for one project with those from another, and I may be tempted to edit a file 
in the wrong location (though hopefully they are in different subdirectories).

Assuming that site-specific changes are always in distinct subdirectories 
then on Unix it may well be possible to set up symbolic links from grouper-ui 
to, say, uob-grouper-ui. If only Windows had symbolic links....

Some changes e.g. adding new JAR files, modifying resources, changing Struts 
/ tiles configuration files will always require a build and a web application 
restart.

I'd be interested to hear about alternative development environments...