Custom Dumpers

1.  What Are Custom Dumpers?
2.  Dumpers Definition And Usage
3.  Write Your Own Dumper

1. What Are Custom Dumpers?

Dumpers are used by Invicta for creating output files according to the information gathered from Project Definition Files.

The main Dumper is AntDumper, which creates an ANT build.xml file for a project. During Invicta's execution, multiple enabled Dumpers are executed according to the given Invicta properties. Invicta contains the following built-in Dumpers: AntDumper, ProjectDocumentationDumper and ExportedProjectDefinitionDumper.

Invicta has a general extension mechanism for creating customized output files required for the build environment of a project (build scripts, documentation, export file, Eclipse files, etc.). So a Dumper is actually a simple Java class that extends net.sf.invicta.dumper.InvictaBasicDumper.

Return to top

2. Dumpers Definition And Usage

Each Dumper defines its name to be used in properties given to Invicta; these properties affect the Dumper by specifying which Dumpers are enabled and supplied with required parameters.

Dumpers are classes that must be located in the CLASSPATH of the JVM that executes Invicta. They are defined in multiple services files that must be located in the CLASSPATH. The services file name is:
    META-INF/services/net.sf.invicta.dumper.InvictaDumper

Dumpers classes and 'services' definition file can be stored in multiple JAR files. The default built-in Dumpers are defined and stored in invicta.jar.
Invicta goes over all Dumpers defined in the CLASSPATH by 'services' files. All Dumpers are disabled in default. Enabled dumpers are being executed in order to create output files.

Specifying whether a Dumper is disabled or enabled is done by setting a property. See Invicta Usage for more details. This property has the following name:
    invicta.dumpers.<dumper_name>.enabled

Examples:
    invicta.dumpers.ant.enabled=true
    invicta.dumpers.exportedProjectDefinition.enabled=false

Additional dumper-specific properties are passed the same way:
    invicta.dumpers.<dumper_name>.<property_name>

Examples:
    invicta.dumpers.ant.file=build.xml
    invicta.dumpers.myDumper.timeLimit=5

By default, all Dumpers require having the output file property set:
    invicta.dumpers.<dumper_name>.file

Example:
    invicta.dumpers.exportedProjectDefinition.file=exportedProjDef.xml

Return to top

3. Write Your Own Dumper

Following are step-by-step instructions for writing your own Dumper.

  1. Create a Dumper class

Create a new Java class that extends net.sf.invicta.dumper.InvictaBasicDumper, for example:

net.sf.newproj.MySpecialDumper

  1. Implement abstract methods

Implement the following methods of InvictaBasicDumper:

For example:

public String getName() {
    return "mySpecial";
}

For example:

public String getDumpContent() {
    String projectName = getProject().getProjectName();
    return "my:" + projectName;
}

Note: Instead of implementing getDumpContent(), you can override the following method and implement your own dumping mechanism (for example, dumping into multiple files):

public void dump() throws InvictaException;

In that case you may also override the following method, which returns whether the output files of this dumper should be re-created (default implementation is to check whether the file specified by a property is missing or is not updated):

public boolean shouldForceRunning() throws InvictaException; 

  1. Implement Dumper's logic

Add your Dumper logic by doing the following:

Use getProject() for getting an InvictaProject object of the current processed project definition.  You can access all project's components and settings using this object. 

See Invicta API documentation for more details. 

You may use the following utility methods of InvictaBasicDumper:

String getProperty(String propertyName);

Get a value of an optional property of a Dumper. Note: the short property name should be give (file instead of invicta.dumpers.mySpecial.file) 

String getRequiredProperty(String propertyName) throws InvictaException;

Get a value of a required property of a Dumper. An exception will be thrown if the property is missing.

String getFileName() throws InvictaException;

Get the value of the file property.

void writeContentToFile(String fileName, String content) throws InvictaDumperException;

Write a given string into an output file with the given name.

Throw InvictaDumperException on errors.

Use log(String message) for displaying messages to the user.

  1. Define your Dumper by adding the following line to a file named:
    META-INF/services/net.sf.invicta.dumper.InvictaDumper

For example:

net.sf.newproj.MySpecialDumper

This file has to be located in the JVM CLASSPATH (the META-INF directory is at the root of a classpath location).

  1. Compile your Dumper class, pack it together with the "services" file in a JAR file and make sure that this JAR file is located in the CLASSPATH of the JVM that runs the Invicta (you may need to edit Invicta's startup scripts, such as invicta.build.xml).
  1. Test your Dumper by running Invicta while supplying the required properties (in invicta.properties).  For example:

invicta.dumpers.mySpecial.enabled=true
invicta.dumpers.mySpecial.file=special.txt

  1. Document your dumper!

Return to top