protoj.lang
Class StandardProject

java.lang.Object
  protoj.lang.StandardProject

public final class StandardProject
extends java.lang.Object

This is the starting point class for all projects that wish to take advantage of ProtoJ pure java use-cases from compilation and javadoc generation to installation and configuration. There is no need to construct any other protoj class other than this one as it is the domain object that aggregates all the others. Neither is there any need to write even one line of xml - that is unless you take advantage of the dependency download feature or artifact publish feature, which use the xml based ivy/maven API.

Although there are many classes in the ProtoJ library many of them are inside packages qualified with *internal* which means they are implementation classes. This leaves little more than a couple of dozen pojos to get to grips with in order to gain an understanding of ProtoJ. You can find these classes directly under the protoj.lang and protoj.core packages.

To get started simply embed an instance of StandardProject in your own pojo and invoke the initXXX() methods for features that you wish to use and use the CommandStore domain object to add your own project specific commands. Here is a simple but complete example of a class called foo.Foo:

 package protoj.lang.internal.sample;
 
 import protoj.lang.StandardProject;
 
 final class Foo {
        public static void main(String[] args) {
                StandardProject project = new StandardProject(args, "Foo Version 1.0");
                project.initCompile(false, new ArgRunnable<CompileFeature>() {
                        public void run(CompileFeature feature) {
                                feature.getAjcCompileTask().getAjcTask().setMaxmem("16m");
                                feature.getAjcCompileTask().getAjcTask().setSource("1.5");
                        }
                });
                project.initJunit("16m");
                project.getArchiveFeature().initProjectArchive("foo", "foo-1.0-RC1");
                project.getArchiveFeature().addClasses("foo-1.0");
                project.getArchiveFeature().addSources("foo-1.0");
                project.getArchiveFeature().addJavadoc("foo-1.0", "16m");
                project.getCommandStore().addCommand("hello-foo",
                                "writes to the console", "16m", new Runnable() {
                                        public void run() {
                                                System.out.println("Hello Foo!");
                                        }
                                });
                project.getDispatchFeature().dispatchCommands();
        }
 }
 

Take a look at ProjectLayout to find out more about the directory structure of a ProtoJ project and where the java code in particular should be placed. Be sure to modify the demo project though rather than creating a new project from scratch each time - do this by executing the no-dependencies ProtoJ jar file with java -jar.

In order to get to this world of pure java, some mechanism must take responsibility for compiling and running the application in the first place and one solution is to use a shell script. Check out demo.sh and demo.bat from the demo project for some examples. Here is the call to java from a typical bash shell script:

 java ... helloworld.HelloWorld "init --rootDir `pwd`/.. --scriptName $0" "$@"
 

Note the special init command is specified as an argument to java, with the mandatory --rootDir and --scriptName options that protoj requires in order to function: And also note the use of the bash $@ place-holder so that additional commands such as compile, jar and test can be specified at the command line.

Author:

Ashley Williams

Constructor Summary

StandardProject()
Create a default instance of the project.

StandardProject(CoreProject core, java.lang.String versionInfo)
Intended for internal use only.

StandardProject(java.io.File rootDir, java.lang.String scriptName, java.lang.String versionInfo)
This constructor is useful in situations where the commands have to built up in-code rather than parsed from a command line.

StandardProject(java.lang.String[] args, java.lang.String versionInfo)
Parses arguments originating from main().

Method Summary

