Context Navigation

jAPS2.0 - Plugin Pattern

Do It The jAPS Way

Eugenio Santoboni

First and complete version in Italian

Chief Solution Engineer
AgileTec s.r.l.

<e.santoboni@agiletec.it>

William Ghelfi

Porting to DocBook 4.5 and translation to English

Chief Interaction Designer
Tzente s.r.l.

<w.ghelfi@tzente.it>

Legal Notice

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the Appendix entitled "GNU Free Documentation License".

The copyright holders make no representation about the suitability of this Document for any purpose. It is provided “as is” without expressed or implied warranty. If you modify this Document in any way, identify your resulting Document as a variant of this Document.

2010-03-25

Revision History
Revision 1.6	2010-03-19	MEM
Update of the paragraph Directory: src, chapter Package structure: added informations about the global_messages_XY.properties. Revision for the release of the jAPS 2.0.10
Revision 1.5	2009-10-29	ES
Update of the i18n paragraph of the chapter Naming convention
Revision 1.4	2009-04-15	WG
Changes to the directory layout of a Plugin
Revision 1.3	2009-03-09	WG
English and docbook adoption
Revision 1.2	2009-02-09	ES
First public release

Abstract

This document covers the characteristics, structure and components of a jAPS-Plugin. It also provides the guidelines which Java developers must follow in order to build new plugins for the jAPS2.0 framework.

List of Examples

3.1. The Directory Layout of a typical Plugin (continue)
3.2. (continued) The Directory Layout of a typical Plugin
3.3. From a domain name to a package name
3.4. The proper name of a tld file for the public frontend
3.5. The proper name of a configuration file for Tiles
3.6. The proper name of a tld file for the administration area
3.7. Some proper subdirectories
3.8. Plugin jpuserprofile: proper path for the CSS of the public frontend
4.1. Name and id of a Plugin
4.2. From a domain name to a package name
4.3. Unit tests: From a domain name to a package name
4.4. Naming convention for a Struts2 Action
4.5. A proper path for a Strut2 Action
4.6. A proper package id for a Strut2 Action
4.7. Some sample labels for the frontend
4.8. Some sample labels for the backend

Chapter 1. Scope of the document

Table of Contents

Introduction

Target audience
Prerequisites
Resources

Introduction

This document covers the characteristics, structure and components of a jAPS-Plugin. It also provides the guidelines that Java developers must follow in order to create new plugins for the jAPS2.0 framework.

Target audience

This document is for developers aiming to build new plugins for jAPS2.0.

Prerequisites

In order to take the maximum advantage of the present document, it is necessary to have basic knowledge about: the Java platform, the Eclipse IDE, the Apache Tomcat servlet engine, the PosgreSQL DBMS.

Resources

Additional informations may be obtained through the following two mailing-lists:

<japs-devs@lists.sourceforge.net>, focused on developers
<japs-users@lists.sourceforge.net>, focused on final users

Is it also possible to refer to the documentation found in the:

jAPS 2.0 Project - Developer Website

Chapter 2. What is a jAPS-Plugin

A jAPS-Plugin is a module which can add new features to the jAPS2.0 framework or modify some existing ones.

The jAPS-Plugin is commonly also known as service, thus the principles guiding the process of writing a Plugin are basically the same guiding the development of a new service as described in the document jAPS2.0 - Service Creation and Integration Pattern.

The Plugins are classified as follows:

PurePlugins (a.k.a. so-called Plugins)
Modifications

A PurePlugin provides new features without any modification to the existing ones.

The PurePlugins are what we call ideal plugins because their impact on existing features tends to null, the use of two or more PurePlugins at the same time in the same instance of jAPS2.0 not causing any conflicts just because each and every module works well regardless of any other module.

As opposite, the Modifications are the ones which either expand, substituite, or modify (from slightly to deeply) the behaviour of the core elements of jAPS2.0.

Because of their massive impact on the system, they might come with specific install procedures and you may need to be very careful when installing a Modification in a system with other Plugins (both PurePlugins and Modifications). That becasue is not rare to have conflicts under such conditions.

In order to reduce to the minimum the risk of conflicts, the development of a Modification has to be done trying to limit the elements which interact with or modify the core; this fundamental achievement can be reached taking advantage of the elements given by the system and by the inner frameworks (like Spring and Struts2), i.e. the Event Notification service, the AOP, the Interceptors architecture which comes with Struts2, and many others.

Chapter 3. Structure of the package

Table of Contents

Structure of the package

The directory layout of a Plugin
Document: Readme
Directory: src
Directory: doc

