Joy Configuration


Class Tree

Le framework comes with this hierarchy and organization.

  • com.joy
    • api
      • beans
      • filter
      • ready
      • utils
    • auth
    • bo
      • init
      • ora
      • pg
      • registry
    • charts
      • chartjs
      • gaugejs
    • common
      • filter
      • parameters
      • state
    • etl
    • json (Cf. https://github.com/stleary/JSON-java)
    • listener
    • providers
    • tasks
      • filter
    • C.java
    • JOY.java

I suggest to create the Javadoc after importing the framework (download here).

To simplify all, i created an empty J2EE on Github (joytemplate), you can also start by using it (download here). If you want real example, just download myKiraData.

Create a new J2EE project

First of all create (or reuse the joy template project) a J2EE project. This project will encapsulate Joy as a RestFul container.

If you create a project from scratch the chapters below describes all the mandatory files.

web.xml

As all J2EE project you have to create a web.xml file. This file will have at minimum these entries.

   <display-name>joyEmpty</display-name>
   <servlet>
      <servlet-name>mainHandler</servlet-name>
      <servlet-class>com.joy.mvc.controller.JoyController</servlet-class>
   </servlet>
   <servlet-mapping>
   <servlet-name>mainHandler</servlet-name>
   <url-pattern>/joyEmpty</url-pattern>
   </servlet-mapping>

This XML tag section refers to the main joy servlet. This servlet call must not be changed as it is the main Joy controller (it gets and manage all the http requests).
However you can change here the to match with your desire as url call. Here again the future URL call would looks like this : http://myserver/joyEmpty

   <welcome-file-list>
   <welcome-file>index.html</welcome-file>
   </welcome-file-list>

This section is clearly optional as you want to precise a default web page here.

   <context-param>
     <param-name>joy-parameters</param-name>
     <param-value>joy-parameters.xml</param-value>
   </context-param>
   <context-param>
     <param-name>joy-rest</param-name>
     <param-value>rest-config.json</param-value>
   </context-param>
   <context-param>
     <param-name>joy-task</param-name>
     <param-value>task-config.json</param-value>
   </context-param>

In this section you must mention 3 parameters. You can naturally make some changes here (or add new ones) but it is advised to not change the xml files names.
These are the 3 parameters :

  • joy-parameters.xml : is the file in which you could add and manage all your global application parameters.
  • rest-config.json : contains the restful configuration (match table with tag and java classes).
  • task-config.json: contains all the asynchronous tasks (and configuration) you would have to manage in your application.

These files are described later.

   <filter>
     <filter-name>Auth</filter-name>
     <filter-class>com.joyempty.auth.dgmJoyEmptyFilter</filter-class>
   </filter>
   <filter-mapping>
      <filter-name>Auth</filter-name>
      <url-pattern>/auth/*</url-pattern>
      <dispatcher>REQUEST</dispatcher>
   </filter-mapping>
   <filter>
     <filter-name>restAPI</filter-name>
     <filter-class>com.joy.api.filter.FilterAPI</filter-class>
   </filter>
   <filter-mapping>
     <filter-name>restAPI</filter-name>
     <url-pattern>/api/*</url-pattern>
     <dispatcher>REQUEST</dispatcher>
   </filter-mapping>
   <filter>
     <filter-name>taskFilter</filter-name>
     <filter-class>com.joy.tasks.filter.FilterTask</filter-class>
   </filter>
   <filter-mapping>
     <filter-name>taskFilter</filter-name>
     <url-pattern>/task/*</url-pattern>
     <dispatcher>REQUEST</dispatcher>
   </filter-mapping>

The three filters above must be mentionned as they are (no changes). They reflect the three ways to call the framework :

  • Synchronously : by using the REST standard
  • Asynchrounously : by using tasks
  • Authentication (this has to be done in another separate way)

Joy configuration files

After creating the web.xml file you have to create (or copy/modify) several files into the classes directory (under WEB-INF).

task-config.json

This file contains all the task you will have to manage. A task is simply an asynchrounous treatment your application will have to launch. Joy is able to manage this king of runs, and to do that just follow these steps.

First create a new entry in this file like this :

{
   "version": "1.0",
   "services": [
       { "name": "task1", "class": "com.dgm.tasks.load.task1" }
   ]
}

Task1 is the reference to the task itself and com.dgm.tasks.load.task1 is the class in charge to manage the asynchrounous call. This class must inherit the Joy Class ActionTypeTASK and override the taskExecute() function like this.

import com.joy.tasks.JoyTaskStatus;
public class TASKLoadProcess extends TASKCommonLoad {
    @Override
    public JoyTaskStatus taskExecute() {
        return this.loadInternalLanding();
    }
}

rest-config.json

This file contains all the rest call (your api) you will have to manage. Just be inspired by this sample to fulfil this file:

 
{
   "version": "1.0",
   "services": [
   {
       "name": "taskslist",
       "class": "com.joy.api.ready.RESTTasksList",
       "mime": "application/json"
   },
   {
       "name": "relterm",
       "class": "com.dgm.api.RESTActionTermsInFolders",
       "mime": "application/json"
   }, ...

The name is reflecting the tag of the rest call. The class is the treatment in charge and the MIME type precise the type of data returned byt the class.
The class used to manage the treatments have to inherit the ActionTypeREST Joy class.

navi-config.json

This file contains all the availables web files (mainly html) for navigation. The java framework does not manage the navigation itself however this file is retreived by the client (javascript) at the beggining and stays at client level for navigation. This way of storing the file here protect the navigation.

{
"version": "1.0",
"default": "home.html",
"error": "error.html",
"list": [
{ "tag": "home", "url": "home.html" },
{ "tag": "about", "url": "about.html" },
{ "tag": "login", "url": "login.html" },

...

The tag is the label used by the joy client framework to call the effective web page.

logging.properties

This file is the log4J configuration file.

joy-parameters.xml

This file contains all the application parameters (global and static ones). It also contains mandatory parameters managed and used by the framework itself.

Parameter Mandatory Uses/Description
api-start-path yes Must be equal to the url-pattern tag value in web.xml
bundle-message yes Property file prefix for all the messages. The property files must be present into the /classes folder. (Example : for the dgm_fr_FR.properties file put dgm here)
default-dateformat yes Default date format
joy-version yes Joy Version
joy-app-name yes Application name
no-login yes Deactive or not the mandatory login process yes/no
auth-private-key yes Encryption key (application)
joy-entities yes This tag (multiple values inside) includes all the joy entities managed.
joy-menus yes This tag (multiple values inside) includes all the joy menus managed.
joy-navi yes Navigation configuration (See above)
joy-mappings yes This tag (multiple values inside) includes all the configuration mappings for transporting data.
joy-session-timeout yes Session timeout (in min)
joy-localelanguage

joy-localecountry

yes Localisation
app-parameter name no [Multiple occurence possible]

You can specify any value needed by your application here

app-parameter name no [Multiple occurence possible]

You can specify any array of values for your application here

joy-entity.xml

This file contains all the entity (data objects) managed by the application. The goal here is to prevent any SQL code into your application development. This file is unique but refers to many other declarative files, it can be viewed as a kind of data objet registry.

These are the mandatory declarations :

  • joy-datasource : put here the JDBC datasource name (you can put the technical declaration of this into the context.xml for example).
  • joy-jdbc-driver : specify the JDBC driver
  • joy-jdbc-url : specify the JDBC url
  • joy-jdbc-user : specify the data user
  • joy-jdbc-pwd: specify the data user password
  • joy-db-plugins : per database object type you can specify here the java classes in charge of the SGBD specificities.
  • joy-query-init: Per database, you can optionnaly specify an initial SQL query.

After these global parameters, you can register all you entities configuration files into the joy-registry tag.

<joy-registry>
    <joy-entity name="Last Facts Only" type="query" file ="/entity/joy-entity-shared.xml" />
    <joy-entity name="Analytics - Terms Global Score Calculation" type="query" file ="/entity/joy-entity-shared.xml" />
    <joy-entity name="Terms with Glossary information" type="composite" file ="/entity/joy-entity-shared.xml" />
    ...

joy-entity.xml files

These files stores all the configuration for the data objects (joy entities) managed by the framework.

You can declare several kinds of entities :

The entity : Table

<joy-entity name="APP_PARAMS">
    <joy-init-record>
    <joy-field name="...">...</joy-field>
    ...
    </joy-init-record>
</joy-entity>

This entity is exaclty the SQL table you cann access through your JDBC Connection.
the joy-field tag enables you to specify initial record to insert automatically in case of initialization for example.

The entity : Query

<joy-entity name="Mandatory name">
    <!-- SQL Query here
    AND/OR You can add DB specifics by using
    <POSTGRESQL></POSTGRESQL>
    <ORACLE></ORACLE> -->
</joy-entity>

Specify here a custom query to apply into the datasource. The framework allows you specify different queries considering the DB.

The entity : Composite

This entity allows you to build query by configuration.

<joy-entity name = "Composite name" distinct="yes/no">
    <joy-entity alias="[Left Table Alias]" as="[As in Select/To rename the selected field]">...</joy-entity>
    <joy-field alias="[Table Alias for selected field]">[Left IEntity]</joy-field>
    <joy-field ...></joy-field>
    <joy-join type="INNER/LEFT/RIGHT [Single JOIN by default]">
        <joy-entity alias="[Right Table Alias]">[Right IEntity]</joy-entity>
        <joy-join-key master="[Left field Key]" slave="[Right field Key]" />
    </joy-join>
    <joy-join type="...">...</joy-join>
    <joy-filter alias="[Table Alias for filter field]" field="[Filter field]" operator="&lt;&gt;[Or anything else]">[Filter]</joy-filter>
    <joy-filter>...</joy-filter>
    <joy-sort alias="[Alias Sort field]" desc="[no/yes]" />[sort field]</joy-sort>
    <joy-sort ... />
    <joy-group alias="[Table Alias for grouped field]">[Group Field]</joy-group>
    <joy-group ... />
</joy-entity>

This entity builder enables you to use : joins, filters, sorts and groups. You can also combines multiple entities to get complex queries

joy-mappings.xml

This file contains all the needed configuration for moving data from an joy entity to another.

Example :

<joy-mapping id="Term RelationShips Landing" entity-from="Load - get Relationship" entity-to="DIM_TERM_RELLINKS" filter="JOYSTATUS='L'">
    <map to="TRL_PK" key="yes" />
    <map to="TRL_FUNCKEY" from="JOYFUNCKEY" check-if-exist="yes"/>
    <map to="OBJECT_ID_SOURCE" from="REL_KEY_TERM_SOURCE"/>
    <map to="OBJECT_ID_TARGET" from="REL_KEY_TERM_TARGET" />
    <map-lookup to="REL_FK">
        <entity-lookup>DIM_TERM_RELATIONSHIP</entity-lookup>
        <entity-lookup-key>REL_PK</entity-lookup-key>
        <lookup-condition lookup-key="REL_NAME" from="REL_NAME"/>
    </map-lookup>
</joy-mapping>

Each mapping is declared with the joy-mapping tag. into this mapping you must specify each concerned field (map tag). A target field (tag property : to) must match with a source field (tag property : from) or a hard value (like sysdate for the current date).
The framework also manages automatic lookups to match with external data. in the example above the table DIM_TERM_RELATIONSHIP is used to get the REL_PK field value (DIM_TERM_RELATIONSHIP.REL_PK) and to put it into the target field REL_FK.