Re3gistry software v1.2 - Documentation

The documentation is a "living document": if you find some problems or you have suggestions, please write to: inspire-registry-dev@jrc.ec.europa.eu

Index

  1. Overview
  2. Re3gistry software model
  3. System description
  4. System installation and first run
  5. Serving the registry contents
  6. Customization (create your own registry/registers)
  7. Developer documentation

 

Getting started with the Re3gistry software

https://ies-svn.jrc.ec.europa.eu/projects/registry-development/wiki/Re3gistry_1_2_quick_install

Service customisation guide (create a customized service)

Data customization

https://ies-svn.jrc.ec.europa.eu/projects/registry-development/wiki/Re3gistry_1_2_quick_customisation

Web service application customization

https://ies-svn.jrc.ec.europa.eu/projects/registry-development/wiki/Re3gistry_HTML_webapp_documentation

 

Overview

Disclaimer

The software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.

Acknowledgements

As part of the Interoperability Solutions for European Public Administrations (ISA) Programme, the European Commission’s (EC) Joint Research Centre (JRC) is establishing a Reusable INSPIRE Reference Platform  (ARE3NA) which is identifying and developing common components for the successful implementation of the INSPIRE Directive.

The work on the Re3gistry addresses a missing component of INSPIRE as an open source solution for use in other contexts, including those who want to manage multilingual code lists in various levels of public administration in Europe.

This software has been engineered by the ISA founded resources Daniele Francioli and Emanuela Epure.

We are also grateful for the review of this document to Lorena Hernandez Quiros and Robin S. Smith.

 

http://ec.europa.eu/isa/actions/01-trusted-information-exchange/1-17action_en.htm
https://joinup.ec.europa.eu/community/are3na/description
Re3gistry software https://joinup.ec.europa.eu/software/re3gistry/home
INSPIRE registry service http://inspire.ec.europa.eu/registry/

 

To provide feedback on the software/service we kindly invite you to use this service: https://joinup.ec.europa.eu/software/re3gistry/home

 

Contact information

Michael Lutz

European Commission – Joint Research Centre

Institute for Environment and Sustainability

Spatial Data Infrastructures Unit

E-mail: inspire-registry-dev@jrc.ec.europa.eu

http://ies.jrc.ec.europa.eu

http://www.jrc.ec.europa.eu

 

Purpose

This document provides details about the Re3gistry, an open source tool for the management of codelists and other key terms within the scope of the Infrastructure for Spatial Information for Europe (INSPIRE) Directive 2007/2/EC. A background to this work is provided (Section 2), followed by a description of the information model (Section 3) and a description of the overall system (Section 4). Data module and Data Staticization (Section 4) functions are then described before focussing on the web service (Section 7). The last two sections list the technical components used in the Re3gistry (Section 8) and the installation instructions (Section 9).

Changes in this version

This is the v1.2 of the Re3gistry software. Changes in this version:

  • New authentication method added - Apache SHIRO
  • Addition of the new webapp. nthe web application reads the data from the JSON format produced by the Re3gistry software to produce the web pages of the service).
  • New functionality: manually start the data export of the full content of the database
  • Added a domain neutral example in the project package
  • Configuration files improvement
  • Documentation improvement
  • Bug fixes

 

Background

The European Union (EU) Member States are currently implementing the INSPIRE Directive and related regulations.  Technical guidelines for INSPIRE’s implementation, based on existing international standards, have been developed or are currently under development. Interoperability between systems is, however, being limited by varying ways of implementing standards, the regular evolution of standards and challenges in coordinating changes between standards, alongside varying choices in the technologies being adopted.

To further address these interoperability issues and provide support to the Member States, the platform will provide guidance, collaboration, sharing of best practices and approaches and a reference implementation of common components through the following activities:

  • Inventory of
    • Existing INSPIRE components from the Open Source community;
    • Components used within the Member States to implement INSPIRE;
    • Missing components;
  • Selection of other policies and initiatives from other sectors (such as INSPIRE, Water Framework Directive, Digital Agenda for Europe, open data, Shared Environmental Information System (SEIS) etc.;) requiring exchange and sharing and maintenance of spatial data sets and services.
  • Selection of the missing components and/or functionalities. Multilingual support is envisioned where required;
  • Support Open Source projects to develop the missing items and produce the related documentation (installation guides and technical documentation in several languages);
  • Selection and development where required of conformance test suites;
  • Set up a collaborative platform to share and maintain the components

The outputs of this work will also appear on the ISA programme collaborative platform, JoinUp, to aid wide re-use.

 

Re3gistry software model

The Re3gistry software is an open source solution to help managing and sharing ‘reference codes’ in different languages. The Re3gistry allows a central access point to be set up where labels and descriptions for reference codes can be easily checked by humans or retrieved by machines. It provides the consistency and support organizations needs to manage and share their reference codes.

The following documentation provides details related to the Re3gistry software, including the installation instructions. It provides also several user guides including a guide to create a custom registry service starting from an example and a guide to extend the software by creating new modules.

 

Information Model

The Re3gistry software retrieves the registry contents from a simple (text based) data file. It organizes and exports the data in different formats (e.g. XML, Json, RDF). The produced files can then be served through a customizable web service.

A simple representation of the system’s information model is shown below (fig. 1), with the following paragraphs describing each entity that can be found in the system. The complete information model can be found at Annex 1.

Figure 1 - Simplified information model

Re3gistry software - Simplified information model

Registry

A registry is an information system on which registers are maintained [ISO 19135].

 

Register

A register is a single controlled collection (list) of items with unique identifiers. Each register is operated on behalf of some owner organisation that provides the authority for the collection.

The type of item that can be entered in a register is completely open (e.g. anything which can be given a Uniform Resource Identifier (URI) can be registered).

 

Item Class

The item class represents set of items with common properties. It defines a group of items contained in a specific register.

For example, in a “theme register”, such as a register for the INSPIRE Theme, the item class of the items contained can be referred to as “theme items”.

Item class can have parent/child relations to identify if the items are part of a collection. For example, in the INSPIRE Registry, the “codelist register” has two item class: CodeList and CodeListValue. The CodeList item class is the father of CodeValue. The CodeValue item class contains the items that are part of the “Code List” collection. This means that this collection relation is between items belonging to different item classes. The "collection" relation and the hierarchy between the item classes is used to handle the hierarchical registers.

 

Item

The Items are elements that can be contained in a register. An item can contain other child items. For example, in the INSPIRE registry [INS-REG], the item class “CodeList” could contain other items (items with item class “CodeListValue”). The contained item (the “code list value item”), has an indication of the collection within the collection_id field (for detailed information please see the complete information model Annex 1).

