OpenSubsystems

Directory structure

OpenSubsystems project is setup to allow convenient development cleanly separating all source files created as part of this project from those, which are part of external projects and those generated as part of the build processs or testing. All code for all subsystems is located in a single directory tree even though individual subsystems are separated by packages. This allows for easier and simpler development since developers can easily find code they can use and reuse as well as fix problems and add features in multiple subsystems as needed without worrying about switching from project to project.

• OpenSubsystems - if you have followed Development Environment setup then this is a subdirectory of Development directory in the root of your drive. This directory contains ALL files related to OpenSubsystems project.
  • classes - Eclipse uses this directory to store compiled class files. This directory is not used by the Ant based build process. You can simple delete content of this directory and Eclipse will recreate all files next time it rebuilds the OpenSubsystems project. DO NOT add this directory or any of its content to CVS.
  • external - this directory contians all external projects, which OpenSubsystems integrates with or uses and which can be distributed freely. The content is managed by CVS repository and External libraries article tells you what to do when files are added or updated.
    • ant
    • ...
    • ant.zip
    • ....zip
  • generated - OpenSubsystems uses this directory to store all files that are produced by Ant based build process or files used when running tests. You can simply delete content of this directory and next time you build one of the OpenSubsystems components, the build script will recreate the directory and its content. DO NOT add this directory or any of its content to CVS.
    • core
    • security
    • ...
  • sources - this directory contains all files created as part of OpenSubsystems project. The content is managed by CVS and you can download it from the CVS repository. When you are developing OpenSubsystems you are changing or creating files in this directory or in one of its subdirectories.
    • build - Ant build files for individual subsystems. All build files should be started from this directory.
    • code - this directory contains all code created as part of OpenSubsystems.
      • java - all code written in Java
        • ...core
        • ...security
        • ...
      • shell - shell scripts used to execute applications or tools (BAT, CMD, SH, ...)
      • webui - webui related files, which look like code (CSS, JavaScript, JSP, ...)
    • config - configuration files for individual subystems
    • resources - all other resources used by code, which are not coded but created by other means (e.g. images).
    • tests - this directory contains all tests used to test functionality of the files in the code directory. The directory structure below should be identical to the directory structure under code so that the tests resides in the same directory as the code they test.
      • java
        • ...core
        • ...security
        • ...
      • webui
    • ...

While you are creating new code or modifying existing code within Eclipse development environment, Eclipse automatically compiles your files as they are modified. The Problems view shows you any syntactical or checkstyle errors, which were found during the build and you can conveniently fix them by double clicking the message for Eclipse to take you to the location of the error. Eclipse also provides Quick Assist to help you automatically fix the common problems.

The files compiled by Eclipse are placed into

C:\Development\OpenSubsystems\classes directory.

Since Eclipse doesn't recognize individual components, classes directory contains compiled code for all subsystems. This speeds up development but it is not suitable for distribution, since when distributing OpenSubsystems, the desire is to build and package individual subsystems independently. That allows us to track dependencies between subsystems and it allows users to pick and choose, which subsystems they are going to use.

Ant build scripts

The build of individual subsystems is performed using Ant build scripts. All build scripts and build related files are located in

C:\Development\OpenSubsystems\sources\build directory.

The main files contained in this directory are:

• build.properties - contains paths to directories where all builds search for files and various properties which control behavior of the build
• external.properties - contains paths to directories where build looks for external projects
• build-generic.xml - common subroutines used by all builds
• build-common.xml - common targets that all builds can simply import
• build-external.xml - subroutines used by build to install external projects
• build-XXX.xml - build file for subsystem XXX

You can conveniently launch Ant from within Eclipse after you tell Eclipse, which subsystems you want to work with. Go to Window menu, select item Show view and select menu item Ant. New Ant View will appear in your Java perspective. Click the Add Buildfiles button on the toolbar to add Ant build files into this view. Browse to

C:\Development\OpenSubsystems\sources\build

directory and select build files for components you want to work with. For example you can select build-security.xml if you want to develop Open Security subsystems. Click OK to add the selected files. Once the files are in the Ant view, click the Hide Internal Target button on the toolbar to filter down the displayed Ant targets to show only the important ones.

Build script targets

Each subsystem has a single build script. You can add build scripts for multiple subsystems into the Ant view and work with them simultaneously. Each build script is in Ant view represented by a single item. The build script be expanded by clicking on the + icon next to the name of the subsystem it represents. Once the build script tree in Ant view is expanded it will reveal individual targets, the script provides.

Target represents a step in a build process, which can be executed. Build scripts for all subsystems have the same structure and offer the same targets. When you double click on the target, Eclipse will launch Ant to build specified target and all its dependencies. There are also dependencies setup between individual subsystems. If one subsystems requires for its correct functioning another subsystems, when the dependent subsystem is built, Ant will also build all the subsystems it depends on. These are the common targets provided by every subsystem:

