Adding the schemas to the main project web site

During the site phase the schema is copied to the main site in the pineapple-project. The schemas are copied to the directory /ns/app.

This is implemented in the pom.xml for the project.

Customized package names

The generated classes are mapping into the package com.alpha.pineapple.web.model using the JAXB bindings file at: src/main/resources/bindings.xjb.

Customized type names

The JAXB bindings file also defines mappings of Schema type into Java types. The applied rule is to remove the postfixed Type from the Schema type in the corresponding Java types, i.e. from the schema type named NiceType a Java type named Nice is generated by JAXB.

WAR Deployment descriptors

Pineapple configuration

Pineapple is initialized from the value of the pineappple.home.dir system property which defines the Pineapple Home directory. The directory defines the location where Pineapple will look for its configuration files, modules and write reports to.

Initialization of the home directory is done by PineappleHomeInitializer context listener as part of the initialization of the web application.

Two use cases for distribution of the web application are supported:

• Stand alone client.
• Deployable web application.

Logging

The web application uses Log4j for logging. The Log4j configuration file is located in src/main/webapp/WEB-INF/log4j/log4j.properties.

The Log4j configuration file is read by the com.alpha.pineapple.web.logging.LoggingInitializer class which is configured in the web.xml deployment descriptor.

The file configures logging for ALL the pineapple components / jars which constitutes the web application.

The configuration file configures Log4j to write log files to:

• ${pineapple.home.dir}/logs/pineapple-web-application.log

Spring web application context file

The main application context file for the application is located at src/main/webapp/WEB-INF/spring/webapp-config.xml.

The application context file defines:

• Configuration of Spring web MVC through the import of the file mvc-config.xml
• Configuration of services through the import of the file service-config.xml
• Component scanning of the com.alpha.pineapple.web.spring.rest package for Spring Web MVC controller classes which implements the REST API.
• Definition of messageProvder bean for I18N.
• Definition of sessionState bean for definition of the session state for a single user of the web application.
• Definition of debugInfoModel bean which defines the debug information model which provides debug information to the debug panel.
• Definition of systemInfoModel bean which defines the system information model which provides system information to the system panel which is embedded into environment configuration tab.
• Definition of treeNodeStateConverter bean which implements the org.zkoss.bind.Converter which is use to convert the state of an execution result into a string for rendering in a tree.
• Definition of treeNodeStateIconConverter bean which implements the org.zkoss.bind.Converter which is use to convert the state of an execution result into a FontAwesome icon for rendering in a tree.
• Definition of treeNodeStartTimeConverter bean which implements the org.zkoss.bind.Converter which is use to convert the start time of an execution result into a string for rendering in a tree.
• Definition of treeNodeDescriptionStyleConverter bean which implements the org.zkoss.bind.Converter which is use to convert the description of an execution result into a string for rendering in a tree.
• Definition of executionStateStyleConverter bean which implements the org.zkoss.bind.Converter which converts a string based ExecutionState into a color.
• Definition of executionStateTextConverter bean which implements the org.zkoss.bind.Converter which converts a string based ExecutionState into a human readable text.
• Definition of errorMessageBoxHelper bean which is a helper class for creation of error message boxes in ZK.
• Definition of eventDispatcher bean which implements the ZK event dispatcher EventDispatcher interface which dispatches ZK events to registered ZK desktop's.
• Definition of asyncTaskExecutor bean which defines a task executor used to handle the asynchronous execution of the asyncOperationTask bean. (DEPRECATED)
• Definition of asyncTaskHelper bean which is general helper class for asynchronous execution tasks in the ZK framework. (DEPRECATED)
• Definition of unpackModuleTask bean which is asynchronous task which uploads and unpacks a zipped module and updates the GUI continuously. (DEPRECATED)
• Definition of restResultMapper bean which is implements mapping from the core component classes to the model classes which are returned by the REST web services.

Spring web MVC application context file

The application context file for Spring web MVC is located at src/main/webapp/WEB-INF/spring/mvc-config.xml.

