HEAD PREVIOUS

Chapter 16
Child Projects

This chapter provides a more detail information about the structure of JMatter project directories, and documents a JMatter application's build file.

16.1  Creating Child Projects

The framework has its own build file, used to compile the framework itself. This build file contains a target: new-project-ui that automates the creation of a JMatter project. We walked through using this target in chapter 4. Invoking this target brings up a simple user interface, shown in figure . We specify:
  1. The project name
  2. The base directory
  3. Whether we wish to produce a standalone or dependent project
The project name is required. It is also used as the name of the directory that contains the project files. If the base directory is not specified, we default to creating the project as a sibling directory of the framework itself. The last option needs a slightly lengthier explanation.
A standalone project has no external dependencies. Not only is the child project structure created, but all libraries necessary to run it are containing within the project, in the lib/ subdirectory. That is, a copy of the JMatter framework is in a sense frozen into the child project. Standalone projects are therefore not subject to changes to the framework that might take place after its creation (unless the JMatter jar file and other dependent jar files are manually replaced).
When creating a dependent project, its build file is told where the JMatter framework is located and so it can reference the JMatter framework's .class files directly, as well as any .jar files that the framework itself leverages.
Both modes are useful in different contexts. For developers with in-depth knowledge of the framework, that expect expect perhaps to make changes to the framework as they develop their application, it's convenient not to have to repackage the framework jar file and copy it to the child project each time a change takes place. Dependent child projects would pick up these changes immediately. So therein lays the tradeoff.
It isn't particularly difficult to change one's project from being dependent to being standalone or vice versa. However, at the time of this writing, there is no magic ant target that will do this work on our behalf.

16.2  Directory Structure and Files

The main directories that you'll see after creating a new project are:
src, test, doc, resources
Each directory's name fairly clearly implies its role. The base directory for Java source code is src, while test is the base directory for tests. The doc subdirectory contains a basic README file. The doc/ directory is of course an ideal location for your project's own documentation.
The resources folder is interesting; its composition is summarized in the table below.
Directory or File Description
images/ Where to place icons for model objects, the image for the splash screen, and other image resources that your application will use.
styles.css Default stylesheet for JMatter; governs how the JMatter user interface is styled (see chapter 17).
model-metadata.properties Where to specify required fields, and field default values.
local-metadata_<locale>.properties Use for localization: provide translations for type names, command captions, field captions, and more in order to produce a user interface that is properly translated for the given locale.
hibernate.properties Governs database configuration: database dialect, driver class name, connection url, username and password.
resources/jws Contains resources necessary to bundle the application as a java webstart distribution (see chapter 18)
wings/ and echo2/ This requires some explanation. We're in the process of developing a web-based user interface for JMatter. At the time of this writing, this work is not yet finished. Resources necessary to construct the web application distribution resides in these directories.
src/class-list.json (Optional) This is where you can preconfigure your application's classbar: that is, specify here the list of model objects you wish to expose to your user interface.
src/persistClasses.st You typically will not need to edit this file. This template is resolved at build time to list the persisted entities in your application. The list is derived from the @Entity annotations in your class files. It is passed to Hibernate via a Spring configuration file.
All child projects come with an ant build file. This build file generates a number of directories for the purpose of maintaining artifacts. Let's discuss these:
db
If you configure your application to use a lightweight or file-based database, such as H2 or hsqldb, the database files by default reside in this subdirectory
build/classes
Your application is compiled to this directory. All resources are also copied here, including images and hibernate mapping files (the latter being generated, not copied)
jws-dist
Used to assemble the Java WebStart distribution
dist
The Java WebStart distribution is packaged as a .war file and copied to this directory

16.3  Build File Targets

Let's now turn our attention to the child project's ant build file. Here is a listing and description of the relevant targets.
 compile        compile code
 compile-tests  compile tests
 genhbm         generate hbm.xml files
 jar            jar it
 jar-model      jar just the model 
 jws-dist       create java webstart distribution
 macappbundle   create macosx app bundle 
 reveng-db      Reverse engineer an existing database schema..
 run            run app
 run-test       run a test class
 run-tests      run tests
 schema-export  export schema to db
 schema-update  update db schema
 shellscript    produce runnable shell script
 test-report    produce junit reports
Default target: run
There isn't that much to say beyond the default description of these targets. JMatter generates Hibernate hbm.xml files to the build/classes directory. The run target is useful while developing. You typically don't need to invoke many of these targets. Invoking schema-export for example will automatically compile the code and generate the mapping files first. Also, if you're working with a dependent project, any changes to the framework codebase will automatically be recompiled first.
The jar-model target is useful in the context of the JMatter Application Browser (see chapter 19). For more detail about the reveng-db target, see .
Other targets worth pointing out include shellscript and macappbundle. The first generates a run.sh (or run.bat on win platforms) to launch the application. On Linux, going from such a script to a desktop-launched application, complete with icon, is trivial. The latter is specifically for macosx users and bundles the application as a .app "file."
Chapter walks you through deploying your project via Java WebStart.
HEAD NEXT