DeveloperGuide

Instructions for how to improve this system.
Featured

Updated Mar 11, 2010 by edtme...@gmail.com

Table of Content

1.0 Prerequisites
2.0 Install Libraries and Verify Installation
3.0 Using the build.xml Files

3.1 Verify
3.2 Run
3.3 JUnit
3.4 Checkstyle
3.5 PMD
3.6 Findbugs
3.7 Javadoc
3.8 Jar
3.9 Distribution

4.0 Application Packages

4.1 Wattdepot
4.2 Home
4.3 Browser {currently in development}
4.4 Monitor
4.5 Visualizer

5.0 Development Guidelines

5.1 Updating The System
5.2 Releasing An Application

1.0 Prerequisites

You must have Ant 1.7.1 and Java 1.6 installed. We also provide .project and .classpath files for Eclipse, although that IDE is not mandatory for development.

2.0 Install Libraries and Verify Installation

NOTE: For all Installations and Verifications time may vary by Internet connection and the amount of testing which is conducted by your project

After checking out the trunk from SVN, or downloading the latest distribution and unzipping it, invoke the following "ant" command, shown below, in the top level of the project:

% ant -f verify.build.xml

This will download the required libraries necessary to compile the system and run Quality Assurance tools JUnit, Checkstyle, PMD, and Findbugs. If you cannot successfully compile the system, please contact one of the project owners for help.

Sample verify.build.xml output

Buildfile: verify.build.xml
    [mkdir] Created dir: /Users/Edward/Desktop/wattdepot-apps-2.0.308/lib/configfiles

download-ivy-if-necessary:

install-ivy:

install-libraries:
No ivy:settings found for the default reference 'ivy.instance'.  A default instance will be used
[ivy:retrieve] :: Ivy 2.1.0-rc1 - 20090319213629 :: http://ant.apache.org/ivy/ ::
:: loading settings :: file = /Users/Edward/Desktop/wattdepot-apps-2.0.308/ivysettings.xml
[ivy:retrieve] 
[ivy:retrieve] validate:
[ivy:retrieve] 
[ivy:retrieve] [xmlvalidate] 1 file(s) have been successfully validated.
[ivy:retrieve] 
[ivy:retrieve] 
[ivy:retrieve] setResourceURL1:
[ivy:retrieve] 
[ivy:retrieve] 
[ivy:retrieve] setResourceURL2:
[ivy:retrieve] 
[ivy:retrieve] 
...
[ivy:retrieve] downloading file:/Users/Edward/.ivy2/packager/build/edu.umd.cs/findbugs/1.3.8/artifacts/jars/annotations.jar ...
[ivy:retrieve] .. (13kB)
[ivy:retrieve] 	[SUCCESSFUL ] edu.umd.cs#findbugs;1.3.8!annotations.jar (1ms)
[ivy:retrieve] downloading file:/Users/Edward/.ivy2/packager/build/edu.umd.cs/findbugs/1.3.8/artifacts/jars/jFormatString.jar ...
[ivy:retrieve] .. (22kB)
[ivy:retrieve] 	[SUCCESSFUL ] edu.umd.cs#findbugs;1.3.8!jFormatString.jar (1ms)
[ivy:retrieve] downloading file:/Users/Edward/.ivy2/packager/build/edu.umd.cs/findbugs/1.3.8/artifacts/sources/source.zip ...
[ivy:retrieve] .................................................. (3092kB)
[ivy:retrieve] 	[SUCCESSFUL ] edu.umd.cs#findbugs;1.3.8!source.zip(source) (7ms)

findbugs.install.filter.file:
      [get] Getting: http://ics-software-engineering.googlecode.com/svn/trunk/configfiles//findbugs.exclude.xml
      [get] To: /Users/Edward/Desktop/wattdepot-apps-2.0.308/lib/configfiles/findbugs.exclude.xml

findbugs.tool:
 [findbugs] Executing findbugs from ant task
 [findbugs] Running FindBugs...
 [findbugs] Calculating exit code...
 [findbugs] Exit code set to: 0
 [findbugs] Output saved to /Users/Edward/Desktop/wattdepot-apps-2.0.308/build/findbugs/findbugs.xml

verify:

BUILD SUCCESSFUL
Total time: 8 minutes 11 seconds

3.0 Using the build.xml Files

At the top level of the project there are various build.xml files that are executed through "ant". This section will briefly go over each top level command.

3.1 Verify

The verify command is the most essential and most used command a developer can have. Verify is invoked in the following way:

% ant -f verify.build.xml

Verify is a two-fold command in that it compiles the system and runs Quality Assurance tools JUnit, Checkstyle, PMD, and Findbugs. As a developer, it's always good habit to invoke this command before every commit and after every checkout. Any errors that occur during this command will fail the build, at which point the console will display at what point it failed. You can then run the corresponding command to generate an error report. Error reports are found in the /build directory under the appropriate command that was run.

3.2 Run

The run command is used to execute the system. The run command is invoked in the following way:

% ant run

When you "run" the system, it will run Jetty and generate a link similar to the one below. This is just like being an end-user, you copy the generated link and paste it into your browser to start the application.

Sample Output

3.3 JUnit

To run Java Unit tests, invoke JUnit as shown:

% ant -f junit.build.xml

JUnit is a simple framework to write repeatable tests. It is an instance of the xUnit architecture for unit testing frameworks. Any errors occur will fail the build and an error report will be generated in the /build/junit directory.

Sample Output

Buildfile: junit.build.xml

download-ivy-if-necessary:

install-ivy:

install-libraries:
No ivy:settings found for the default reference 'ivy.instance'.  A default instance will be used
[ivy:retrieve] :: Ivy 2.1.0-rc1 - 20090319213629 :: http://ant.apache.org/ivy/ ::
:: loading settings :: file = F:\SchoolWork\Fall09\ICS413\Workspace\wattdepot-apps\ivysettings.xml
[ivy:retrieve]  conflict on F:\SchoolWork\Fall09\ICS413\Workspace\wattdepot-apps\lib\wicket\source.zip in [default, datetime]: 1.4.3 won
[ivy:retrieve]  conflict on F:\SchoolWork\Fall09\ICS413\Workspace\wattdepot-apps\lib\wicket\javadoc.zip in [default, datetime]: 1.4.3 won

compile:
     [copy] Copying 16 files to F:\SchoolWork\Fall09\ICS413\Workspace\wattdepot-apps\build\classes