Another type of relation between items of the same item class is the parent/child relation. This kind of relation is provided by the parent_id field in the data import file. This field represents the reference to the local_id of the parent item.

Note: The parent item and the child item shall be in the same item class. If an item is part of a collection, it can have a parent contained in the same collection.

 

Status

Each item has a status as defined in ISO 19135-1 draft:

  • Valid: the item has been accepted, is recommended for use, and has not been superseded or retired (value to be used in the CSV import file: valid).
  • Invalid: a decision has been made that a previously valid register item contains a substantial error and is invalid, and will normally have been replaced by a corrected item (value to be used in the CSV import file: invalid).
  • Submitted: the item has been entered into the register, but the control body has not accepted the proposal to add it (value to be used in the CSV import file: submitted).
  • Superseded: the item has been superseded by another item and is no longer recommended for use (value to be used in the CSV import file: superseded).
  • Retired: A decision has been made that the item is no longer recommended for use. It has not been superseded by another item (value to be used in the CSV import file: retired).

 

Standard and Custom Attribute Fields

Each element has a standard list of attributes. Below there is a list of attributes for each object type represented in the system.

Registry

Id Identifier of the registry
Label Label of the registry
Content summary

Description of the purpose for which the registers and their items managed in the registry are made available to potential users.

Registry manager Person or organization responsible for the day-to-day management of the registry

Register

Id Identifier of the register
Label Label of the register
Content summary Description of the purpose for which items in the register are made available to potential users. It should also specify any limits to the scope of the register and identify the types of applications for which the items are intended.
Owner Organization that estabilishes a register
Register manager Organization to which management of a register has been delegated by the register owner
Control body Group of technical experts that makes decisions regarding the content of a register.
Submitter Organization authorized by a register owner to propose changes to the content of a register
Contact point Name or position of the person who serves as a point of contact for information about the register owner and the register
License The licence under which the register content is being made available

The Registry and Register attributes cannot be extended using custom attributes (see below).

The information related to the Registry and the Register can be configured in the system during the installation using the provided example .sql script (refer to the "Getting started" guide).

Item

Id Identifier of the item
Label Label of the item
Definition Definition of the item (precise statement of the nature, properties, scope or essential qualities of the item)
Description Description of the element (statement of the nature, properties, scope, or non-essential qualities of the item but are not specified by the definition)
Status Status of the item

Custom Attributes

The custom attributes are designed to add additional attributes out of the standard attributes available for an item. By using a custom attribute, any item can be extended to include any item-specific attribute.

The current standard list of attributes required by the input file format is described in Data actions and CSV formats

The system creates the items reading the data from the input file. Fore more information on the system flow, refer to section "System description".

 

Language representations

The Re3gistry software user interface and the data processed and produced by this tool has two different ways of managing multiple language representations.

  • The Re3gistry software user interface uses a localization file to translate the GUI. This file is not linked with the translation of the data processed by the tool. Currently in the software package, there is only the English and Italian translation file for the Re3gistry admin interface.
  • The data processed and produced by the Re3gistry software has in turn two ways of handling the multi lingual representations:
    • The data localization (included in the import data file);
    • The graphic user interface localization (included in the web service’s webapp configuration).

Using the examples contained in the package, you are able to load and export the example data in all the languages supported by the INSPIRE registry service.

 

System description

The Re3gistry software handles the entire data flow process for register items management, from data import and edit to the staticization of specific items in different customizable formats.

The system is composed by modules: there is a common module, implementing all the basic features, and several other modules implementing each specific functionality.

This package is bundled with the data management module (responsible for importing and editing data), the data staticization module (responsible for saving the data as static files in different formats) and the deployer module (responsible for deploying all the static files produced to the target production server).

The picture below (fig. 2) shows a schematic representation of the system.

Figure 2 - Schematic system description

 

The schema below gives a complete overview of the Re3gistry software and all the other components required in order to provide a RESTful web service (fig. 3).

Figure 3 - System description

The following paragraphs give an overview of the system. A description of the module and how to extend them or create a new module is provided at section Developer documentation.

 

Registry core

The registry core module contains all the basic object model and database operation required by the system.

 

Data module

The data module is responsible for all the data operation that can be performed on the registers.

The input for this module is the zip data file (described at section Data file structure), containing one CSV file for each of the operations, for each register.

The supported operations are taken from the ISO19135-1 and are listed below (detailed at section Data actions and CSV format):

  • Addition
  • Clarification
  • Supersession
  • Retirement
  • Invalidation

The description of the CSV file endocing for each of these actions is provided at section Data actions and CSV format.

The data module performs different check to ensure the data consistency in the register.

The data module procedure steps are listed below:

  • Format check: a check on the CSV files format (CSV format described at section Data actions and CSV format);
  • Data analysis: a semantic check trough the data, by verifying links between data and data consistency (described at section Data analyser)
  • Data store: save the data contained in the CSV files (CSV format described at section Data actions and CSV format).

An important concept is the “operating language”: this property identifies the language representation that shall be always available. You cannot load an item without this language representation.

For example, if the operating language is set to English, and a new item has to be added in the French language, the addition file shall also contain the item in the English language.

The operating language can be configured in the system following the "Getting started" guide.

 

Common user interface

Since version 1.0, the Re3gistry software has a simplified single page interface. This interface has a single input point that controls all the available functionalities.

To start the data procedure, the user needs only to upload the data file using the "Add data file" button and dialog. Only zip files can be uploaded.

By clicking the "Add data file" button, a dialog box is opened. The user has to select the data file from the file system. In addition a short description shall be added in order to provide context of the procedure. The optional “Ignore warning” flag could be selected.

The procedure’s description field is mandatory and it is useful to later identify the procedure in the list of the procedure completed.

The “Ignore warnings” checkbox forces the system to perform the data storage even if the analyzer finds warnings in the data files. If the analyzer finds some errors, the procedure will be locked even if the “force warnings” flag was set. The difference between errors and warnings is explained at section Data analyzer.

After providing all the required information, the procedure starts after clicking on the “Start procedure" button.

The user can always check the status of the procedure from the "procedure list" table in the user interface. This table contains the history of the procedures launched, together with the current running procedure and eventual queued procedure. Once the procedure starts, the systems performs all the data operations (import and export).

Note: Only one procedure can run per time. If the user add a new data file while another procedure is running, the newly added data file will be queued. The system will run the queued files once the current running procedure has ended.

The procedure may take a considerable amount of time, depending on the number of items to be processed.

Once the procedure has started, the browser can be closed: the system will continue to run. An email notification will be sent once the procedure ends; if it ends with problems, the list of problems will be attached to the email.