Structure of the package

A Plugin has to be released in a package containing 3 fundamental elements:

Document: Readme
Directory: src
Directory: doc

The directory layout of a Plugin

The directory layout resembles the Standard Directory Layout from the Apache Maven Project.

Example 3.1. The Directory Layout of a typical Plugin (continue)

wiz@id:~/jAPS2-Plugin-jpuserprofile-1.0$ tree -dx
.
|-- doc
|   `-- jAPS2.0-Plugin_UserProfile
|       |-- fo
|       |   `-- img
|       |-- html
|       |   |-- css
|       |   `-- img
|       |-- pdf
|       `-- ps

Example 3.2. (continued) The Directory Layout of a typical Plugin

|
`-- src
    |-- java
    |   |-- main
    |   |   `-- com
    |   |       `-- agiletec
    |   |           `-- plugins
    |   |               `-- jpuserprofile
    |   |                   |-- aps
    |   |                   |   |-- externalframework
    |   |                   |   |   `-- common
    |   |                   |   `-- system
    |   |                   |       `-- services
    |   |                   |           `-- profile
    |   |                   |               `-- model
    |   |                   `-- apsadmin
    |   |                       |-- common
    |   |                       |   `-- attribute
    |   |                       |       `-- action
    |   |                       |           `-- list
    |   |                       `-- user
    |   `-- test
    |       `-- test
    |           `-- com
    |               `-- agiletec
    |                   `-- plugins
    |                       `-- jpuserprofile
    |                           |-- aps
    |                           |   |-- externalframework
    |                           |   |   `-- common
    |                           |   `-- system
    |                           |       `-- services
    |                           `-- apsadmin
    |                               `-- common
    |-- sql
    `-- webapp
        |-- WEB-INF
        |   |-- lib
        |   `-- plugins
        |       `-- jpuserprofile
        |           |-- aps
        |           |   `-- jsp
        |           |       `-- externalFramework
        |           |-- apsadmin
        |           |   |-- conf
        |           |   `-- jsp
        |           |       `-- common
        |           |           `-- template
        |           |               `-- extraresources
        |           `-- conf
        |               `-- managers
        `-- resources
            `-- plugins
                `-- jpuserprofile

62 directories

Document: `Readme`

The Readme is a short document (max 40 rows of 80 columns) explaining the features of the Plugin and the version of jAPS under which the Plugin is declared to have been developed and tested. The scope of the document is to give an immediate review of the Plugin.

Directory: `src`

This directory contains all the components necessary for integrating the Plugin in a jAPS2.0 based project using the Eclipse IDE (version 3.4 Ganymede) or later.

The directory contains:

Java sources

The Java classes of the Plugin must be written following the coding standard of jAPS2.0 framework. They must be gathered under the package <R_DOMAIN>.plugins.<PLUGIN_ID> where <R_DOMAIN> is the reversal of the domain name of the developer (company, association, web site, person...) of the Plugin.

Example 3.3. From a domain name to a package name

Company: MyCompany.com, package: com.mycompany.*

Every Class must come with proper Javadoc in english for an easy understanding of the code and of the application flow. Every interface and concrete class must have its Javadoc in the head part, and for every method and public or private variable. You may also want to write some Javadoc for complex or not-so-readable private methods.

If the Plugin adds elements to the administration GUI of jAPS2.0, in the root of java sources is mandatory to have a file named <PLUGIN_ID>-japs-struts-plugin.xml containing the references to file for configuration of defined actions.

The ...<CODICE_PLUGIN/src directory contains aps and apsadmin. The apsadmin always contains the global-messages_<LOCALE_CODE>.properties: the file(s) contains the global labels of the menu items and eventually of the interfaces.

Important

The property files must always contain at least the two following voices:

<PLUGIN_CODE>.code=<PLUGIN_CODE>
<PLUGIN_CODE>.name=<plugin description>

The libraries

There is a jAPSPlugin-<PLUGIN_ID>-<VERSION>.jar containing all the classes and packages described before, plus the optional libraries which may be necessary to the Plugin and are not present in the standard package of the jAPS2.0 framework.

The unit tests

Each feature of the Plugin must have a comprehensive set of unit tests; the test classes must be into a package named as follows: test.<R_DOMAIN>.plugins.<PLUGIN_ID>.

The test environment, in the initialization phase, must load the whole context from the core of jAPS2.0 and the beans of the Plugin optionally accompanied by the any other necessary bean.

The jsp files and the configurations

The name of this directory is the code of the plugin and it is placed into /WEB-INF/plugins/.

