In order to modify hackyDoc_NewModule to suit your own needs, it first helps to understand the internal organization of the module.
One of the first files you see at the top-level in hackyDoc_NewModule is the local.build.xml file. Example 14.1, “hackyDoc_NewModule/local.build.xml” shows the contents of this file.
Example 14.1. hackyDoc_NewModule/local.build.xml
<project name="hackyDoc_NewModule.local" default="hackyDoc_NewModule.default">
<description>
Provides documentation code and packaging for the New Module chapter in the developer guide.
</description>
<dirname property="hackyDoc_NewModule.local.basedir" file="${ant.file.hackyDoc_NewModule.local}"/>
<property name="hackyDoc_NewModule.src.dir" location="${hackyDoc_NewModule.local.basedir}/src"/>
<property name="hackyDoc_NewModule.required.modules" value="hackyCore_Common, hackySdt_Activity"/>
<path id="hackyDoc_NewModule.classpath">
<pathelement location="${tomcat.servlet.jar}"/>
<fileset dir="${install.war.web-inf.lib.dir}">
<include name="*.jar"/>
</fileset>
</path>
<target name="hackyDoc_NewModule.compile" if="hackyDoc_NewModule.available"
description="Compiles changed classes to WEB-INF/classes directory.">
<hackyCore_Build.javac srcdir="${hackyDoc_NewModule.src.dir}">
<classpath refid="hackyDoc_NewModule.classpath"/>
</hackyCore_Build.javac>
</target>
<target name="hackyDoc_NewModule.install.pre-sensorshell" if="hackyDoc_NewModule.available"
description="Install hackyDoc_NewModule code and files into web application.">
<makeUpdateWebAppContent module.src.dir="${hackyDoc_NewModule.src.dir}"/>
</target>
<target name="hackyDoc_NewModule.junit" if="hackyDoc_NewModule.available" description="Runs JUnit.">
<makeJUnit module.name="hackyDoc_NewModule" module.package.prefix="org.hackystat.doc.newmodule"/>
<makeEcho message="Completed hackyDoc_NewModule.junit." prefix="hackyDoc_NewModule.junit"/>
</target>
<target name="hackyDoc_NewModule.default" description="Does nothing. Required by Ant."/>
</project>
This local.build.xml file contains the minimum set of Ant targets required to build a simple module that contains no third party libraries and whose only purpose is to define a simple Hackystat analysis.
For more details on the targets in local.build.xml, see Section 13.8, “The local.build.xml file”. If using this file as a template for your own local.build.xml, consider the following:
Rename each occurrence of "hackyDoc_NewModule" to your own module name. It will typically begin with either "hackySdt_", "hackySensor_", or "hackyApp_".
Edit the required.modules property to list the set of modules required by your module.
Check the classpath property and edit to include any other library files required by your module.
If any library files are required at run-time (and for compilation by other modules that will require this one), then copy them to ${install.war.web-inf.lib.dir} in the compile target.
Update the pre-sensorshell target to do any other copying required by this module.
Define a post-sensorshell target if necessary.
Edit the module.package.prefix attribute in the makeJUnit macro to correctly specify your module's package prefix.
The top-level directory also contains two files: .project and .classpath. These files define the "hackyDoc_NewModule" project for Eclipse.
If you choose to use Eclipse to develop your modules, you will need to do a small amount of configuration. Section 19.6, “Eclipse configuration hints” contains more information on this process.
Many Hackystat application modules will want to include one or more chapters of documentation to be included in one or more of the User, Developer, and Administrator guides. (Hackystat modules defining Sensors and Sensor Data Types have an alternative docbook documentation mechanism that produces entries in the User Guide Appendices.) The hackyDoc_NewModule/docbook subdirectory contains two files that define a Developer Guide chapter for the hackyDoc_Module.
Example 14.2, “hackyDoc_NewModule/docbook/devguide/hackyDoc_NewModule.devguide.docbook.def.xml” shows the contents of the definition file.
Example 14.2. hackyDoc_NewModule/docbook/devguide/hackyDoc_NewModule.devguide.docbook.def.xml
<hackydocbook>
<chapter guide="Developer"
fileName="hackyDoc_NewModule.devguide.docbook.xml"
rank="100.0"/>
</hackydocbook>
This file contains an XML specification for this Docbook chapter used by the Hackystat documentation generation system to determine which guide to place the chapter in, what file contains the chapter text, and how to order this chapter within the specified guide. The Hackystat documentation generation system requires these files to end with "docbook.def.xml". More details on this definition file will be forthcoming in later chapters of this Developer Guide.
When using this file as a template for your own module documentation, consider the following:
Rename the file so that its name refers to your module name.
Check the guide attribute, and change to "User" or "Administrator" if needed.
Edit the fileName attribute to refer to your module's documentation chapter file name.
Edit the rank so that your chapter will show up in the appropriate order.
Example 14.3, “hackyDoc_NewModule/docbook/devguide/hackyDoc_NewModule.devguide.docbook.xml” shows the contents of the hackyDoc_NewModule chapter file.
Example 14.3. hackyDoc_NewModule/docbook/devguide/hackyDoc_NewModule.devguide.docbook.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC
"-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
"http://www.cs.put.poznan.pl/dweiss/dtd/dweiss-docbook-extensions.dtd" [
<!ENTITY % isopub SYSTEM "iso-pub.ent">
%isopub;
<!ENTITY % local SYSTEM "local-entities.ent">
%local;
]>
<chapter id="ch:hackyDoc_NewModule.developerguide">
<title>[hackyDoc_NewModule] Sample Chapter</title>
<para>
If this was a real docbook documentation chapter, its purpose would be to
explain the design and implementation of the hackyDoc_NewModule module for
enhancement and extension by other developers.
</para>
<para>
However, this is not a real docbook documentation chapter; it's purpose is
actually to show simple examples of the files and their locations in a Hackystat module.
</para>
</chapter>
This file contains the contents of the documentation chapter associated with this module. Hackystat uses a set of DocBook customizations developed by Dawid Weiss.
When using this file as a template for your own module documentation, you will need to supply content appropriate for your module, and make sure that all identifiers are unique by prefixing them with your own module name. A forthcoming chapter in the Developer Guide will go over the process of defining DocBook documentation in more detail.
The src directory of hackyDoc_NewModule contains six files that provide an implementation of the Sensor Data Summary command:
SensorDataSummary.java: This file contains the Java code that implements the "CommandRequest" class, a special Hackystat class that simplifies processing of Hackystat analysis command invocations.
SensorDataSummary.jsp: This file contains Java Server Pages code for displaying the SensorDataSummary command and the results of its invocation.
TestSensorDataSummary.java: This file contains the test code for remote invocation of the SensorDataSummary command and checking the results of its invocation for correctness.
hackyDoc_NewModule.sensordatasummary.command.def.xml: The file contains an XML specification of this command used by the Hackystat web server.
doc.sensordatasummary.html: Every Hackystat analysis command has a "short" and "long" documentation string. This file contains the "long" one.
package.html: This file contains the JavaDoc package-level documentation.
An explanation of these six files will require its own Developer Guide chapter, which will be forthcoming. All Hackystat commands do involve the definition of these six files, and you may find these files to be useful templates for your own development purposes.