Once the procedure ends successfully, the “static files export” can be started again using the specific button in the table containing the list of procedures.

 

Procedure statuses

Checking data The system is checking the dafa file format and analyzing the data file consistency.
Storing data The data has been checked; the system is storing the data to the database
Writing files The data has been  stored to the database; the system is writing the static file to the file system
Completed The files has been written to the file system and they are ready for the deployment
Imported This status indicates that the data import has succesfully completed but the export to the static files has not been done (or the export went wrong). In this case the export can be started manually with the specific button in the UI.
Deployed The file has been deployed to the web server
Failed Somenthing went wrong during one of the data procedure step. In this case, a detailed error description is sent to the user's mail

 

Data file structure

The Re3gistry software reads the data to be imported from the data import file (zip file).

The zip file structure is described below:

  • The root of the ZIP file contains one folder for each of the item class (for the definition of item class, refer to section Information model); the system is going to perform an action on each of these folders. The name of the folder has to be exactly the same name of the item class, including the case (the reference to the register is taken through the item class, which is linked to the register in the information model – section Information model).
  • Each of these folders contains the CSV files related to the action to be performed on the specific item class. The file is named with the action’s name in lowercase.

An example ZIP structure:

Exmaple 1 - ZIP data file

import.zip   

     ApplicationSchema/addition.csv    

     ApplicationSchema/clarification.csv    

     Theme/supersession.csv 

     Theme/retirement.csv

     CodeList/invalidation.csv

 

The ZIP data files can contain only the files and folders needed to perform the related actions.

For example, the ZIP data file provided above (example 1) will perform:

  • addition(s) and clarification(s) for the ApplicationSchema item class;
  • supersession(s) and retirement(s) for the Theme item class;
  • invalidation for the CodeList item class.

Data actions and CSV formats

This section will describe the action that can be performed on the data. The system support 5 types of actions: addition, clarification, supersession, invalidation, retirement.

For each of the actions supported by the system, there is a specific CSV format for the data file (detailed below).

 

Addition

This action adds the items specified in the related register.

The CSV for this action is composed by two different types of fields: main fields and additional fields.

The main fields must be provided even if they have null values; if one or more of the main field values are not available, the specific field must be left blank (the csv separator without any character or space. Example: value1|||value2|value3|||value4||…).

There are some main fields that are required for each action. These fields are highlighted in table 1 and can be configured in the data module properties file.

The property to customize the required fields is: data.mantatoryfields.<action_name>=<field>.<field>. …

The example below shows an example of mandatory fields for the addition action.

Exmaple 2 - Mandatory field property

Data file header:

LocalId|ParentLocalId|CollectionLocalId|Language|Label|Definition|Description|Status|Comment|*Theme[t,f,f,t]|*UMLName[t,f,f,f]

 

Property in the properties file:

data.mantatoryfields.addition=0.3.3.7

 

List the index of the field as in the property above to set a common field mandatory.

The additional fields (called custom attributes) represent some extra fields that users can add in order to customize the data model. The properties of these fields are described in the table 1.

Table 1 - CSV fields for the addition data file

Type

Code

Description

Main fields

LocalId (mandatory)

The local identifier (id) is used to identify an item inside the register and to create the URI of the item. If an item has a local identifier such as “localId”, the URI will be composed as follow: “http://site.ext/register/localId”;

ParentLocalId

This is the reference to the parent item

CollectionLocalId

This is the reference to the collection parent. If this field is set then an item is part of a collection.

Language (mandatory)

The language of this item. If there is multiple language for each item, the row has to be duplicated, hanging the language related fields.

Label (mandatory)

This contains the label of the items

Definition

This contains the definition of the system

Description

This contains the description of the items

Status (mandatory)

This contains the status related to the current item. More details about the code to be used in this field can be found in Table 2.

Comment

A textual comment for the change log stored by the system for each action.

Additional fields

(custom attribute/ header descriptor)

The custom attribute headers define the properties of the additional fields.

 

Custom attributes must be added to the CSV file after the standard fields and have the following format:

*custom_attribute_name[required,multivalue,coded,foreignkey]

 

The value in the square parenthesis is a Boolean value, and can be “t” (for true) of “f” (for false): e.g. *extensibility[t,f,f,f].

The meaning for each of the properties set in the square parenthesis is described in the following rows.

Required

This indicates that the custom attributes is required. The whole data rows in the CSV must have this value in order to be imported.

Multivalue

This indicates that this custom attribute could have more than one value. The values are saparated by comma. E.g. ...|ab,cd,ef

Coded

If this property is set to true, the custom attribute takes its values from a list of values defined in a specific database table. More details about the information model can be found in Annex A (This feature is not implemented but is foreseen in the future).

Foreignkey

If this property is set to true, the value in this field is a localId of another item in the register. The name of the custom attribute has to be the name of the item class referenced.

Exmaple 3 - Addition CSV example

Import.zip -> ApplicationSchema/addition.csv

LocalId|ParentLocalId|CollectionLocalId|Language|Label|Definition|Description|Status|Comment|*Theme[t,f,f,t]|*UMLname[t,f,f,f]

sd|||en|Species Distribution|||valid||sd|SpeciesDistribution

sd|||fr|Répartition Des Espèces|||valid||sd|SpeciesDistribution

 

This example contains an addition of the item "sd" in the ApplicationSchema register. There is the mandatory header line and two rows (the "sd" item in two languages - one row for english language an the other for frrench).

Note: in the example above the custom attribute (name: Theme) is defined as foreign key. In this case, the name of the custom attribute (in the descriptor line – the first line of the csv) shall be exactly the name of the itemclass related to the item specified as value. The value of the custom attribute shall be the LocalId of the referenced element. Only items that are not part of a collection (with the CollectionId field empty) can be pointed by a custom attribute.

 

Clarification

This action allows editing the items. Every time a clarification action is performed, the version of the edited item is increased.

This action data file shall be filled only with the fields that need to be edited (plus the LocalId and the language to identify the item). Only the filled fields will be updated; the field left blank in the action file, will not be updated, and remain as is in the register.

The clarification action cannot change the collection of an item. Nevertheless the clarification CSV file contains the CollectionLocalId field in order to unambiguously identify the item. In fact, in the same data file, different items that are part of a collection may have the same LocalId but different CollectionLocalId. In the clarification (but also in the supersession, retirement and invalidation) the item has to be identified in the data file by its LocalId and CollectionLocalId (if available).

The clarification’s CSV file is like the addition CSV file but without the status field. The CSV format is described in table 2 (for the detailed fields description, refer to table 1).

Table 2 - CSV fields for the clarification data file