The directory contains the subdirectories aps, apsadmin, conf. The internal organization of these subdirectories is a perfect copy of the ones placed into the directory WEB-INF of the core of jAPS2.0.

The subdirectory aps contains the files needed by the public frontend (as opposite to the backend administration area) part of the Plugin.

The directory contains:

The subdirectory jsp/showlets, for any showlet coming with the Plugin
The subdirectory jsp/models, for any Page Model coming with the Plugin
The subdirectory jsp/externalFramework (optional), for the jsp files concerning any feature wich uses the External Framework special showlet.
The subdirectory tld, for the definitions of any custom tag.
Example 3.4. The proper name of a tld file for the public frontend
<PLUGIN_ID>-aps-core.tld

The subdirectory apsadmin contains the files needed by the backed administration area (as opposite to the public frontend) part of the Plugin.

The directory contains:

The subdirectory jsp, with a subdirectory for each component feature and all the jsp files for any needed administration GUI that has to be added to the main one
The subdirectory conf, with a subdirectory for each component feature and all the configuration files for any needed Action class (Spring Beans) and the configuration file for Tiles
Example 3.5. The proper name of a configuration file for Tiles
<PLUGIN_ID>-tiles.xml
The subdirectory tld, for the definitions of any custom tag.
Example 3.6. The proper name of a tld file for the administration area
<PLUGIN_ID>-apsadmin-core.tld

The subdirectory conf contains the configuration files of all the beans (Spring Object) used by the Plugin.

If the Plugin needs new DataSources or has its own paths used by any internal process, in the directory conf there must be two files which resemble the ones found in the standard package of the jAPS2.0 framework:

systemParams.properties: containing all the configurations.
systemConfig.xml: configuration file for Spring containing the placeholders for the properties defined in the other file and the definitions for the Bean DataSources (Spring Objects).

The optional directory extras contains resources or subdirectories needed by the Plugin which cannot find any other place in the filesystem as described before.

The needed static resources (CSS, images, Javascript...)

The files are placed into the directory /resources/plugins/<PLUGIN_ID>.

It resembles the structure, naming convention and organization of the main directory resources; thus, it may have two main subdirectories: administration and static with their own subdirectories.

Example 3.7. Some proper subdirectories

static/css, static/img, administration/js

Example 3.8. Plugin jpuserprofile: proper path for the CSS of the public frontend

/resources/plugins/jpuserprofile/static/css/

Directory: `doc`

The directory contains all the documentation for the Plugin.

There must be a document presenting the technical and functional characteristics, written in english, and containing the following informations:

The complete description of all the features and services provided by the Plugin
The declaration of the version of the Plugin, and of the version of jAPS2.0 declared compatible (ie: 2.0, or > 2.0.2, or >= 2.0, and so on). Any dependency with other Plugins (and their versions) must also be declared
The installation procedure, optionally accompanied by any needed SQL script
The instructions for installing the Plugin in a development environment based on Eclipse IDE version 3.4 Ganymede. You must also provide the instructions for properly configure the unit tests
The flavour of the Plugin (PurePlugin or Modification). If the Plugin is a Modification, you must declare and give detailed explaination of each and every feature of the core of jAPS2.0 which is subject of changes; you must also declare each and every Bean (Spring Object) overwritten by the Modification and the modified GUIs.

Chapter 4. Naming convention

Table of Contents

Naming convention

Name and Id
Sources
Name of the jar
Directory under WEB-INF/plugins
Static resources
Beans (Spring Objects) in the core of the Plugin
Beans (Spring Objects) of the Actions (Struts2 Objects)
Tiles
i18n
Permissions
Bean for a sub-menu in the backend
Database tables
Configuration items (table sysconfig, database *Port)

Naming convention

The following is the naming convention to be adopted during the development of a Plugin.

Name and Id

The id of the Plugin is unique, it must have the prefix jp, all lowercase, and it must contain alphabetic characters only (no numbers, special characters, nor spaces).

The id is different from the name because the name allows special characters and spaces.

Example 4.1. Name and id of a Plugin

User Profile is the name of the Plugin whose id is jpuserprofile.

Sources

Example 4.2. From a domain name to a package name

Company: MyCompany.com, package: com.mycompany.plugins.<PLUGIN_ID>

Example 4.3. Unit tests: From a domain name to a package name

Company: MyCompany.com, package: test.com.mycompany.plugins.<PLUGIN_ID>

This syntax resembles the one defined in the [Java Language Specification by Sun Microsystems].

Name of the `jar`

The name of the jar must be: jAPSPlugin-<PLUGIN_ID>-<VERSION>.jar.