ScriptSession	createScriptSession() Creates a helper that is able to drive the project represented by this class instance through its command line interface.
ArchiveFeature	getArchiveFeature() A reference to the delegate object used to provide archive creation functionality.
StandardCommands	getCommands() A container of references of those commands belonging to this StandardProject that have been added to the CommandStore.
CommandStore	getCommandStore() Delegated functionality, see CommandStore.
CompileFeature	getCompileFeature() A reference to the delegate object used to perform in-code compilation .
ConfigureFeature	getConfigureFeature() A reference to the delegate object used to provide configuration functionality.
DispatchFeature	getDispatchFeature() A reference to the delegate object used to dispatch the instructions usually specified at the command line.
InfoFeature	getInfoFeature() A reference to the delegate object used to provide project information functionality.
InstructionChain	getInstructionChain() Access to the class responsible for containing all the instructions to be dispatched.
JunitFeature	getJunitFeature() A reference to the delegate object used to provide configuration functionality.
ProjectLayout	getLayout() Delegated functionality, see ProjectLayout.
org.apache.log4j.Logger	getLogger() Access to the protoj log4j instance.
StandardProperties	getProperties() A container of references of those properties belonging to this StandardProject that have been added to the PropertyStore.
PropertyStore	getPropertyStore() Delegated functionality, see PropertyStore.
ProtoLogger	getProtoLogger() Delegated functionality, see ProtoLogger.
PublishFeature	getPublishFeature() A reference to the delegate object used to publish project artifacts.
ResourceFeature	getResourceFeature() A reference to the delegate object used to extract resources to the filing system for APIs that can only work in this way and also apply variable ${var} substitutions.
RetrieveFeature	getRetrieveFeature() A reference to the delegate object used to download project dependencies.
SampleProjectFeature	getSampleProjectFeature() A reference to the delegate object used to create a sample project.
ScpFeature	getScpFeature() A reference to the delegate object used to provide scp functionality.
UploadGoogleCodeFeature	getUploadGoogleCodeFeature() A reference to the delegate object used to provide the google code upload functionality.
VerifyTarFeature	getVerifyTarFeature() A reference to the delegate object used to provide configuration functionality.
void	initConfig(boolean interpolated) This method must be called if configuration with properties files is to be supported.
void	initJunit(java.lang.String memory) This method must be called if junit tests are required, in order to specify the amount of memory required.
void	initPublish(java.lang.String url) This method must be called if you wish to be able to publish project artifacts created with the ArchiveFeature class.
UploadGoogleCodeFeature	initUploadGoogleCode(java.lang.String googleProjectName) This method must be called if the ability to upload the project tar file to google code is required.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StandardProject

public StandardProject(java.lang.String[] args,
                       java.lang.String versionInfo)

Parses arguments originating from main(). The easiest way to describe the format is with an example:

 compile "find-alien -gx milky-way" --rootDir ˜/dev/myproj/ --scriptName alien.sh -Dprotoj.debug
 

which results in the following args array elements:

• arg[0]="compile" - command with no arguments
• arg[1]="find-alien -gx milky-way" - command with a single argument
• arg[2]="--rootDir" - the project root directory option name
• arg[3]="~/dev/myproj/" - the project root directory option value
• arg[4]="--scriptName" - the project script name option name
• arg[5]="alien.sh" - the project script name option value
• arg[6]="-Dprotoj.debug" - system property

So in other words the two types of argument are commands and system properties. Also the rootDir and scriptName options are mandatory and used to calculate the project layout - see InstructionChain for more information

Note that although -D syntax is used for the vm arguments, these are not the same as the genuine vm arguments that won't appear in the args parameter at all. This is because we need to store them so that they can successfully be passed to any new virtual machines that need starting.

Parameters:

args - these should be the arguments from main()

versionInfo - any information to be reported when the version command is invoked

StandardProject

public StandardProject(java.io.File rootDir,
                       java.lang.String scriptName,
                       java.lang.String versionInfo)

This constructor is useful in situations where the commands have to built up in-code rather than parsed from a command line. For example in unit tests and also in VerifyTarFeature.

Parameters:

rootDir - the root directory of the project

scriptName - the name of the script responsible for issuing commands - if no extension is given then ".bat" is assumed for windows and ".sh" otherwise

versionInfo - any information to be reported when the version command is invoked

StandardProject

public StandardProject()

Create a default instance of the project. Only useful for a limited number of features since it isn't tied to any particular directory or launch script.

StandardProject

public StandardProject(CoreProject core,
                       java.lang.String versionInfo)

Intended for internal use only.

Parameters:

core -

versionInfo -

Method Detail

initPublish

public void initPublish(java.lang.String url)

This method must be called if you wish to be able to publish project artifacts created with the ArchiveFeature class.

Parameters:

url -

initJunit

public void initJunit(java.lang.String memory)

This method must be called if junit tests are required, in order to specify the amount of memory required. Invoke junit funtionality by first obtaining the delegate with a call to getJunitFeature().

Parameters:

memory - uses standard java tool notation, e.g. "32m"

initConfig

public void initConfig(boolean interpolated)