Type

Code

Description

Main fields

LocalId (mandatory)

The local identifier (id) is used to identify the item to be updated

ParentLocalId

 

CollectionLocalId

 

Language (mandatory)

The local identifier (id) is used to identify the language representation of item to be updated

Label

 

Definition

 

Description

 

Status

 

Comment

 

Additional fields

(custom attribute/ header descriptor)

In the clarification data file, all the custom attribute related to the current item class shall be specified in the first row as the addition CSV.

Exmaple 4 - Clarification CSV example

Import.zip -> ApplicationSchema/clarification.csv

LocalId|ParentLocalId|CollectionLocalId|Language|Label|Definition|Description|Comment|*Theme[t,f,f,t]|*UMLname[t,f,f,f]

sd|||en|Species Distribution changed|||||changed custom attribute

sd|||fr|| Ajouter la définition en français ||||

 

This example contains a clarification CVS file for the ApplicationSchema item class (linked to the ApplicationSchema register). The file contains only the “sd”. Item, to be modified in the 2 different language:

  • English: the label and the “UMLname” custom attribute are edited;
  • French: the definition is added

 

Supersession

This action allows superseding an item. The supersession CSV file format is quite different from the previous two, because it only requires the reference to the item to be superseded and to the successor item(s).

The successor item(s) shall be available in the database or shall be present in the addition csv of same item class data file containing the supersession csv.

Table 3 - CSV fields for the supersession data file

Code

Description

SupersededLocalId (mandatory)

The local identifier (id) is used to identify the item to be superseded

SupersededCollectionLocalId

The optional collection local identifier (id) is used to identify the item to be superseded (to be provided if the item is part of a collection)

NewLocalId (mandatory)

The local identifier (id) is used to identify the successor item(s). The identifier can be a single identifier or multiple identifier separated by comma (e.g. ac,mf).

In case of multiple successors elements that are part of a collection, all of the specified successor shall belong to the same CollectionId.

If the successor belong from different Collection, one row for each collection shall be specified in the supersede file.

NewCollectionLocalId

The optional collection local identifier (id) is used to identify the successor item (to be provided if the item is part of a collection).

Comment

A textual comment for the change log stored by the system for each action.

Exmaple 5 - Supersession CSV example

Import.zip -> ApplicationSchema/supersession.csv

SupersededLocalId|SupersededCollectionLocalId|NewLocalId|NewCollectionLocalId|Comment

sd||ad||this is a comment

mf||ad,ac||this is a comment

This example contains a supersession CVS file for the ApplicationSchema item class (linked to the ApplicationSchema register). The file contains two supersessions:

  • the "sd" item, with successor item "ad".
  • the "mf" item, with successor items "ad","ac".

 

Invalidation

This action allows invalidating an item. The invalidation CSV file format is the same such as the supersession CSV file, in addition there is the recursive flag (explained in the  table 4), because it only requires the reference to the item to be superseded and to the successor item(s).

The successor item(s) shall be available in the database or shall be present in the addition csv of same item class data file containing the supersession csv.

Table 4 - CSV fields for the invalidation data file

Code

Description

LocalId (mandatory)

The local identifier (id) is used to identify the item to be invalidated

CollectionLocalId

The optional collection local identifier (id) is used to identify the item to be invalidated (to be provided if the item is part of a collection)

SuccessorLocalId (mandatory)

The local identifier (id) is used to identify the successor item(s). The identifier can be a single identifier or multiple identifier separated by comma (e.g. ac,mf).

In case of multiple successors elements that are part of a collection, all of the specified successor shall belong to the same CollectionId.

If the successor belong from different Collection, one row for each collection shall be specified in the supersede file.

SuccessorCollectionLocalId

The optional collection local identifier (id) is used to identify the successor item (to be provided if the item is part of a collection)

Recursive

This field tell the system to recursively invalidate any children items or linked items to the invalidated item. To set this flag put the word “true” in the field, otherwise leave it blank.

Comment

A textual comment for the change log stored by the system for each action.

Exmaple 6 - Supersession CSV example

Import.zip -> ApplicationSchema/invalidation.csv

LocalId|CollectionLocalId|SuccessorLocalId|SuccessorCollectionLocalId|Recursive|Comment

sd||ad|||this is a comment

so||ac,mf||true|this is a comment

 

This example contains an invalidation CVS file for the ApplicationSchema item class (linked to the ApplicationSchema register). The file contains two invalidations:

  • the “sd” item,  with the successor item "ad". This is not recursive and contains also a comment.
  • the “so” item,  with the successor items "ac" and "mf". This is recursive and contains a comment.

 

Retirement

This action allows retiring an item. The supersession CSV file format is the simpler one. It only requires the reference to the item to be retired plus a recursive flag (explained at table 5).

Table 5 - CSV fields for the retirement data file

Code

Description

LocalId (mandatory)

The local identifier (id) is used to identify the item to be retired

CollectionLocalId

The optional collection local identifier (id) is used to identify the item to be retired (to be provided if the item is part of a collection)

Recursive

This field tell the system to recursively retire any children items or linked items to the retired item. To set this flag put the word “true” in the field, otherwise leave it blank.

Comment

A textual comment for the change log stored by the system for each action.

Exmaple 7 - Retirement CSV example

Import.zip -> ApplicationSchema/retirement.csv

LocalId|CollectionLocalId|Recursive|Comment

sd|||this is a retirement

so||true|this is a retirement

 

This example contains a retirement CVS file for the ApplicationSchema item class (linked to the ApplicationSchema register). The file contains two item, to be retired:

  • the “sd” item.  This is not recursive and contains also a comment.
  • the “so” item.  This is recursive and contains a comment.

 

 

Data analyser

The data analyser component perform some checks in order to understand if the data file contains consistent data and also to understand if the database keeps its consistency after current data file is processed.

There are two type of message raised by the analyser:

  • Errors: these are locking problems; the data file shall be corrected before the system can continue its work.
  • Warnings: these are non-locking problems; the user is notified about the problem but the import can continue by setting the “ignore warning” flag available in the web interface.

Below there is a list of the checks performed by the analyser.

Table 6 – Analyzer check and report message type

Legend: errors - warnings

 

Actions

Situations

Addition

Clarification

Supersession

Invalidation

Retirement

Item already in the database

                 

-

-

-

-

Item not available in the database

-

                 

                 

                 

                 

Custom attribute (with foreign key flag true) pointing to an item not available in the database nor in the current addition file

                 

                 

-

-

-

Custom attribute (with foreign key flag true) pointing to an item not valid

                 

                 

-

-

-

Item pointing to a parent not available in the database nor in the current addition file

                 

                 

