JPlate Environment 1.2

Conventions

Project Conventions

The Environment strives to adhere to various conventions as described below.

Directory names

Directory names should reflect the contents of those directories:

lib: where applicable, all necessary 3rd party libraries.
src: root directory for all source files.
src/ant: Ant source files.
src/doc: documentation.
src/resources: root directory for all resource files.
src/resources/en_US: messages for the U.S. locale.
src/xsl: all XSLT transformations.
test: root directory for all unit test cases.

File names

Files adhere to the following naming conventions:

Property files: *-properties.xml- i.e. documentation-properties.xml.
Macro files: *-macros.xml - i.e. documentation-macros.xml.
Resource files: *-messages.xml - i.e. environment-macros-messages.xml. It is important to note that resources belong in a directory named after the appropriate locale - for example en_US for the United States.
Script files: *-scripts.xml - i.e. documentation-scripts.xml.

Property Names

Properties are named according to the concept and type in this format: jplate-[concept].type - i.e. jplate-build.ASSEMBLY_HOME. Please note: by naming variables in this fashion a form of namespace is defined that should help to avoid property name collisions.

Property Types

User Definable Properties

User definable properties are those that can be defined value outside the Environment. If not defined, reasonable default values are used.

There are three ways to express values for user definable properties:

System properties, for example using the -D command line option when invoking Ant or java:

ant -Djplate-build.JAVA_SRC_DIR_NAME=MySrcDir

Environment variables:

export jplate-build.JAVA_SRC_DIR_NAME=MySrcDir
ant

Ant properties:

"Fixed" Properties

Fixed properties are those that are set by the Environment to predefined values. Often fixed properties are expressed using some user definable properties to create values. Please note: if a fixed property currently has a value, it is reset with a new one as defined by the Environment.

Variables

Variables are properties used within macrodef's. These properties will always be overwritten for each call of a macrodef.

Deriving Directory Information

Properties holding directory information are typically named using a summation strategy: definition of a directory name and a "home" using this name. Additionally, directories may be defined relative to a "root" or home directory. For example:

jplate-build.PROJECT_HOME = [some directory]
jplate-build.ASSEMBLY_DIR_NAME = "assembly"
jplate-build.ASSEMBLY_HOME = "${jplate-build.PROJECT_HOME}/${jplate-build.ASSEMBLY_DIR_NAME}"

Building and "skipping"

The build script, jplate-build.xml, contains reusable targets and dependencies that follow a named pattern in the form of verb-noun (for example document-svn). To skip execution of targets (either directly or through a dependency), most targets make use of the unless attribute. For example <target name = "document-svn" unless = "jplate-build.SKIP_DOCUMENT_SVN"...> The name of the property used to denote skipping execution typically follows a naming convention like jplate-build.SKIP_NAME_OF_TARGET - note the use of underbars instead of hyphens. Here are a few examples:

Target Name	Unless Attribute
document-svn	jplate-build.SKIP_DOCUMENT_SVN
compile-java	jplate-build.SKIP_COMPILE_JAVA
jar-java	jplate-build.SKIP_JAR_JAVA