• all - clean, build, checkstyle, test and distribute
• build - rebuild the whole subsystem from scratch by building all files including the entire documentation
• checkstyle - check coding style in all source files in this subsystem
• clean - removes all generated files for this subsystems but it leaves all generated files for subsystems this one depends on
• cleanall - removes all generated files for this subsystems and all all other subsystems this one depends on
• distribute - create distribution packages for this subsystem
• retest - update and test
• test - run JUnit tests for this subsystem
• update - build and package only minimal number of required files

The day to day development work consists of using the update target to quickly build only the modified files so you can launch the built subsystem. The build target is handy to rebuild the entire subsystem including JavaDoc documentation to discover any potential problems. If there is a problem, you can use clean or cleanall target to remove the generated files and then use build or all target to rebuild the subsystems and all its dependencies. Checkstyle and test targets are handy when you are building using automates script but for day to day developmen. The distribute target will build distribution packages once you are ready to distribute your subsystem. Eclipse provides better way to check you coding style and run jUnit tests.

Generated files

Ant build script generates all files into

C:\Development\OpenSubsystems\generated

directory. For a given subsystem it creates a subdirectory with the same name as the name of the subsystem. For example for Open Security subsystem the directory is

C:\Development\OpenSubsystems\generated\security.

The first step of the build process is to separate the source files applicable to this subsystems from all the other ones. The build script copies the source files into

C:\Development\OpenSubsystems\generated\security\sources

directory. The rest of the build will then use only this subset of the files to build the subsystem. This step ensures that even though there is a single tree for all the subsystems, when the subsystem is built, it is absolutely clear, which source files are used to build it.

The second step of the build process is to collect all external libraries and files this subsystem requires. The build script copies the files into

C:\Development\OpenSubsystems\generated\security\external

directory. The rest of the build will then use only these libraries to build the subsystem. This step ensures that even though different subsystems use different external projects, when a specific subsystem is built, only its required projects are used to build it. It is also clear, which external projects are needed for this subsystem. During this step the build script also collects libraries from other subsystems this one depends on.

The third step of the build process is to build the subsystem. All the files collected in step 1 are compiled (using libraries collected in step 2), generated, precompiled and packated into

C:\Development\OpenSubsystems\generated\security\build

directory. JavaDoc documentation for the subsystem is at this time also generated into

C:\Development\OpenSubsystems\generated\security\docs

directory.

The next step of the build process is to test that the built subsystem is valid. This is done by running automated JUnit test suite to verify functionality of the created subsystem. All files created by the test are placed into

C:\Development\OpenSubsystems\generated\security\test

directory. At the end an HTML summary report of executed tests is generated into

C:\Development\OpenSubsystems\generated\security\testdoc

directory.

The last step of the process is to create distribution packages. All files created for distribution are placed into

C:\Development\OpenSubsystems\generated\security\distribution

Packaging

During the package phase, the build process creates compressed archives for all executable code as well as the web application. Seven different files are created

• [subsystem_name].jar - java code for the subsystem
• [subsystem_name]-ejb.jar or [subsystem_name]-gen.jar - java code required to run the subsystem as enterprise java beans within J2EE application server
• [subsystem_name]-tests.jar - JUnit tests for the subsystem
• [subsystem_name]-testutils.jar - utility classes required by the jUnit tests for the subsystem
• [subsystem_name].war - web application including the web user interface for the subsystem and all classes required to run the tests from the browser. This package doesn't contain any java code present in the above subsystem jar files or external libraries and the main purpose is to package the web ui portion of the subsystem.
• [subsystem_name]-app.war - full web application including all java code, tests and external libraries. This gives you option to deploy the application inside of web container.
• [subsystem_name]-app.ear - full enterprise application including all java code, tests and external libraries. This gives you option to deploy the application inside of enterprise application container.

Distribution

The last and optional (therefore it needs to be executed explicitly) step of the build process is to create distribution packages. Three different packages are created

• [subsystem_name]-bin.jar - Binary distribution including external dependencies. This package allows you to develop your application using the specified subsystem. It contains all libraries, external dependencies, configuration files and scripts you may need for your application. The package also contains reference documentation such as JavaDoc API.
• [subsystem_name]-src.jar - Source distribution without external dependencies. This package contains all source code for a specified subsystem including scripts, configuration files and resources required to rebuild the subsystem. This package doesn't include external dependencies, which can be found in the "bin" package.
• [subsystem_name]-app.jar - Binary distribution of test applications. This package contains ready to deploy demo application. It allows you to access and execute tests demonstrating possibilities of the web user interface built using given subsystem and exercising the backend code. This way you can verify that the subsystem works in your environment. Refer to readme.txt file in the root directory of the package to find out the details how to run the application.

To rebuild subsystem from source just using the distribution packages and without getting the entire code from CVS you will need both src and bin packages. First you will unpack the src packages to directory named sources in your development directory. Next you will place the entire external directory from the bin package next to the sources directory in your development directory. Now you can just navigate into the build subdirectory of the directory sources and invoke build script build-[subsystem_name].xml.