-

-

-

Item pointing to a parent not valid

                 

                 

-

-

-

Item pointing to a collection not available in the database nor in the current addition file

                 

-

-

-

-

Item pointing to a collection not valid

                 

-

-

-

-

Item pointing to a successor not available in the database nor in the current addition file

-

-

                 

                 

-

Item pointing to a successor not valid

-

-

                 

                 

-

The item’s operating language is not available

                 

-

-

-

-

The item’s language is not in the list of supported language

                 

-

-

-

-

The item has collection

-

-

                 

               

                 

The item has child

-

-

                 

                 

                 

The item has links (pointed by a custom attribute as foreign key)

-

-

                 

                

                 

If the system finds some errors or warnings, the procedure is stopped and an email notification is sent. The email contains an attachment with the detailed list of the errors.

In case the procedure produces both errors and warnings, the system will lock even if th the “ignore warning” flag is set. In this case the notification email will contain a mixed error and warning rows.

The user is notified by email also when the procedure ends correctly.

 

Data store

The data store component save the data to the database and performs all the action described in each csv contained in the ZIP data file. The data store component starts after the data check performed by the analyzer.

If something goes wrong in the store process, the user will recieve an email with the detailed list of errors, and the import is rollbacked.

 

Staticization

The “Staticization” component is responsible for saving  to the file system the data stored in the database by the data procedure.

 

Data staticization process

The data staticization procedure saves the items stored in the database to the file system. The system uses some XSLT trasformations files (described in the following paragraphs) to provide the different configured formats.

The staticizer creates firstly a master xml file, containing a structured export of the items stored in the database.

Then, using the custom XSLT files, it creates the different file formats (also called "custom" formats). The “custom” folder will contain all the files produced using the configured XSLT files.

 

XSLT

The transformation system allows the user to define different custom formats. The XSLT files are responsible for the creation of those custom file formats.

The XSLT files translate the information contained in the master XML file. There are 3 types of master XML files:

 

The XSLT files shall be contained in a folder specified in the system properties file (Re3gistryStaticizer.properties - properties files describet in the Getting started guide). The property is specified below:

Example 8 - XSL path properties
staticizer.formats.path= /your-path/xsl

 

Each format shall have a folder named with the exact name of the format itself.

E.g. the XSLTs for the .html format are contained in a folder called "html".

An example folder list related to the XSLT folder linked to each format used in the INSPIRE registry is provided below:

Example 9 - XSL folder structure

…/xsl/atom
…/xsl/json
…/xsl/rdf
…/xsl/solr
…/xsl/xml
…/xsl/gui-languages

 

 

Each of the folders used for the XSLT transformation shall contain one XSLT file for each registry, one for each register and one for each category of item:

Exmaple 10 - Xslt transformation for xml

<itemclass_uriname>.<format>.xsl - items

<register_uriname>.<format>.xsl - register

<registry_uriname>.<format>.xsl - registry

 

Figure 4 - XSLT trasformations files for the custom XML format (contained in the xml folder)

 

Each format shall also be configured in the format list property, in the Re3gistryStaticizer.properties file.

To configure each transformation, the relative entry has to be listed in the xsl.formats.list property. Example:

Exmaple 11 - Staticizer configurations

xsl.formats.list=xml,json,html,atom,rdf

 

This property tells the system which transformations are available.

 

The name of the folders containing the output files can be customized in the Re3gistryStaticizer.properties file:

Exmaple 12 - Staticizer folder configurations

staticizer.standard.folder=standard

staticizer.custom.folder=custom

staticizer.solr.folder=solr

staticizer.solrcustom.folder=solrcustom

 

Static element localization

To handle the localization of some static elements (such as some gui part of the the HTML format) there is a language mapping file. The “gui-languages” folder contains <language_code>.xml files (one for each language supported by the system) containing the keys used by the XSLT files for any static string not available in the database.

Example - the fr.xml gui translation file could be:

Exmaple 13 - Gui-languages folder, French file structure

<guilanguage languagecode="fr">

<item key="feedback">Retour d'utilisation</item>

<item key="powered-by">Construit avec</item>

<item key="about">A propos de</item>

<item key="contact">Nous contacter</item>

. . . .

</guilanguage>

 

Example 14 - Usage example

Place this piece of code to retrieve the translated word in the file.

<xsl:value-of select="$languagefile/guilanguage/item[@key='feedback']"/>

The $languagefile variable is the path of the document containing the translations and it is defined at the beginning of the xsl file. An example is provided below:

<xsl:variable name="language" select="item/language/isocode"/>
<xsl:variable name="languagefile" select="document(concat('../gui-languages/',$language,'.xml'))" />

 

Additional information

The staticizer is responsible aslo for the creation of some additional files to handle the content-negotiation (Var files) and the Apache Solr indexing.

The Var Generator generates the .var index configuration files needed to set-up the Apache content-negotiation feature. This allows the user to use the content-negotiation approach explained at section Serving the registry content.

The Solr export will produce the files to be imported by the Apache SOLR application (one file for each item, containing all the languages). The Solr XSLT transformation produces files compliant with the Apache SOLR system.

 

Run a staticization manually

When you start a new data procedure, uploading a data file, it will import and expor the data automatically. Once the first procedure has been completed, if you want to start the export of the static file manually you can use the "Run data export functionality" available for each proceure with the "completed" or "imported" status.

 

Run a complete export of the database

To start a complete export of all the database, click the "Run full export" button. THis will start a staticization process for all of the data contained in the database.

 

Deployer

The deployer module is responsible for deploying all the static files produced by the staticization system to the target production server. This is needed if the production server is in a different machine (or the files in the same machine need to be moved to another place in the same system).

The module automatically takes all the static file produced and move them to the configured target place.

The system uses a configurable script to launch the deployment process. This script can be found in the main application properties folder under scripts/Re3gistryDeployer.

The system automatically recognizes the operative system (Linux or Windows) and launch the relative file (linux-deploy.sh or windows-deploy.bat). These shell scripts can be configured and customized to perform the needed operations in order to move the produced files to another directory as well as to another server.

To configure the Deployer module, the properties to be customized are contained in the RegistryDeployer.properties file. The properties are described below.

deploy.script.folder: this property represents the folder where the .sh of .bat file are stored.

deploy.rss.file: this property is the location of the base RSS file. It is the master file that contains all the RSS news. If the "RSS update" option has been selected (through the specific flag in the interface), the RSS update system takes this file and updates it with the new information. Then the file is copied to the target path

deploy.rss.targetfolder: the folder in which the RSS file is stored after the update (usually is the same folder that contains all the files produced by the staticizer)