This method must be called if configuration with properties files is to be supported. Broadly speaking, setting interpolated to true means that property placeholders of the form ${var} in config files will get replaced with their real values. This is useful if you use libraries that can't handle property placeholders at runtime. See ConfigureFeature for more information.

Parameters:

interpolated -

initUploadGoogleCode

public UploadGoogleCodeFeature initUploadGoogleCode(java.lang.String googleProjectName)

This method must be called if the ability to upload the project tar file to google code is required. This is a pass-through method to UploadGoogleCodeFeature.UploadGoogleCodeFeature(StandardProject, String) , so see that constructor for a description of the parameters.

Note that there is no corresponding out of the box command for this feature. That's because it would be too generic to be useful due to the many pieces of information that would need to be specified at the command line. Projects would be best served by writing their own commands with the information hardcoded, such as the artifact name etc.

Parameters:

googleProjectName -

Returns:

createScriptSession

public ScriptSession createScriptSession()

Creates a helper that is able to drive the project represented by this class instance through its command line interface. Very useful for tests for example that need to go through the script as the user would.

Returns:

getSampleProjectFeature

public SampleProjectFeature getSampleProjectFeature()

A reference to the delegate object used to create a sample project. See SampleProjectFeature.

Returns:

getResourceFeature

public ResourceFeature getResourceFeature()

A reference to the delegate object used to extract resources to the filing system for APIs that can only work in this way and also apply variable ${var} substitutions. See ResourceFeature.

Returns:

getDispatchFeature

public DispatchFeature getDispatchFeature()

A reference to the delegate object used to dispatch the instructions usually specified at the command line. See DispatchFeature.

Returns:

getCompileFeature

public CompileFeature getCompileFeature()

A reference to the delegate object used to perform in-code compilation . See CompileFeature.

Returns:

getRetrieveFeature

public RetrieveFeature getRetrieveFeature()

A reference to the delegate object used to download project dependencies. See RetrieveFeature.

Returns:

getJunitFeature

public JunitFeature getJunitFeature()

A reference to the delegate object used to provide configuration functionality. See JunitFeature.

Returns:

getArchiveFeature

public ArchiveFeature getArchiveFeature()

A reference to the delegate object used to provide archive creation functionality. See ArchiveFeature.

Returns:

getVerifyTarFeature

public VerifyTarFeature getVerifyTarFeature()

A reference to the delegate object used to provide configuration functionality. See VerifyTarFeature.

Returns:

getUploadGoogleCodeFeature

public UploadGoogleCodeFeature getUploadGoogleCodeFeature()

A reference to the delegate object used to provide the google code upload functionality. See UploadGoogleCodeFeature.

Returns:

getScpFeature

public ScpFeature getScpFeature()

A reference to the delegate object used to provide scp functionality. See ScpFeature.

Returns:

getConfigureFeature

public ConfigureFeature getConfigureFeature()

A reference to the delegate object used to provide configuration functionality. See ConfigureFeature.

Returns:

getInfoFeature

public InfoFeature getInfoFeature()

A reference to the delegate object used to provide project information functionality. See InfoFeature.

Returns:

getPublishFeature

public PublishFeature getPublishFeature()

A reference to the delegate object used to publish project artifacts. See PublishFeature.

Returns:

getInstructionChain

public InstructionChain getInstructionChain()

Access to the class responsible for containing all the instructions to be dispatched.

Returns:

getCommandStore

public CommandStore getCommandStore()

Delegated functionality, see CommandStore.

Returns:

getCommands

public StandardCommands getCommands()

A container of references of those commands belonging to this StandardProject that have been added to the CommandStore.

Returns:

getPropertyStore

public PropertyStore getPropertyStore()

Delegated functionality, see PropertyStore.

Returns:

getProperties

public StandardProperties getProperties()

A container of references of those properties belonging to this StandardProject that have been added to the PropertyStore.

Returns:

getProtoLogger

public ProtoLogger getProtoLogger()

Delegated functionality, see ProtoLogger.

Returns:

getLogger

public org.apache.log4j.Logger getLogger()

Access to the protoj log4j instance. Convenient short-hand for getProtoLogger().getProtoLogger().

Returns:

getLayout

public ProjectLayout getLayout()

Delegated functionality, see ProjectLayout.

Returns: