Development documentation

This document provides an overview of the various documents and links that are part of this project's technical documentation.

Implementation

All of the implementation of the project resides in the Maven POM.

The project builds a ZIP file named pineapple-standalone-web-client-${pineapple.release.version}.zip. where ${pineapple.release.version} is the current Pineapple version.

The ZIP file creation is implemented in the Maven assembly file src\main\assembly\release.xml.

The content of the project is located in the directory src\main\release-dir which contains the application directory.

The ZIP file contains the structure:

pineapple-standalone-web-client-${pineapple.release.version}
     |     
     +--- runPineapple.cmd
     +--- runPineapple.sh     
     |     
     +--- conf     
     |     +--- log4j.properties
     |     `--- jetty.xml
     |               
     +--- resources
     |     `--- jetty-logging.properties
     |               
     +--- webapps
     |     `--- pineapple-web-application-war.war
     |               
     +--- lib
           +--- pineapple-jetty-starter-1.0.jar
           +--- jetty-*.jar
           +--- log4j-1.2.14.jar
           +--- slf4j-api-1.7.7.jar           
           +--- slf4j-log4j12-1.7.7.jar

The runPineapple.cmd or runPineapple.sh invokes Java with the Jetty starter JAR file pineapple-jetty-starter-X.0.jar which starts Jetty as a stand-alone application.

When Jetty starts, it will deploy the Pineapple pineapple-web-application-war.war and thus make it available as a stand-alone application.

The conf directory contains internal configuration files.

The webapps directory contains the Pineapple web application (war) which are deployed into Jetty.

The lib directory contains all the jar files that constitutes the Jetty web server.

Internal configuration

The stand-alone web application uses two configuration files. The source files are located in the directory src\main\release-dir\conf. As a result of the build process the configuration files are copied into the ZIP file in the location pineapple-standalone-web-client-${version}\conf as shown above.

The files are:

  • log4j.properties - configures logging.
  • jetty.xml - configures the Jetty web server.

Logging

Jetty is configured to use Slf4j and Log4j for logging.

Slf4j is enabled in the file pineapple-standalone-web-client-${pineapple.release.version}/resources/jetty-logging.properties file which configures Jetty logging layer by setting the value of the org.eclipse.jetty.util.log.class: 

# Configure Jetty for SLf4j Logging
org.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog

Log4j is "enabled" through the inclusion of the Slf4j binding layer for Log4j in the application class path, e.g. the jars slf4j-api-VERSION.jar and slf4j-log4j12-VERSION.jar

The log output is controlled by the Log4j configuration file pineapple-standalone-web-client-${pineapple.release.version}/conf/log4j.properties. The log4j.properties file. configures logging for ALL the Pineapple components / jars which constitutes the web application. Log4j is configured to log to ${pineapple.home.dir}/logs/pineapple-web-application.log.

Jetty server web configuration

The Jetty web server is configured by the jetty.xml file which defines:

  • The thread pool
  • The connectors and handlers

Application version

The master POM for the Pineapple project contains a property definition named pineapple.release.version which contains the current visual release number:

        <properties>
                <pineapple.release.version>x.y.z</pineapple.release.version>
        </properties>

The version number is added to name of the created ZIP file during usage of the assemply file.

For more information about Pineapple version information please consult the version info page.

Substituting the release version into the starter scripts

The runPineapple.cmd or runPineapple.sh invokes Java with the Jetty starter JAR file pineapple-jetty-starter-X.0.jar which starts Jetty as a stand-alone application.

TODO.