deploy.rss.baseuri: this is the base uri of the RSS file, stored in the RSS file as the channel's "link" element (example: for the inspire registry, it is http://inspire.ec.europa.eu/registry/rss/).

 

System installation and first run

Refer to the "Get started" guide

 

Serving the registry content

The Re3gistry software, produces a set of files organised to set up a web service providing access to the registers. An important characteristic of the service is the possibility to provide the same information in multiple formats and multiple languages. The service is implemented using the content-negotiation approach. The server can provide the correct file language/format based on the http header sent in the http request.

If a user prefers to use the classic way to accessing a specific file (request a specific format/language using a direct URL), the system supports this approach too.

The file to be used in order to set up a web service can be found in the staticizer’s output folder.

Detailed information about the web service and its configuration are provided in the following paragraph.

 

Web Service

The files produced by the Re3gistry software (staticizer module) can be used to provide the web service in two ways:

  • a RESTful web service which adopts a content-negotiation approach for serving the resource and
  • a web service, which uses the resource name in order to access the specific resources.

 

RESTful web service with content-negotiation

This web service is implemented using the Apache HTTPD web server and its content-negotiation capabilities.

The resource is accessed using the standard RESTful notation. Below there are some examples:

Table 7 - RESTful URL example

URL Use
http://base_uri/register_uriname
http://base_uri/register_uriname/item_uriname
http://base_uri/register_uriname/collection_uriname/item_uriname
Used to access a register, an item or an item collection
http://inspire.ec.europa.eu/themes Used to access the INSPIRE theme’s register
http://inspire.ec.europa.eu/applicationschema/ad Used to access a specific application schema
http://inspire.ec.europa.eu/codelist/ActiveWellTypeValue/decontamination/ Used to access a specific value in the code list

To ask for a specific file format or language, the HTTP request should have the http header set. If no header is set, the web service returns (by default) the xml format in English.

There are different ways of setting the HTTP header in the requests. If the request to a resource is done via browser, the HTTP header can be set using a specific plugin for that browser. Search for “HTTP header” in the browser’s component store. If the request is done programmatically, refer to the guide of the programming language used.

Example 14 - Example of Content Negotiation Parameters

Accept             application/xml 

Accept-Language    en


 
Accept             application/atom

Accept-Language    fr

In order to enable the content-negotiation capabilities, the Apache HTTPD server has to be configured. Each content folder needs a configuration file that addresses the HTTPD server to serve the right file.

This file is a .var file (cn .var). The staticizer module has an automatic procedure to produce this file after the execution of the staticization.

Example 15 - .var file example

URI: ICDValue.en.atom

Content-language: en, en-GB, en-US, en-EN

Content-type: application/atom+xml

 

URI: ICDValue.en.html

Content-language: en,en-GB,en-US,en-AU,en-NZ; q=1.0

Content-type: text/html

 

URI: ICDValue.en.json

Content-language: en, en-GB, en-US, en-EN

Content-type: application/json

 

URI: ICDValue.en.xml

Content-language: en, en-GB, en-US, en-EN

Content-type: application/xml

For detailed information on how to configure Apache HTTPD and content-negotiation, refer to the Apache HTTPD guide.

 

Standard web service

To access the resources without using the content negotiation approach, the standard url-based request can be used.

Example 16 - Direct URL example

http://inspire.ec.europa.eu/codelist/codelist.en.html

http://inspire.ec.europa.eu/themes/themes.de.atom

http://inspire.ec.europa.eu/Applicationschema/ad.fr.json

http://inspire.ec.europa.eu/codelist/AgeBy5YearsValue/0-5/0-5.en.xml

http://inspire.ec.europa.eu/codelist/Article17CountingUnitValue/reference/Article17CountingUnitValue.fr.rdf

 

Configuring the webapp component to set up the web service

In order to set up the web application for the web service follow the steps available in the "Getting started" guide.

 

Customization guide (create your own registry/registers)

In order to set up a custom register follow the steps available in the "Service customization" guide.

 

Developer documentation

The following information describes the technical specification of the system.

Technology

The system requires the Java 1.7 or Java 1.8 technology. The libraries used in the system are described in the Project Object Model (POM) file. This project is built using Apache Maven technology.

The registry service web application requires php >= 5.4.

 

Web Server

There are two different web servers: one used to serve the RESTful web service and another is the Servlet container for the Re3gistry Java webapp. The two servers are listed below:

 

Database

The database layer is handled by EclipseLink library. All the databases supported by EclipseLink can be used for the system.

Note: only the following database type/version, has been tested for the current version of the system: PostgreSQL 9.2

 

System structure

The Re3gistry software is organized in modules: this concept allow a simple customization and extension of the system.

The main components of the system are the Re3gistryCommon module and the Re3gistry webapp.

The paragraphs below explain the main structure of the system and the modules. By understanding the system’s structure the modules can easily edited and extended.

 

Module concept

The module is a Java library plus some optional web pages that adds functionality to the core system. Each module is composed by a core part (java library). There may also be a presentation part (web pages).

  • The module’s core part (java library) contains all the logic related to the functionality provided by the module itself. Each module needs to include the Re3gistryCore module in order to access all the common beans and functions.
  • The module’s presentation part is optional (you can access the module's core functionalities by customizing the standard interface provided by the Re3gistry) and is contained in the module’s folder of the Re3gistry webapp. This folder contains the user interface to interact with the function provided by the module, and the specific module’s configuration file.

The Re3gistry webapp contains also the main configuration properties files and all the localization properties files.

 

Re3gistryCommon module

The Re3gistryCommon module is the base of all the software. It contains the object definition that represents each entity in the system and the manager to work with them (read/write). This core module has no a related presentation part in the Re3gistry webapp because its function is to provide the object structure and the main functionalities to all the other modules.

The Re3gistryCommon library is composed by different package described below:

  • constants: contains a class with all the constant used in this library;
  • managers: contains all the method to access the data for each bean defined in the model package;
  • model: contains all the bean related to the information model;
  • utils: contains several general utility classes, such as StringUtils or Logger class.

 

Re3gistry software interface

The R3gistry software interface contains the web interface to manage and use the functionalities provided by each module. In this component all the configuration files are stored, both related to the core module and to each of the additional module.

Below there is a description of the components contained in the Re3gistry webapp.

Web Pages folder: contains all the files related to the web pages (jsp, css, js, resources like images etc.). The “modules” folder, inside the “Web Pages” contains all the module specific web pages and configuration files.

Source folder: contains the java class related to the Re3gistry webapp (constants, module manager functionalities, servlets, utility, etc.).

Resources folder: contains all the configurations and localization file. Below there is a description for each file:

META-INF/persistence.xml: in this file all the configurations related to the database are specified.

configurations/Application.properties: this file contains all the main Re3gistry configurations (common to all the modules)

configurations/modules: this folder contains all the properties related to each module. The file name shall be exactly as the name of the module’s folder

configurations/logcfg.xml: the configuration related to the logging system

localization/Application/localizationBundle_xx.properties: the folder localization contains all the properties files related to the localization of the system. There is the subfolder “Application” that contains the core system localizations. Then, each module has its own localization file contained in a folder called exactly as the Library part of the module.

 

The source code

The following steps shows how to install and run the Re3gistry using the NetBeans IDE. We choose NetBeans for this documentation because it is the official open source IDE provided by Java.

 

Load projects

The first step is to load the projects contained in the “source” folder of the package (/Project_package_1.2/source) using the NetBeans IDE.

Figure 9 - Load projects with NetBeans IDE

Configuration files

For convenience, all the configurations are placed under the “build profile” in the POM files of the Re3gistry web project. These Project Object Model (POM) files can be found under the project’s root folder.

Edit these configuration settings using the local settings:

  1. The path for the logs file;
  2. The information regarding the database;
  3. The path for the temporary import folder/ the custom export data folder (if it is left blank, a standard folder, inside the webapp folder will be taken).

To customize the set up for all the feature of each module, check the following  properties file:

  • Re3gistry/src/main/resources/configurations/modules/Application.properties:
    •  this file contains all the main configurations for the system. To run the system the properties to be updated are “application.language.available” which represents the available language on the interface and the related language label, “application.contact”, “mail.sender”, “mail.recipient” which are the e-mail address of the contact, sender and respectively recipient and “mail.smtp.host” which is the server host smpt email;
  • Re3gistry/src/main/resources/configurations/modules/RegistryData.properties:

- “data.operatinglanguage”: this property represents the main language of the system;

- data.supportedlanguage: this property represents the list of the language supported by the data management system.

  • Re3gistry/src/main/resources/configurations/modules/RegistryStaticizer/RegistryStaticizer.properties:
    • “xml.formats.list=xml,json,html,atom”: the formats to be used by the xslt transformations (separated by comma)
    • “staticizer.SOLR.format=solr”: the SOLR name.

Exmaple 17 - Example POM file

<pofiles>       

       <profile>

            <id>env-dev1</id>

            <activation>

                <property>

                    <name>env</name>

                    <value>dev1</value>

                </property>

            </activation>

 

            <properties>

              <!-- Loggers configurations -->

<Default.log.file.dir>C:/re3gistry-data/logs/Complete.log</Default.log.file.dir>

<Re3gistry.log.file.dir>C:/re3gistry-data/logs/Re3gistry.log</Re3gistry.log.file.dir>

<Re3gistryData.log.file.dir>C:/re3gistry-data/logs/Re3gistryData.log</Re3gistryData.log.file.dir>

<Re3gistryStaticizer.log.file.dir>C:/re3gistry-data/logs/Re3gistryStaticizer.log</Re3gistryStaticizer.log.file.dir>

               

             <!-- Database configurations -->

             <persistence.jdbc.url>jdbc:postgresql://db_ip:5432/inspire_registry </persistence.jdbc.url>

                <persistence.jdbc.driver>org.postgresql.Driver</persistence.jdbc.driver>

             <persistence.jdbc.username>db_username</persistence.jdbc.username>

             <persistence.jdbc.password>db_password</persistence.jdbc.password>

               

             <!-- Specific module configurations -->

                 

             <!-- RegistryData -->

<RegistryData.import.dir>C:/re3gistry-data/temp</RegistryData.import.dir>

             <!-- / -->

               

             <!-- RegistryStaticizer -->

<!-- The root folder where to save the files produced by the Staticizer. ->

<RegistryStaticizer.export.dir>C:/re3gistry-data/staticizer</RegistryStaticizer.export.dir>

<!-- The path from where to read the xslt transformation and the translations for the GUI interface -->

<RegistryStaticizer.xsl.dir>C:/re3gistry-data/xsl</RegistryStaticizer.xsl.dir>

                                                       

            </properties>

        </profile>

</profiles>

Prior to starting the build process, ensure that the build profile (specified in the POM) for each the Re3gistry web project is selected. To do check this, in NetBeans go to “Set Configuration” under the project and choose the right profile (right click on the project -> “Set Configuration”).

 

Choose the authentication method

In order to choose the desired authentication method, two configuration files have to be updated. Below you can find a reference for both files in each case.

source/Re3gistry/src/main/resources/Application.properties

source/Re3gistry/src/main/webapp/WEB-INF/web.xml

The Application.properties file contains the property that allows the switch between ECAS or SHIRO authentication method. The default configuration is Apache SHIRO as authentication method.

# Login type: SHIRO | ECAS

application.LoginType=SHIRO

In addition, the web.xml file has to be updated based on the authentication method selected.

For example, the default configuration is Apache SHIRO: the SHIRO related lines are uncommented and the ECAS lines are commented:

<!--SHIRO authentication configs-->

    <listener>

        <listener-class>org.apache.shiro.web.env.EnvironmentLoaderListener</listener-class>

    </listener>



    <filter>

        <filter-name>ShiroFilter</filter-name>

        <filter-class>org.apache.shiro.web.servlet.ShiroFilter</filter-class>

    </filter>



    <filter-mapping>

        <filter-name>ShiroFilter</filter-name>

        <url-pattern>/*</url-pattern>

        <dispatcher>REQUEST</dispatcher>

        <dispatcher>FORWARD</dispatcher>

        <dispatcher>INCLUDE</dispatcher>

        <dispatcher>ERROR</dispatcher>

    </filter-mapping>



<!--END SHIRO authentication configs-->

    

<!--ECAS authentication configs-->

    <!--

    <login-config>

        <auth-method>ECAS</auth-method>

        <realm-name>re3gistry Realm</realm-name>

    </login-config>

    

    <security-constraint>

        <web-resource-collection>

            <web-resource-name>not protected content</web-resource-name>

            <url-pattern>/res/*</url-pattern>

            <url-pattern>/ChangeLocale</url-pattern>

            <url-pattern>/login</url-pattern>

            <url-pattern>/login.jsp</url-pattern>

        </web-resource-collection>

    </security-constraint>

    <security-constraint>

        <web-resource-collection>

            <web-resource-name>inspire-regadmin</web-resource-name>

            <description>Requires users to be authenticated but does not require them to be authorized</description>

            <url-pattern>/*</url-pattern>

        </web-resource-collection>

        <auth-constraint>

            <role-name>*</role-name>

        </auth-constraint>

        <user-data-constraint>

            <description>Encryption is not required for the application in general.</description>

            <transport-guarantee>NONE</transport-guarantee>

        </user-data-constraint>

    </security-constraint>

    -->

<!--END ECAS authentication configs-->
 

If the chosen authentication method is ECAS, comment the SHIRO configuration lines and uncomment the ECAS ones.

To use the ECAS authentication method, follow the ECAS installation guide at annex ANNEX 2.

 

Database creation and initialization

The database initialization procedure creates the structure of the database and populate the registry contents. Some examples of database initialization script are provided in the Re3gistry software package.

Execute the database initialisation using the example SQL scripts available in the project’s package “example//database” folder.

The database script could be executed either from the command line or using a Graphic User Interface (GUI) such as pgAdmin.

The first step is to create a database. After the database has been created,the initialization script can be executed.

Open the create-tables.sql into an SQL editor and run the queries.

Do the same for the database-initialization.sql and database-localization.sql. It is important to run the create-tables.sql before the any other scripts. The database-initialization.sql and database-localization.sql files contain some sample data.

If the cleanup of the database is needed, in the example packages, there is also a drop-tables.sql script.

Note: for each new register to be added, the register table, the interclass table and the localisation table should all be filled in; for more information related to the creation of new register, please refer to the Customization guide.

 

Build Projects

To get the system running, build each project and start the web application (Re3gistry).

To build the project, right click on the project name and select “build” or “clean and build”.

 

Creating new modules

To start creating a new module, it is important to understand the module’s structure by reading the chapter 5 and taking a deep look at one of the modules included in the package (for example the Data module or the Staticizer Module).

After understanding the structure, the development of a new module can be started from an IDE like NetBeans. The following guide is provided using the NetBeans IDE as example.

Step 1

Open the main project contained in the project package.

Step 2

Create a new project: right click on the project browser and click on “new project”.

Figure 10 - Creating new project from the project browser

Choose “Maven” -> “Java Application” in the opened window, then click the “next” button.

Figure 11 - Project type selection

In the following window, give a name to the new module; in this example the “NewModule” name is used.

Figure 12 - Module name

Step 3

Go to the newly created project and edit the POM file, to insert the dependency to the RegistryCommon module as shown at example 16 .

Exmaple 17 - POM edit example

<dependency>

           <groupId>eu.europa.ec.re3gistrycommon</groupId>

        <artifactId>Re3gistryCommon</artifactId>

        <version>0.4</version>

</dependency>

Step 4

The library component of the module is now ready. To start the development, create the required package and classes in the project’s source folder.

It is important to create the Class “Constants.java” under package “eu.europa.ec.newmodule.constant”. This is a common used Class containing all the constants related to this module.

This class shall contain at least the class name. An example is provided below.

Exmaple 18 - Constants.java example

package eu.europa.ec.newmodule.constants;

 

public final class Constants {

 

    /* ###################################### */

    /* ########## Common constants ########## */

    /**

     * The name of this module

     */

    public static final String MODULE_NAME = "NewModule";

   

}

