Class Tree
Le framework comes with this hierarchy and organization.
- com.joy
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.
[code language= »XML »]
<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>
[/code]
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
[code language= »XML »]
<welcome-file-list>
<welcome-file>index.html</welcome-file>
</welcome-file-list>
[/code]
This section is clearly optional as you want to precise a default web page here.
[code language= »XML »]
<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>
[/code]
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.
[code language= »XML »]
<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>
[/code]
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 :
[code language= »CSS »]
{
"version": "1.0",
"services": [
{ "name": "task1", "class": "com.dgm.tasks.load.task1" }
]
}
[/code]
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.
[code language= »JAVA »]
import com.joy.tasks.JoyTaskStatus;
public class TASKLoadProcess extends TASKCommonLoad {
@Override
public JoyTaskStatus taskExecute() {
return this.loadInternalLanding();
}
}
[/code]
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:
[code language= »CSS »]
{
"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"
}, …
[/code]
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.
[code language= »CSS »]
{
"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" },
…
[/code]
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.
[code language= »XML »]
<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" />
…
[/code]
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
[code language= »XML »]
<joy-entity name="APP_PARAMS">
<joy-init-record>
<joy-field name="…">…</joy-field>
…
</joy-init-record>
</joy-entity>
[/code]
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
[code language= »XML »]
<joy-entity name="Mandatory name">
<!– SQL Query here
AND/OR You can add DB specifics by using
<POSTGRESQL></POSTGRESQL>
<ORACLE></ORACLE> –>
</joy-entity>
[/code]
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.
[code language= »XML »]
<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="<>[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>
[/code]
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 :
[code language= »XML »]
<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>
[/code]
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.