The application context file defines:

• The mvc:annotation-driven element which configures the @Controller programming model in Spring web MVC.
• A forwarding rule which forward requests to the workspace view:

  <mvc:view-controller path="/index" view-name="workspace"/>
  <mvc:view-controller path="/workspace" view-name="workspace"/>
  <mvc:view-controller path="/mvc/workspace" view-name="workspace"/>
  <mvc:view-controller path="/pineapple" view-name="workspace"/>  
  <mvc:view-controller path="/error" view-name="error"/>  
  

• A view resolver InternalResourceViewResolver which resolves view names to .zul resources within the /WEB-INF/jsp directory
• A resource mapping which maps requests for JavaScript at /js/** to the internal location /js/ at the web root in the web application.
• A resource mapping which maps requests for images at /images/** to the internal location /images/ at the web root in the web application.
• A multipart resolver to support multipart uploads in the REST API implemented using Spring web MVC.

Spring services MVC application context file

The application context file for services used by the MVC controllers is located at src/main/webapp/WEB-INF/spring/service-config.xml.

The application context file defines:

• Access to the Pineapple core component through the import of the file com.alpha.pineapple.core-config.xml.
• Access to the Pineapple HTML report generator through the import of the file com.alpha.pineapple.report.basichtml-config.xml.
• Definition of webAppCoreFactory factory bean for creation of core component instances.
• Definition of coreComponent bean which defines the core component instance created by the webAppCoreFactory factory bean.
• Definition of webAppResultListener bean for definition of a Pineapple result listener. Received events are forwarded to Reactor as events. The events are posted as result notifications.
• Definition of reportRepository bean for definition of report repository.
• Definition of reportSetMarshaller bean for definition of reports marshaller which can load and save reports in the report repository.
• Definition of activityRepository bean for definition of activity repository.
• Definition of configurationModelObjectFactory for creation for model objects returned by the REST API. The model objects are defined by the Environment configuration schema defined in the Pineapple API project.
• Definition of webAppObjectFactory for creation for model objects defined by the web application.
• Definition of webAppReactor bean which implements the Reactor.
• Definition of webAppReactorEnvironment bean which implements the Reactor environment.
• Definition of createReport bean for definition of create report Reactor consumer.
• Definition of createdReportNotifier bean for definition of create report Reactor consumer.
• Definition of openModuleActivityInvoker bean for definition of open module Reactor consumer.
• Definition of executeOperationActivityInvoker bean for definition of execute operation Reactor consumer.
• Definition of resultNotificationNotifier bean for definition of execution result notifier Reactor consumer.

ZK GUI definition files (.zul)

The GUI widgets are defined by .zul files located in the src/main/webapp/WEB-INF/jsp directory.

For each .zul file either a view model (MVVM)class and/or a ZK controller class exists which implements the logic (e.g. event code) of the widgets. The ZK view model classes are located in the package com.alpha.pineapple.web.zk.viewmodel. The ZK controller classes are located in the package com.alpha.pineapple.web.zk.controller.

Servlet API configuration

The web application is configured with a Maven dependency to the Servlet API version 3.1.0 (see PINEAPPLE-715/6) with the provided scope:

    <dependency>
         <groupId>javax.servlet</groupId>
         <artifactId>javax.servlet-api</artifactId>
         <scope>provided</scope>
    </dependency>    

The version is managed from the main project pom.xml.

JSP Standard Tag Library (JSTL)

The application doesn't use JSTL and contains no dependencies to JSTL (since resolution of PINEAPPLE-145).

Internationalization (I18N) configuration file

The report generator uses internationalization. Messages used by classes in the project are located in the file src/main/resources/com.alpha.pineapple.web-messages.properties.

Integration of the ACE editor

The module panel implements integration of the ACE editor to support remote editing of model files.

Components used to implement the ACE integration

This diagram illustrates the components constitutes the integration between ZK and ACE:

The participating files are:

• ZK View - which defines the GUI widgets. The view is implemented in the .zul file named module-panel.zul.
• ZK View Model - which provides data for the ZK view using the ZK MVVM and implements event handlers. The view model is implemented as a Java POJO named ModulePanel.java.
• JavaScript #1 - which implement functions for creation of the editor instance. The script is implemented in the file named module-panel.js.
• JavaScript #2 - which implements the ACE editor. The editor is implemented in a collection of scripts which are added to the web application. The main script is named ace.js.
• Application Service - which serves as a backend for the view model. The service is implemented as a Java POJO named SessionState.java.

Loading a document in ACE

This diagram illustrates the call sequence when a new document is loaded:

Saving a document in ACE

This diagram illustrates the call sequence when a document is saved at the server side:

The REST API

Reactor usage

public PineappleCore createCore() throws CoreException {
        
  webAppReactor.getConsumerRegistry().clear();
  webAppReactor.on($(REACTOR_TOPIC_SERVICE_NOTIFICATION), createReport);
  webAppReactor.on($(REACTOR_TOPIC_SERVICE_NOTIFICATION), resultNotificationNotifier);  
  webAppReactor.on($(REACTOR_TOPIC_SERVICE_CREATED_REPORT), createdReportNotification);
  webAppReactor.on(T(OpenModuleActivity.class), openModuleActivityInvoker);
  webAppReactor.on(T(ExecuteOperationActivity.class), executeOperationActivityInvoker);

  // create core
  ResultListener[] listeners = { webAppResultListener };                
  PineappleCore coreComponent = coreFactory.createCore(listeners);                 
                        
  return coreComponent;
}

Dispatching Reactor events as ZK events

Dispatch of Reactor events as ZK events is implemented to support notification of the GUI of events in the non GUI layer of the web application which should be reflected in the GUI.

A ZK event dispatcher is used by a Reactor consumer who wants to post to a ZK event. A Reactor consumer is by nature non-graphical and has no reference to the GUI. The ZK event dispatcher is a class* which perform a double registration when a ZK desktop is created. The event dispatcher registers itself with the desktop to allow for unregistration when the desktop is destroyed. Furthermore the dispatcher registers the ZK desktop to keep record of all known desktop’s (i.e. live GUI’s). The purpose is to have a defined end point where ZK events can be posted to.

The event dispatcher will dispatch events to all registered desktops. A registered desktop is unregistered when the desktop is destroyed.

The interface EventDispatcher is used to implement an event dispatcher The default implementation of the interface is EventDispatcherImpl.

Order of initialization of the context listeners

The order of initialization is:

1. PineappleHomeInitializer
2. Log4jInitializer
3. ContextLoaderListener

The PineappleHomeInitializer is initialized first since it sets the pineappple.home.dir system property which is used by log configuration initialized by Log4jInitializer and the Pineapple core component defined in the Spring application context initialized by ContextLoaderListener.

Core Factory Classes

The package com.alpha.pineapple.web contains a factory for creation of the core component:

• WebAppCoreFactory which registers Reactor consumers, and creates a core component instance with the a Pineapple-to-Reactor event listener WebAppResultListenerImpl configured.

Context Listeners

The package com.alpha.pineapple.web.context contains servlet context listeners which is used to initialize the web application:

• LoggingInitializer which initializes Log4j when the application is started.
• PineappleHomeInitializer which initializes the Pineapple Home directory.

Model classes

The package com.alpha.pineapple.web.model contains:

• RestResultMapper defines interface for model mapper which can map object used by core component to model objects returned by the REST API.
• RestResultMapperImpl implementation of the RestResultMapper interface.
• DebugInfoModel Creates model of a available debug information. Is used to provide content to the DebugPanel.
• SystemInfoModel Creates model of a available system information. Is used to provide content to the systemInfoPanel.
• ReportRepository defines interface for a report repository
• ReportRepositoryImpl Implementation of the ReportRepository interface. The repository contains information about reports stored on disk. The location of the reports is resolved form the RuntimeDirectoryProvider.
• SessionState defines interface for the web application session state for a single user.
• SessionStateImpl is an implementation of the SessionState interface.
• UnpackedEntry is a data object which is used to describe a unpacked ZIP file entry during the execution of the asynchronous task unpackModuleTask.
• Model defines interface for a simple data object which is used to render a model in the module panel. The model object is introduced to avoid the issue PINEAPPLE-269: Loading a new module results in a class cast exception from the execution panel.
• ModelImpl is an implementation of the Model interface.
• ExecutionResultProperty class for rendering detail about a selected execution result in the execution panel.

Accounts classes

The package com.alpha.pineapple.web.account contains interfaces and classes for user account management:

• Account defines interface for user accounts.
• AccountImpl implements Account interface.

Reactor event support

The package com.alpha.pineapple.web.event contains interfaces and classes to support usage of Spring Reactor and mapping to ZK events:

• EventDispatcher defines the interface event dispatcher which supports dispatch of ZK events from Reactor consumers (i.e. non-GUI code).
• EventDispatcherImpl implements the EventDispatcher interface.
• WebAppResultListenerImpl implements the Pineapple EventListener interface which forwards Pineapple events of the type ExecutionResultNotification as Reactor events.

Reactor consumers

The package com.alpha.pineapple.web.event.consumer contains classes which implements the Reactor Consumer interface:

• ResultNotificationNotifierImpl implements a Reactor-to-ZK event transformer which notifies the GUI that an execution result has been produced by Pineapple core component. If the result is part of any user initiated execution then the execution panel view model should be updated.
• CreateReportImpl implements a report generator.
• CreatedReportNotifierImpl implements a Reactor-to-ZK event transformer which notifies the GUI that a report is generated and the report view should be updated.
• OpenModuleActivityInvokerImpl implements a Reactor-to-ZK event transformer which notifies the GUI that an open module activity should should performed again and that the GUI should be updated.
• ExecuteOperationActivityInvokerImpl implements a Reactor-to-ZK event transformer which notifies the GUI that an execute operation activity should should performed again and that the GUI should be updated.

ZK View Models

The package com.alpha.pineapple.web.zk.viewmodel contains ZK view model classes which backs views implemented in .zul files:

• DebugPanel - provides data for the Debug view.
• FooterPanel - provides data for the Footer view.
• ExecutionPanel - provides data for the Execution view.
• ScheduledOperationPanel - provides data for the Scheduled operation view.
• ActivityPanelPopup - provides data for the Activity popup view.
• ModulePanel - provides data for the Module view.
• OpenModuleModalPanel - provides data for the Open module modal view.
• DeleteModuleModalPanel - provides data for the Delete module modal view.
• ReportPanel - provides data for the Report view.
• UploadModuleModalPanel - provides data for the Upload module modal view.
• WorkspacePanel - provides data for the main Workspace view.
• EnvironmentConfigurationPanel - provides data for the main Configuration view.
• ResetCredentialPasswordModelPanel - provides data for the reset credential password modal view.
• CreateResourcePropertyModalPanel - provides data for the create resource property modal view.
• CreateModelModalPanel - provides data for the create model modal view.

<window apply="org.zkoss.bind.BindComposer" 
        binder="@init(queueName='pineapple-queue',queueScope='application')"
        viewModel="@id('vm') @init('com.alpha.pineapple.web.zk.viewmodel.ReportPanel')" 
        hflex="1" vflex="1" border="none" >

<window apply="org.zkoss.bind.BindComposer" 
        binder="@init(queueName='pineapple-queue',queueScope='application')"
        viewModel="@id('vm') @init('com.alpha.pineapple.web.zk.viewmodel.ActivityPanelPopup')" 
        hflex="1" vflex="1" border="none" >

ZK View Controllers

The package com.alpha.pineapple.web.zk.controller contains ZK composer classes for views which requires additional functionality that can be provided by a view model. If a view requires data then a view model is implemented. As result the composer shouldn't store any data in them:

• ExecutionPanel - implements controller functionality for the Execution view.
• Menu - implements controller functionality for the Menu bar..
• ModulePanel - implements controller functionality for the Model view.
• UploadModuleModalPanel - implements controller functionality for the Upload module modal view. The controller handles the upload of a zipped module into the module repository. The actual upload is implemented by ZK. The unpacking of the uploaded zipped module is handled by the asynchronous task UnpackModuleTask which unpacks the module archive into the module repository while updating the ZK view by sending UnpackedEntryEvent and UnpackModuleTaskEvent events.
• WorkspacePanel - implements controller functionality for the main Workspace view.

Asynchronous Tasks

The package com.alpha.pineapple.web.zk.asynctask contains asynchronous tasks which supports execution of long running processes while updating the ZK GUI by scheduling ZK events.

• AsyncTask - interface for asynchronous tasks. DEPRECATED.
• AsyncTaskHelper - Helper class for execution of asynchronous tasks and scheduling of ZK GUI events. DEPRECATED.
• UnpackModuleTask - Implementation of the AsyncTask interface which implement upload of a zipped and module unpacking it into the module repository.

ZK Events

The package com.alpha.pineapple.web.zk.asynctask.event contains ZK event classes which is used by asynchronous tasks to communicate updates to the ZK controllers.

• UnpackedEntryEvent - ZK event used by the UnpackModuleTask task to communicate that it have unpacked an entry (file or directory).
• UnpackModuleTaskEvent - ZK event used by the UnpackModuleTask task to communicate its progress in unpacking a file.
• ResultNotificationEvent - ZK event used by the ResultNotificationNotifierImpl consumer to dispatch a result notification event to an event handler.
• GenericEvent - ZK event used by the EventDispatcherImpl task to dispatch a generic event with no arguments to an event handler.

Asynchronous task visitors

The package com.alpha.pineapple.web.zk.asynctask.event.visitor contains interfaces for visitors which can receive events from asynchronous tasks:

• UnpackModuleTaskEventVisitor - interface for visitor which can receive task for the UnpackModuleTask task.

ZK lifecycle event listeners

The package com.alpha.pineapple.web.zk.lifecycle contains classes which implements the ZK lifecycle event listener interfaces:

• LifecycleEventListener - implements the ZK DesktopCleanup interface whose method is invoked when a ZK desktop is destroyed.

ZK converters

The package com.alpha.pineapple.web.zk.converter contains ZK converters which can convert data object into formats which can be rendered by views.

REST web service controllers

The package com.alpha.pineapple.web.spring.rest implements the REST web services:

• ConfigurationController - implements web services for configuration of Pineapple, e.g. CRUD on environment configuration entities.
• ExecuteController - implements web services for execution of operations in Pineapple.
• ModuleController - implements web services for management of modules in Pineapple.
• SystemController - implements web services for system information about Pineapple.

Utilities

The package com.alpha.pineapple.web.zk.utils contains utility classes:

• DetachConverter is an implementation of the Converter interface to detach a modal window.
• ErrorMessageBoxHelper is a helper class for showing a modal error message with details about an exception.

Pineapple Home directory configuration

The Pineapple Home directory will be set to the value of the pineapple.home.dir parameter in the web.xml whose default value is ${user.home}/.pineapple.

Logging configuration for Jetty

The plugin is configured to use Log4j for logging. The Log4j configuration file is located in src/test/resources/log4j.properties.

The Log4j configuration file is read by the Commons Logging bridge in Jetty which is configured by the plugin to use Log4j as logging implementation.

The file configures logging for ALL the pineapple components / jars which constitutes the web application, including log output from Jetty.

The configuration file configures Log4j to write log files to:

• ${pineapple.home.dir}/logs/pineapple-web-application-jettymavenplugin.log

The plugin is configured to set the System properties:

slf4j = false
log4j.configuration= file:./target/classes/log4j.properties

..which disables logging to slf4j and configures where the plugin will look for a Log4j configuration. Furthermore, the plugin requires the dependencies to commons-logging, slf4j-jcl and log4j for the Log4j based logging to work.