Directory under `WEB-INF/plugins`

The name of the directory containing all the jsp and configuration files must be equale to the Plugin id: WEB-INF/plugins/<PLUGIN_ID>.

Static resources

See the previous chapters.

Beans (Spring Objects) in the core of the Plugin

In order to avoid any overwriting of names used in the main core or by other Plugins, the ids of the Beans must be prefixed with the plugin id. In the particular case of a Manager, the id must be <PLUGIN_ID><SERVICE_NAME>Manager.

Moreover, if a Plugin overwrites a Bean of the main core or of another dependent Plugin the id of that Bean must be the same of the one overwritten. Detailed informations must also be provided in the technical documents.

Beans (Spring Objects) of the Actions (Struts2 Objects)

See the previous paragraph. Besides, also the paths of all the Actions must avoid overlappings with the paths used in the main core or in other Plugins.

Here are the proper syntaxes for definitions of the Actions:

The paths in the namespaces must have the id of the Plugin after the string used for the mapping of the Struts2 filter.
Example 4.4. Naming convention for a Struts2 Action
/do/<PLUGIN_ID>/<SUB_PATH>

Example 4.5. A proper path for a Strut2 Action
/do/jpuserprofile/CurrentUser/edit.action
The ids of the packages must be in the form <PLUGIN_ID>_do/<PLUGIN_ID>/<SUB_PATH>
Example 4.6. A proper package id for a Strut2 Action
jpuserprofile_do/jpuserprofile/CurrentUser

Tiles

In order to avoid any overwriting of names used in the main core or by other Plugins, the ids of the Tiles Definitions must use the plugin id as follows: admin.<PLUGIN_ID>.<FEATURE>.<NAME_OF_THE_VIEW>

i18n

If the Plugin has its own GUIs for the public frontend, you must provide the proper labels (which are stored in the database table localstrings and are outputted through the wp:i18n custom tag). I.e. labels for forms, subtitles, notes, and so on.

Example 4.7. Some sample labels for the frontend

jpuserprofile_SEARCH_FORM = Search
jpuserprofile_ADDRESS_COUNTRY = Country

The same is for any GUI in the administration backend. In this case you must provide the files package_<LANG_CODE>.properties as described in the document jAPS2.0 - Service Creation and Integration Pattern.. As always, both frontend and backend keys must avoid any overlapping of the ones in the main core or other Plugins. This can be achieved properly using the id of the Plugin as a prefix.

Example 4.8. Some sample labels for the backend

jpuserprofile.mylabel = My really simple label
jpuserprofile.myarea.myotherlabel = This is a note, just like the one up there

Furthermore, for the back-end interfaces, each plugin must have a property file named in the package <R_DOMAIN>;.plugins.<PLUGIN_ID>.apsadmin. This file must include the base label plugin (labels of code <PLUGIN_ID>.code and <PLUGIN_ID>.name) as well as any other label for the general menu Plugins.

Permissions

If the Plugin introduces new permissions, the id of each permission must be prefixed by the id of the Plugin followed by an underscore (_ character).

Bean for a sub-menu in the backend

The id of the Bean for a sub-menu of the Plugins menu item, must be as follows: <PLUGIN_ID>SubMenu.

Database tables

The names of the tables in either the *Port or *Serv database, must be prefixed by the id of the Plugin followed by an underscore (_ character).

Configuration items (table `sysconfig`, database `*Port`)

The names of the configuration items must be prefixed by by the id of the Plugin followed by an underscore (_ character).

Download in other formats:

Plain Text

Context Navigation

jAPS2.0 - Plugin Pattern

Do It The jAPS Way

Eugenio Santoboni

William Ghelfi

Chapter 1. Scope of the document

Introduction

Target audience

Prerequisites

Resources

Chapter 2. What is a jAPS-Plugin

Chapter 3. Structure of the package

Structure of the package

The directory layout of a Plugin

Document: Readme

Directory: src

The directory contains:

Important

Directory: doc

Chapter 4. Naming convention

Naming convention

Name and Id

Sources

Name of the jar

Directory under WEB-INF/plugins

Static resources

Beans (Spring Objects) in the core of the Plugin

Beans (Spring Objects) of the Actions (Struts2 Objects)

Tiles

i18n

Permissions

Bean for a sub-menu in the backend

Database tables

Configuration items (table sysconfig, database *Port)

Download in other formats:

Document: `Readme`

Directory: `src`

Directory: `doc`

Name of the `jar`

Directory under `WEB-INF/plugins`

Configuration items (table `sysconfig`, database `*Port`)