StartGuideForStrutsApp

This guide is relevant to 1.2.x versions of Struts. The Jharks Workflow Survey Engine build is compatible with the 1.2.x versions of Struts.

1 Download the Jharks workflow-<version>.jar</version> and include in your applications library dependencies.

2 Download the Jharks workflow-survey-engine-<version>.jar</version> and include in your applications library dependencies.

3 Add the key Jharks Workflow Survey Engine action mapping within the Struts config file.

    <action
       path="/jharksContinueWorkflow"
       type="org.jharks.workflow.survey.engine.web.struts.SurveyEngineFrontAction"
       validate="false"
       scope="request"
       >
       <forward name="jharksDynamicSurveyPage" path="jharks_survey_page.tiles" redirect="false"/>
       <forward name="jharksWorkflowEndView" path="jharks_end_page.tiles" redirect="false"/>
    </action>

The path can be whatever value you want to standardize on within your application.

The type needs to be set the Jharks Workflow Survey Engine front controller implementation that is part of the workflow-survey-engine jar, org.jharks.workflow.survey.engine.web.struts.SurveyEngineFrontAction.

The validate attribute should be set to false.

The scope attribute should be set to request.

Then you basically need to configure two forwards for the action mapping by the standard Jharks names jharksDynamicSurveyPage and jharksWorkflowEndView. The example demonstrates these pointing to two tile resources, but these can be just jsp resources as well. That will all depend on whether your are using Tiles within your application or not.

You can create the structure yourself for both the jharksDynamicSurveyPage and the jharksWorkflowEndView. There is no requirement on any specific jharks code that needs to be placed in the jharksWorkflowEndView. But there are Jharks code requirements within the jharksDynamicSurveyPage and the specifics are listed below:

You need to make a reference to the Jharks Workflow Survey Engine taglib

<%@ taglib uri="/workflow-survey" prefix="jharks" %>

And then you need to include the call to the jharksWorkflowSurvey tag.

<jharks:jharksWorkflowSurvey surveyXml="${requestScope.surveyXml}" path="jharksContinueWorkflow.do"/>

**Note: The path value specified in the tag must match the name you specified within the path attribute of the Struts action mapping.

4 You need to make sure you include in the jharks web resources (javascripts and css files) into your project and make sure you refer to them from within your web pages.

<link rel="stylesheet" type="text/css" href="<c:url value="/jharks/css/jharks-survey-engine.css" />" /> 
<script type="text/javascript" src="<c:url value="/jharks/js/jharksSurveyEngine.js" />"></script>

You will notice the use of jstl tag url within the src and href values. This is the recommended approach to handle the application root context instead of hard coding it within your references.

5 If you are already using Spring in your application then the next step is easy. You need to add in the wiring for the Spring components of the Jharks Workflow Survey Engine. The following content needs to be specified in your Spring application context file:

<bean id="org.jharks.questionGroupConfigCache" class="org.jharks.workflow.survey.engine.cache.EhCacheBasedQuestionGroupCache">
            <property name="cache">
                <bean
                    class="org.springframework.cache.ehcache.EhCacheFactoryBean">
                    <property name="cacheManager">
                        <ref bean="org.jharks.cacheManager"/>
                    </property>
                    <property name="cacheName" value="org.jharks.questionGroupConfigCache" />
                    <property name="eternal" value="false" />
                    <property name="overflowToDisk" value="false" />
                    <property name="timeToLive" value="86400" />
                </bean>
            </property>
</bean>

<bean id="org.jharks.cacheManager" class="org.springframework.cache.ehcache.EhCacheManagerFactoryBean"/>

<bean id="org.jharks.questionManager" 
    class="org.jharks.workflow.survey.engine.service.impl.QuestionManagerImpl">
    <property name="questionDao">
      <ref bean="org.jharks.questionDao"></ref>
    </property>
    <property name="questionGroupConfigCache">
      <ref bean="org.jharks.questionGroupConfigCache"></ref>
    </property>
 </bean>

 <bean id="org.jharks.responseManager" 
    class="org.jharks.workflow.survey.engine.service.impl.ResponseManagerImpl">
    <property name="responseDao">
      <ref bean="org.jharks.responseDao"></ref>
    </property>
    <property name="answerRetriever">
      <ref bean="org.jharks.answerRetriever"></ref>
    </property>
 </bean>

 <bean id="org.jharks.surveyPersistenceManager" class="org.jharks.workflow.survey.engine.service.impl.SurveyPersistenceManagerImpl">
  <property name="surveyPersistenceDao">
    <ref bean="org.jharks.surveyPersistenceDao" />
  </property>
 </bean>

 <bean id="org.jharks.xmlDefintionService" class="org.jharks.workflow.survey.engine.service.impl.XmlWorkflowDefinitionServiceImpl">
  <property name="xmlDefinitionDao">
    <ref bean="org.jharks.xmlDefinitionDao"/>
  </property>

 <!-- DAO Mappings -->