Step 5

If the new module requires a dedicated interface, the user shall create it using the following instructions. Otherwise you can jump to Step 6.

Open the Web Pages folder in the Registry webapp project. Search the modules folder, right click on it and select “New” - > “Folder”.

Figure 13 - Creation of the module's folder

Name the new folder exactly as the previously created Java Application (at step 2).

 

Step 6

Create the module’s property file, inside the “Other sources – configurations/modules” project folder (in the file system this folder is located under Re3gistry/ WEB-INF/classes/configurations/modules) with the same module name (“NewModule.properties”).

Figure 14 - Module's properties file

The required property keys for all the new modules are shown below:

  • module.active=true – if set to true, the module is active and is loaded in the system.
  • module.menuitem.visible=true – if this property is true, the menu entry related to this module is shown in the main system webpage. If no module has this property as visible, the menu bar is not visible.
  • module.menuitem.label=Data – This property rapresent the label of the menu item in the system main menu.
  • module.homewidget.enabled=true – This property enable/disable the system to show the module widget in the home page.
  • module.dateformat=dd-MM-yyyy HH:mm:SS – The module dat/time format.
  • module.menuitem.order=2 – The order in which this menu item is shown in the main menu. The higher values mean to be displayed later.

Step 7

Add the localization files in the “Other sources” -> “src/main/resources/localization” folder. To do this, right click on the “Other sources” -> “src/main/resources” folder and select “New” -> “Folder”.

Figure 15 - Localization folder for the new module

Name the new folder “localization/NewModule”.

Figure 16 - Localization properties folder

 

Then create a file for each language using this naming pattern: “LocalizationBundle_[language_code].properties”.

The minimum set of property to be available in the localization files are:

  • The module’s title: common.pagetitle=New Module
  • The module’s description: main.description=Descriptive text

Figure 17 - Module's localization properties file

Step 8

Add into the logger configurations the entry relative to this new module. Open the logcfg.xml file under “Other sources” –> configuration.

Add the entry related to the new module as defined below. Note that this example is using maven profile properties. In this case the property key related to this logger file has also to be added to the pom file.

Exmaple 19 – Logger configurations

<!-- NewModule -->

<appender name="appender.NewModule" class="org.apache.log4j.DailyRollingFileAppender">

  <param name="File" value="${NewModule.log.file.dir}"/>

  <param name="DatePattern" value="'.'yyyy-MM-dd"/>

  <layout class="org.apache.log4j.PatternLayout">

  <param name="ConversionPattern" value="%d - %-5p - %-10c [%C{1}.%M:%L] %m%n"/>

  </layout>

</appender>

 

<logger name="NewModule">

  <level value="info"/>

  <appender-ref ref="appender.NewModule"/>

</logger>

Step 9

The module structure is now complete.

Now the next step is to create the required web pages and to start the development of the functionalities for the module (both in the library and in the web part).

The web pages shall be placed in the module’s folder root, created at step 5.

There are 2 file required:

  • main.jsp: contain the main web page of the module, with all the functionalities.
  • widget.jsp: this page represents a sort of summary that can be placed in the home page of the system.

Notes

The main structure of the modules can be easily understood by taking a look at the files from the modules available in the project package.

There are some particular module related code snippets, used in the web pages that are explained below.

  • ${module.localization['property.name']} – It is used to retrieve a specified text in the language selected by the user. The keys passed as argument to this method has to be defined in the module specific localization file (created at step 7).
  • ${module.properties['property.name']} – It is used to retrieve a specific properties related to this module. The keys passed as argument are defined in the module’s related properties file (defined at step 6).