junit.tool:
    [junit] Running edu.hawaii.wattdepotapps.browser.TestBrowserPage
    [junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 7.511 sec
    [junit] Error:
    [junit] 678 [main] INFO org.apache.wicket.Application - [WattDepotApplications] init: Wicket core library initializer
    [junit] 680 [main] INFO org.apache.wicket.RequestListenerInterface - registered listener interface [RequestListenerInterface name=IBehaviorListene
r, method=public abstract void org.apache.wicket.behavior.IBehaviorListener.onRequest()]
    [junit] 680 [main] INFO org.apache.wicket.RequestListenerInterface - registered listener interface [RequestListenerInterface name=IBehaviorListene
r, method=public abstract void org.apache.wicket.behavior.IBehaviorListener.onRequest()]
    [junit] 681 [main] INFO org.apache.wicket.RequestListenerInterface - registered listener interface [RequestListenerInterface name=IFormSubmitListe
ner, method=public abstract void org.apache.wicket.markup.html.form.IFormSubmitListener.onFormSubmitted()]
    [junit] 681 [main] INFO org.apache.wicket.RequestListenerInterface - registered listener interface [RequestListenerInterface name=IFormSubmitListe
ner, method=public abstract void org.apache.wicket.markup.html.form.IFormSubmitListener.onFormSubmitted()]
    [junit] 681 [main] INFO org.apache.wicket.RequestListenerInterface - registered listener interface [RequestListenerInterface name=ILinkListener, m
ethod=public abstract void org.apache.wicket.markup.html.link.ILinkListener.onLinkClicked()]
    [junit] 681 [main] INFO org.apache.wicket.RequestListenerInterface - registered listener interface [RequestListenerInterface name=ILinkListener, m
ethod=public abstract void org.apache.wicket.markup.html.link.ILinkListener.onLinkClicked()]
    [junit] 686 [main] INFO org.apache.wicket.RequestListenerInterface - registered listener interface [RequestListenerInterface name=IOnChangeListene
r, method=public abstract void org.apache.wicket.markup.html.form.IOnChangeListener.onSelectionChanged()]
    [junit] 686 [main] INFO org.apache.wicket.RequestListenerInterface - registered listener interface [RequestListenerInterface name=IOnChangeListene
r, method=public abstract void org.apache.wicket.markup.html.form.IOnChangeListener.onSelectionChanged()]
    [junit] 686 [main] INFO org.apache.wicket.RequestListenerInterface - registered listener interface [RequestListenerInterface name=IRedirectListene
r, method=public abstract void org.apache.wicket.IRedirectListener.onRedirect()]
    [junit] 689 [main] INFO org.apache.wicket.RequestListenerInterface - registered listener interface [RequestListenerInterface name=IRedirectListene
r, method=public abstract void org.apache.wicket.IRedirectListener.onRedirect()]
    [junit] 689 [main] INFO org.apache.wicket.RequestListenerInterface - registered listener interface [RequestListenerInterface name=IResourceListene
r, method=public abstract void org.apache.wicket.IResourceListener.onResourceRequested()]
    [junit] 689 [main] INFO org.apache.wicket.RequestListenerInterface - registered listener interface [RequestListenerInterface name=IResourceListene
r, method=public abstract void org.apache.wicket.IResourceListener.onResourceRequested()]
    [junit] 690 [main] INFO org.apache.wicket.RequestListenerInterface - registered listener interface [RequestListenerInterface name=IActivePageBehav
iorListener, method=public abstract void org.apache.wicket.behavior.IBehaviorListener.onRequest()]
    [junit] 690 [main] INFO org.apache.wicket.RequestListenerInterface - registered listener interface [RequestListenerInterface name=IActivePageBehav
iorListener, method=public abstract void org.apache.wicket.behavior.IBehaviorListener.onRequest()]
    [junit] 690 [main] INFO org.apache.wicket.Application - [WattDepotApplications] init: Wicket extensions initializer
    [junit] 803 [main] INFO org.apache.wicket.protocol.http.WebApplication - [WattDepotApplications] Started Wicket version 1.4.3 in development mode
    [junit] ********************************************************************
    [junit] *** WARNING: Wicket is running in DEVELOPMENT mode.              ***
    [junit] ***                               ^^^^^^^^^^^                    ***
    [junit] *** Do NOT deploy to your live server(s) without changing this.  ***
    [junit] *** See Application#getConfigurationType() for more information. ***
    [junit] ********************************************************************
    [junit]
    [junit] Running edu.hawaii.wattdepotapps.home.TestWattDepotAppsPage
    [junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.871 sec
...
junit.report:
[junitreport] Processing F:\SchoolWork\Fall09\ICS413\Workspace\wattdepot-apps\build\junit\TESTS-TestSuites.xml to C:\Users\Kendyll\AppData\Local\Temp\
null1019485784
[junitreport] Loading stylesheet jar:file:/E:/Java/apache-ant-1.7.1/lib/ant-junit.jar!/org/apache/tools/ant/taskdefs/optional/junit/xsl/junit-frames.x
sl
[junitreport] Transform time: 1406ms
[junitreport] Deleting: C:\Users\Kendyll\AppData\Local\Temp\null1019485784

define-sensors:

junit.sensor:
[hacky-junit] 4 UnitTest sensor data instances created.
[hacky-junit] These instances were transmitted to: http://dasha.ics.hawaii.edu:9876/sensorbase/ (0 secs.)

junit:

BUILD SUCCESSFUL
Total time: 36 seconds

3.4 Checkstyle

Calling Checkstyle specifically will solely run the quality assurance tool Checkstyle. Checkstyle is involked in the following way:

% ant -f checkstyle.build.xml

Checkstyle is a development tool to help programmers write Java code that adheres to a coding standard. It automates the process of checking Java code to spare humans of this boring (but important) task. This makes it ideal for projects that want to enforce a coding standard. Any errors that occur will fail the build and an error report will be generated in the /build/checkstyle directory.

3.5 PMD

PMD scans Java source code and looks for potential problems like:

Possible bugs - empty try/catch/finally/switch statements
Dead code - unused local variables, parameters and private methods
Suboptimal code - wasteful String/StringBuffer usage
Overcomplicated expressions - unnecessary if statements, for loops that could be while loops
Duplicate code - copied/pasted code means copied/pasted bugs

To run PMD, invoke the following:

% ant -f pmd.build.xml

Any errors that occur will fail the build and an error report will be generated in the /build/pmd directory.

3.6 Findbugs

The last quality assurance tool, Findbugs is analyzes the compiled Java bytecode and looks for errors not seen by the previous quality assurance tools.

Findbugs is invoked as:

% ant -f findbugs.build.xml

Any errors that occur will fail the build and an error report will be generated in the /build/findbugs directory.

3.7 Javadoc

To generate Javadocs of the whole system, invoke the following:

% ant -f javadoc.build.xml

You should always run Checkstyle prior to generating Javadocs! This will ensure that all source code is up to standards and no method is missing its Javadocs. The resulting Javadoc is generated in the /build/javadoc directory. Any errors that occur will generate an error report also in the /build/javadoc directory.

3.8 Jar

Creating an executable .jar file of the system can be accomplished by invoking the following:

% ant -f jar.build.xml

The jar will be created at the top level of the project. Note: When creating jar files of specific applications, for instance if you wish to create a jar file that generates a link to the visualizer or monitor page, you must modify Jetty.java and add the corresponding page to the "contextpath" There is an in-line comment to help you out.

Sample Output

""

3.9 Distribution

To create an archive of the whole system, you can invoke the following command:

% ant -f dist.build.xml

The distribution that this creates will be places in the /build/dist directory. The distribution does not contain any libraries, only build.xml files and the source code. If you have added any dependancies/libraries to the project, make sure you add them to the main "build.xml" file.

Sample Output

4.0 Application Packages

4.1 Wattdepot

Starts and enables WattDepot-Apps to be run inside a Jetty container. Contains all the classes for the stand-alone web applications Visualizer, Monitor, and Browser.

The package labeled edu.hawaii.wattdepot contains the following files:

BasePage.java
Jetty.java
WattDepotApplications.java
BasePage.html
package.html

4.2 Home

The WattDepot Stand-Alone Application Home Page. Gives a brief introduction and summary of the functions and purpose of various applications.

The package labeled edu.hawaii.wattdepot.home containts the following files:

TestWattDepotAppsPage.java
WattDepotAppsPage.java
logo.bmp
menu.bmp
package.html
WattDepotAppsPage.html

4.3 Browser {currently in development}

Contains all classes necessary to actively inspective the WattDepot server. Displays User and Source summary information.

The package labeled edu.hawaii.wattdepot.browser contains the following files:

BrowserPage.java
TestBrowserPage.java
BrowserPage.html
package.html

4.4 Monitor

Contains all classes to display the WattDepot monitor, a GUI interface displaying current real-time SensorData of a WattDepot server.

Monitors a single source and displays a SensorData properly specified by the user. User selects a source, update interval, and data type, then the application refreshes every interval displaying the latest data type. Primarily implemented in Wicket with various Ajax behaviors for refreshing.

The package labeled edu.hawaii.wattdepot.monitor contains the following files:

MonitorPage.java
TestMonitorPage.java
WattDepotLatestSensorDataCommand.java
DisplaySensorPanel.html
MonitorPage.html
package.html

4.5 Visualizer

Uses Google Visualization's Annotated Timeline or Table to display a single or multiple sources sensor or interpolated data. Currently supports multiple sources and multiple data. Implemented using a combination of Wicket for source's and! JavaScript for the rest of the components which include Data Types, Date and Time pickers, and Interval.

The package labeled edu.hawaii.wattdepot.visualizer contains the following files:

VisualizationPage.java
TestVisualizationPage.java
VisualizationPage.css
VisualizationPage.html
VisualizationPage.js
overview.html

5.0 Development Guidelines

Once you have verified your local installation of Wattdepot-Apps, you are ready for development. We follow these development guidelines:

We use Eclipse for development, and format the code using this format.
For new features, please add an Issue that specifies what you plan to do.
Please develop a JUnit test case (either before, during, or after) development of a new feature to ensure it works.
Before committing changes, please make sure that "ant -f verify.build.xml" runs successfully.

5.1 Updating The System

The system is regularly updated. You can update your build system by changing the version number within the build.xml file.

  <property name="junit.version" value="4.5" />
  <property name="wicket.version" value="1.4.3" />
  <property name="jetty.version" value="6.1.9" />
  <property name="slf4j.version" value="1.5.6" />
  <property name="wattdepot.version" value="1.3.304"/>

After changing the 'value' of the library you wish to update. The system will download the updates through ivy on the next ant build.

5.2 Releasing An Application

To release a standalone application Jar file, you will first need to remove the links and references from each of the pages.

Remove any links to other pages from the BasePage.html file (e.x. VisualizationPage.html, MonitorPage.html, ...)
Remove all internal code from the BasePage.java leaving behind an empty constructor.
Modify Jetty.java and add the corresponding page to the "contextpath" (There is an in-line comment to help you out.)
Modify the main build.xml file and append the applications name to the value of "system.name"
Execute the automated jar.build.xml using the following command:

ant -f jar.build.xml

The resulting jar will be built in the top level of the project directory.
(Revert the BasePage.html, BasePage.java, Jetty.java, and build.xml files after creating the jar)

► Sign in to add a comment