<bean id="org.jharks.answerRetriever" class="org.jharks.workflow.survey.engine.web.SurveyAnswerRetrieverRequestImpl"/>

<bean id="org.jharks.questionDao" class="org.jharks.workflow.survey.engine.dao.impl.QuestionJdbcDaoImpl" init-method="populateQuestionIds">
  <property name="dataSource">
    <ref bean="org.jharks.dataSource"/>
  </property>
</bean>

<bean id="org.jharks.responseDao" class="org.jharks.workflow.survey.engine.dao.impl.ResponseJdbcDaoImpl" init-method="init">
  <property name="dataSource">
    <ref bean="org.jharks.dataSource"/>
  </property>
  <property name="questionDao">
      <ref bean="org.jharks.questionDao"></ref>
    </property>
</bean>

<bean id="org.jharks.surveyPersistenceDao" class="org.jharks.workflow.survey.engine.dao.impl.SurveyResponseJdbcPersistenceDaoImpl">
  <property name="dataSource">
    <ref bean="org.jharks.dataSource"/>
  </property>
  <property name="questionDao">
    <ref bean="org.jharks.questionDao"/>
  </property>
</bean>

<bean id="org.jharks.xmlDefinitionDao" class="org.jharks.workflow.survey.engine.dao.impl.XmlWorkflowDefinitionDaoImpl">
  <property name="dataSource">
    <ref bean="org.jharks.dataSource"/>
  </property>
</bean>

<bean id="org.jharks.dataSource" class="org.springframework.jndi.JndiObjectFactoryBean">
   <property name="jndiName" value="jdbc/**app_datasource**"/>
 </bean>

The one value you will need to specify/change in the above snippet is the jndiName of the org.jharks.dataSource bean. You need to appropriately create a datasource within your application server for your web application. The jndi name you configure for that datasource within your application server must be the value you use within the spring configuration for jharks.

You also must add in the ehcache configuration for jharks. Either add the following entry to your existing ehcache configuration file

 <defaultCache
    maxElementsInMemory="10000"
    eternal="false"
    timeToIdleSeconds="120"
    timeToLiveSeconds="120"
    overflowToDisk="true"
    diskPersistent="false"
    diskExpiryThreadIntervalSeconds="120"
    memoryStoreEvictionPolicy="LRU"
    />

or add a file named ehcache.xml under WEB-INF/classes in your web application with the content.

<ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="ehcache.xsd">
<diskStore path="java.io.tmpdir"/>
<!--    <cacheManagerEventListenerFactory class="" properties=""/>-->
<!--
Mandatory Default Cache configuration. These settings will be applied to caches
created programmtically using CacheManager.add(String cacheName).
The defaultCache has an implicit name "default" which is a reserved cache name.

    diskSpoolBufferSizeMB="30"
    maxElementsOnDisk="10000000"
-->
<defaultCache
    maxElementsInMemory="10000"
    eternal="false"
    timeToIdleSeconds="120"
    timeToLiveSeconds="120"
    overflowToDisk="true"
    diskPersistent="false"
    diskExpiryThreadIntervalSeconds="120"
    memoryStoreEvictionPolicy="LRU"
    />   
</ehcache>

6 Add workflow.properties file for the Jharks Workflow Engine to WEB-INF/classes directory within your web application.

###########################################
# Deployment Properties
###########################################

xml-base-directory = etc

###########################################
#Default formats
default.date.format = MM/dd/yyyy HH:mm

###########################################
# Configuration of value handlers to handle 
# Answer value objects that are standard java objects
# other than Strings, or custom value object 
# implementations.
#
###########################################
# Standard java classes
java.util.Date-handler = org.jharks.workflow.handlers.DateValueHandler

# Custom classes would be entered below

7 Add the workflow.xsd schema definition to WEB-INF/classes directory wthin your web application.

8 Add a JharksWorkflowSurveyResources.properties to WEB-INF/classes directory within your web application.

###################################
# Configure the database schema that contains the Jharks Workflow Survey Engine
# related database tables. If this value is left blank then it is assumed the
# the database user configured in the application org.jharks.datasource is the
# same database user as the database user that owns the schema were the Jharks
# related tables exist.  If there is a value populated then queries within Jharks
# will reference the specified schema to access database objects. 
###################################
database.schema = quality

###################################
# Set the workflow.resource.bundles.db.backed to true if you want to retrieve
# the Jharks resource bundles used for text insertion and internationalization
# from the database instead of the classpath.  Note: you will need to populate
# the WORKFLOW_RESOURCE_BUNDLE database table appropriately to use this feature. 
###################################
workflow.resource.bundles.db.backed = true

9 Depends If the property workflow.resource.bundles.db.backed = false in the JharksWorkflowSurveyResources file then the Jharks Workflow Survey Engine is coded to leverage a ResourceBundles placed in the classpath WEB-INF/classes.

10 The infrastructure and integration should be in place to now start building Jharks surveys within your Struts based web application. Now you just need to learn how to create your first Jharks Workflow Definition xml file and define the content (questions for each Survey page).