A              ITG-technology – Integration Technology

A.1          Basic Information

ITG-technology is a library serving for various aims in the project NAZOU. It provides communicating with Cocoon, creating user interfaces, tools' configuration of tools, logging localization services and other functionality. It also contains also the testing environment for tools.

A.1.1      Basic Terms

Environment

It means the web application environment in this document. The web application runs under Cocoon system.

Presentation

Presenting information to the user by displaying them in the form of a web page.

A.1.2      Method Description

Integration Technology gives support to tools developed in the project NAZOU. As a web application technology we used the Cocoon environment. We extended Cocoon so that we have allowed an easy way of presentation of developing tools.

ITG-technology serves for the following aims:

§  presentation generation of presentation – creation of presentation for user in the web application environment,

§  communication with environment – gettinggathering data information about the running environment of a web application,

§  cooperation of tools – usage of the Spring framework for tool cooperation,

§  generation generating of diagnostic messages – usage of log4j for generating and storing of diagnostic messages,

§  configuration – easy and common access to configuration files and shared directories,

§  language support – allowing a tool to adjust itself to language settings.

A.1.3      Scenarios of Use

ITG-technology is usable in the following ways:

§  as a Java library for logging support, common configuration, etc.,

§  as a Cocoon's 'plug-in' (output generator) allowing to create output to a user in the web application environment,

§  as a local (test) environment running tools under Cocoon, including the creation of output creation.

A.1.4      External Links and Publications

The project where the method was developed is described in:

Návrat, P. – Bieliková, M. – Rozinajová, V. (2005). Methods and Tools for Acquiring and Presenting Information and Knowledge in the Web. In: CompSysTech 2005, Rachev, B., Smrikarov, A. (Eds.), Varna, Bulgaria, June 2005. pp. IIIB.7.1–IIIB.7.6.

The brief overview of ITG-technology was published here:

Orfánus, D. – Pázman, R. (2006). Technology for Integration of Loosely Coupled Web-based Software Components. In: Tools for Acquisition, Organisation and Presenting of Information and Knowledge, Návrat, P., Bartoš, P., Bieliková, M., Hluchý, L., Vojtáš, P. (Eds.), Proceedings in Informatics and Information Technologies, Research Project Workshop, Bystrá dolina, Nízke Tatry, Slovakia, September 29–30, 2006, pp. 239–242.

The more information about Cocoon can be found on its home page: http://cocoon.apache.org/.

A.2          Integration Manual

A.2.1      Dependencies

ITG-technology uses the following libraries:

§  Cocoon,

§  Spring,

§Hibernate,

§  MySQL Connector/J (netreba aj toto odstranit?),

§  Log4j.

The exact list of JAR files used for building and running ITG-technology is included in the ITG-technology distribution (dist/info.txt).

A.2.2      Installation

Requirements for Installation

Hardware

There are no special requirements concerning the required hardware architecture for this tool.

Software

Fundamental requirement is to have an installed Java 2 Platform Standard Edition Runtime Environment (JRE), version at least version 5.0. The alternative is JDK (Java 2 Platform Standard Edition Development Kit) of a corresponding version. They are available at on java.sun.comhttp://java.sun.com. Note: in order to build Cocoon it is necessary to have JDK installed.

For the proper installation of ITG-technology we need to download additional frameworks and libraries:

§  Cocoon-2.1.9, available e.g. at apache.tuke.sk/cocoon.

§  Spring-1.2.x (do not use version 2.0 or abovenot 2.0, with this version ITG-technology will not work) – available at www.springframework.org.

§  Hibernate Core 3.1.3 – available at www.hibernate.org.

§  MySQL Connector/J 3.1 – available at www.mysql.com. Note: there is a newer production version, not tested with our technology yet.

§  Log4j – available at logging.apache.org.

Cocoon Installation

1.    Unpack the content of the downloaded installation package for Cocoon to a directory, where you want to install Cocoon.

2.    Follow the instructions in INSTALL.txt. In most cases it is enough to run the script build. Note: there It is necessary to have Java Sun’s JDK installed.

3.    Run Cocoon to see if the installation proceeds successfully (see section about running Cocoon to realize how to start Cocoon) and the start page of Cocoon can be seen at the address http://localhost:8888.

4.    If you want to install Cocoon in the environment of a servlet container such as Tomcat, copy the content of the directory build\webapp into a new subdirectory cocoon in the webapps directory of the servlet container. If you have installed Cocoon under Tomcat and Tomcat runs on port 8080 (default setting of Tomcat), you may test Cocoon on the address http://localhost:8080/cocoon/.

(All the following steps – also in other parts of the installation process – which refers to the directory build\webapp should be applied to the directory webapps\cocoon in the directory structure of the servlet container in the case of running Cocoon under the servlet container.)

5.    Copy the content of the subdirectory cocoon from the ITG-technology distribution into the directory build\webapp and let allow overwrite files web.xml and log4j.xconf to be overwritten. There are Spring and log4j configurations in these files.

6.    Edit the file build\webapp\WEB-INF\classes\Nazou-Bootstrap.properties and set the variable ROOT_FOLDER with to the a full path of theleading to the directory build/webapp/nazou/tools, e.g. C:/Program files/Cocoon-2.1.9/build/webapp/nazou/tools. Then set the variable ROOT_URL with to the value of the URL address of the same directory, e.g. http://localhost:8888/nazou/tools (http://localhost:8080/cocoon/nazou/tools for Cocoon under Tomcat). For more information see the section about configuration. Also set the variable PORTAL_FOLDER pointing to the root folder of the portal, e.g. C:/Program Files/Cocoon-2.1.9/build/webapp/samples/blocks/portal.

7.    Copy the content of the subdirectory dist from the ITG-technology distribution into the directory build\webapp\WEB-INF\lib. One file represents a library of the integration technology and the other one contains the demonstration tool.

8.    Copy the content of the directory portal from the ITG-technology distribution into the directory \build\webapp\samples\blocks\portal. Confirm overwrites the overwriting of files.

9.    Continue with the installation of MySQL JDBC Connector, Spring and Hibernate (Hibernate a MySQL Connector netreba odstranit?) and then configure the database (see the following sections). Trying to run the application without having these technologies installed and configured will result in a failure.If you try to run Cocoon now, it will not work, because it will miss these libraries.

MySQL JDBC Connector Installation

Download the newest version of MySQL JDBC Connector, unpack it and copy the JAR file into the directory build\webapp\WEB-INF\lib.

Spring Installation

Unpack the downloaded Spring installation package and copy all *.jar files from its subdirectory dist into the directory build\webapp\WEB-INF\lib. It should be 14 files.

Hibernate Installation

Unpack the downloaded Hibernate installation package and copy the following libraries from the subdirectory lib into the Cocoon directory build\webapp\WEB-INF\lib:

§  asm.jar,

§  asm-attrs.jar,

§  c3p0-0.9.0.jar,

§  cglib-2.1.3.jar,

§  dom4j-1.6.1.jar,

§  jaxen-1.1-beta-7.jar,

§  jdbc2_0-stdext.jar,

§  jta.jar.

Copy the library hibernate3.jar from the main directory into build\webapp\WEB-INF\lib.

Database Configuration

If you run Cocoon without JOP portal (installation of ITG-technology under JOP portal is described in this section) you will need a user information database for user identification purposes. The configuration of this database is a required step of ITG-technology installation as a local (test) environment.

Data about users are stored in database tables, so you need to create the database and the tables within the database. There are 2 alternatives how to do it:

§  use HypersonicSQL database, which is a part of Cocoon,

§  use MySQL server.

Configuration of the database consists of two steps, which are different for each type of database. In the first step the database is created and the tables are filled with an initial set of users:

§  a user with login user, password user and role user,

§  a user with login admin, password admin and role admin.

In the second step the data source is set for authentication purposes.

Configuring HypersonicSQL

This alternative is a good solution for the quick preparation of the test environment and is appropriate for the cases when the user information change rarely or users are not authenticated at all.

In order to configure user maintenance using HypersonicSQL, copy the content of the directory db\hsql from ITG-technology distribution into the Cocoon directory build\webapp\WEB-INF\ and confirm overwrites.

Configuring MySQL

This alternative is appropriate if there will be an intensive usage of users, or if some tool already uses MySQL database.

The prerequisite of this alternative is a properly installed MySQL server.

At first create a database on the MySQL server, for example nazou_main. Afterwards run script db\MySQL\nazou_main.sql, which creates needed tables and fills them with the user initial data.

Now you need to redirect the user data source from HypersonicSQL to MySQL. Change the name of the referenced bean in the file build\webapp\WEB-INF\classes\nazouBeans.xml. That means change the following part of the source text:

<bean id="IConsumerRegistration" class="nazou.om.cs.ConsumerStorage">
    <property name="sessionFactory">
           <ref bean="sessionFactoryHSQL"/>
    </property>
</bean>

into:

<bean id="IConsumerRegistration" class="nazou.om.cs.ConsumerStorage">
    <property name="sessionFactory">
           <ref bean="sessionFactoryMySQL"/>
    </property>
</bean>

The next step is to set the proper connection parameters in the bean dataSourceMySQL (do not confuse it with dataSourceHSQL) in the file build\webapp\WEB-INF\classes\databaseBeans.xml (change the emphasized parts):

<bean id="dataSourceMySQL" class="org.springframework.jdbc.datasource.DriverManagerDataSource">

    <property name="driverClassName">
           <value>org.gjt.mm.mysql.Driver</value>
    </property>

    <property name="url">
           <value>jdbc:mysql://localhost/nazou_main</value>
    </property>

    <property name="username">
           <value>CHANGE ME</value>
    </property>

    <property name="password">
           <value>CHANGE ME</value>
    </property>

</bean>

Running Cocoon

In order to run the Cocoon environment in the case ofas a standalone installation application (under using the included JETTY servlet container) you need to run the script named cocoon. Cocoon will implicitly use the port 8888. If you need to change the port, you must set the environment variable JETTY_PORT to the desired number. The non-portal application environment can be found at the address http://localhost:8888/nazou/. The portal application environment can be found at the address http://localhost:8888/samples/blocks/portal/.

In order to run the Cocoon environment in the case of an installation under other servlet container (e.g. Tomcat) you need to start the servlet container. Cocoon will run as one of its web applications. The non-portal application environment can be found at the address http://localhost:8080/cocoon/nazou/ (if the servlet container uses 8080 port). The portal application environment can be found at the address http://localhost:8080/cocoon/samples/blocks/portal/.

Installation under JOP

The previous sections have specified described the ITG-technology installation under using the default Cocoon environment. You can use ITG-technology also under Job Offer Portal (JOP) which is a portal environment created in the project NAZOU using Cocoon portal engine. For more information about JOP see its documentation.

The requirement of a successful installation of ITG-technology under JOP is a proper installation of JOP. In the following, we assume JOP is installed in the directory webapps/cocoon/portal of the directory structure of the web application.

The process of the installation is as follows (do not follow the installation instructions in the previous sections):

1.    Copy the libraries of ITG-technology (Nazou-ITG-*.jar) and Demo tool (Nazou-DemoTool.jar) into the directory webapps/cocoon/WEB-INF/lib. Libraries are located in the directory dist of the ITG-technology distribution. If these libraries are already in the WEB-INF/lib directory, delete the older versions and replace them with the new versions.

2.    Copy the content of the directory cocoon/nazou from ITG-technology distribution to a new directory webapps/cocoon/nazou.

3.    Copy Spring libraries into the directory webapps/cocoon/WEB-INF/lib. See the section about spring installation.

4.    Copy the content of the directory cocoon/WEB-INF from ITG-technology distribution to the directory webapps/cocoon/WEB-INF. There should be no need to overwrite any files.

5.    Set the parameters in the file webapps/cocoon/WEB-INF/classes/Nazou-Bootstrap.properties. This can be done similarly as for Cocoon installation.

6.    Add any tools (e.g. Demo tool) into JOP environment using the description in the section about adding a tool under JOP.

7.    After the restart of the web application, JOP (together with any tool you have added) can be typically found at the address http://localhost:8080/cocoon/portal.

8.    Besides the JOP environment, the non-portal environment runs also, typically at the address http://localhost:8080/cocoon/nazou. For the addition of a toolWhen adding additional tools into this environment proceed as in case of addition adding of a tool into the non-portal environment.

A.2.3      Configuration

Using the installation routine described in the previous section, a web application environment is prepared. In order to test or run any tools within this environment, the tools must be added into the environment. This section describes the various alternatives of tools’ addition together with some other configuration tasks.

Adding Tool into the Environment

If you want to add a tool into the web application environment, follow these steps:

1.    Create a new subdirectory in the directory build\webapp\nazou\tools. The name of the subdirectory should correspond with the tool’s name.

2.    Put the tool’s static page and any other files such as images into the new directory created in the previous step. If the tool uses files which contains confidential data (such as log-in data), create a new subdirectory and put the files in there.

3.    Put any tool’s *.class files into the directory build\webapp\Web-inf\classes or tool’s *.jar files into the directory build\webapp\Web-inf\lib.

4.    If the tool needs any other libraries, put them into the directory build\webapp\Web-inf\lib. Be careful about adding a library that is already there but in different version.

5.    If the tool is configured by configuration support of ITG-technology, create (or copy if already prepared) the tool’s properties file in the directory build\webapp\nazou\tools\config. Set the tool’s configuration parameters in this file, respectively set some of them in the file Nazou-Commons.properties.

6.    Add the tool’s presentation into the web application using one of the descriptions in the following subsections of this section.

The tool’s presentation can be found at the address of the web application, which depends on the installation alternative, see also the sections about running cocoon and installation under JOP.

Adding Tool into Non-Portal Application

The side menu of the non-portal application serves as a place where you can add a button which runs the tool (loads the first static page).

The side menu is generated from the XML file build\webapp\nazou\documents\menu.xml, where you should add information about the tool. The default content (after the installation) is the following:

<?xml version="1.0" ?>

<nm:menu xmlns:nm="http://www.fiit.stuba.sk/nazou/menu">
    <nm:tool name="Demo" type=""
           src="tools/demo/example.xml" desc="Demo"/>
<!--      
    <nm:tool name="MyTool" type=""
           src="tools/MyToolDir/MyToolMainPage.xml"
           desc="My Tool Description"/>
-->

</nm:menu>

The file menu.xml contains information about the Demo tool, which demonstrates the usage of ITG-technology. To add your tool use (uncomment) the prepared element and fill the emphasized attributes in the following way:

§  The attribute name is the name of the tool, which will be displayed on the buttonas the label of the button.

§  The attribute type remains empty.

§  The attribute src is the path to the static page of the tool.

§  Content of the attribute desc is the button’s tooltip (displayed when cursor stands lies on theabove the button).

Adding Tool into Portal Application

A tool can be added into the portal application in various ways. This subsection describes the addition of a tool into Cocoon portal as a standalone tabulator.

In order to run and displaydisplay and run a tool in the portal environment on in a form of a new tabulator, follow these steps:

1.    Open the file build\webapp\samples\blocks\portal\profiles\copletdata\portal.xml. Basic building blocks of the portal application (coplets) are defined in this file. At the end of the file (after the text <!-- NAZOU coplets -->) there is the definition of the coplet for Demo tool. Below it there There is the a definition for of another coplet undereneath (commented out).

2.    Uncomment the prepared definition of coplet.

3.    Substitute a new identifier of the coplet instead of text {TOOL-ID} (in the attribute id of the element coplet-data), e.g. nazou-mytool. This identifier must be unique in the scope of this file.

4.    Substitute Replace the path to the first static page of the tool relative to the directory build\webapp\nazou\tools instead of the text {TOOL DIRECTORY}/{TOOL STATIC FILE}, e. E.g. if the tool’s directory is build\webapp\nazou\tools\mytool and its static page is static.xml, then type mytool/static.xml.

5.    Open the file build\webapp\samples\blocks\portal\profiles\copletinstancedata\portal-user-anonymous.xml. There are instances of coplets specified in this file. One new coplet instance is sufficient for one tool.

6.    Uncomment the prepared coplet instance and replace the text {TOOL INSTANCE NAME} with a new identifier of the coplet instance. Identifier The identifier must be unique in scope of this file. Replace {TOOL-ID} with the identifier of the new coplet (see point 3).

7.    Open the file build\webapp\samples\blocks\portal\profiles\layout\portal-user-anonymous.xml. Set the placement of the new coplet instance on the web page in this file. Uncomment the prepared element named-item. Replace the text {TOOL INSTANCE NAME} with the identifier of the new coplet instance (from point 6) and replace the text {TOOL NAME} with a new name of the tab for the tool.

Adding Tool into JOP

The Pprocess of adding of a tool into the JOP environment as a new tabulator is very similar to adding a tool to the portalthe previous example. Use the same routine to add your tool into JOP with the following differences:

§  The new tabulator for the tool must be defined at a different place and with slightly different attributes in the file webapps/cocoon/portal/profiles/layout/portal-user-anonymous.xml. You can take an inspiration from the existing definitions of tabulators.

§  If the tabulator should be accessible also for a logged user, the files webapps/cocoon/portal/profiles/copletinstancedata/portal.xml (add a new instance of the coplet) and webapps/cocoon/portal/profiles/layout/portal.xml (add a new tab for the new instance) should be edited too in the same way as the files portal-user-anonymous.xml in the same directories.

Creation of New a new sSkin in the pPortal aApplication

There can be defined varVarious display styles – skins – can be defined in Cocoon which and can be easily switched. If you want to create a new skin for Cocoon, follow these steps:

1.    Create a new directory in the directory \build\webapp\samples\blocks\portal\skins. Copy the content of a directory of an existing skin (e.g. Basic or Common) into the new directory.

2.    Change the design of the new skin. The skin directory consists of four subdirectories: css, images, js, and styles. Directories css and images contain cascading styles style sheets and images. Directory js is usually empty. Put any needed javascript files needed into this directory. In the directory styles, there are XSL-files with predefined names are stored in the directory styles. Each file is responsible for the look of a particular part of a web page (e.g. colors, shape, font, used images, etc):

§  portal-page.xsl specifies contains the final HTML page definition,

§  tab.xsl specifies contains the definition of a tabulator visagelook,

§  window.xsl contains specifies the look of a coplet,

§  column.xsl specifies contains the visage look of a column,

§  row.xsl specifies contains the visage look of a row,

§  login-page.xsl specifies contains the look of an the opening (login) page.

3.    Add the following code in the file \build\webapp\WEB-INF\cocoon.xconf into the skins tab (modify the emphasized parts):

<skin base-path="{PATH TO THE SKIN DIRECTORY}" name="{SKIN NAME}">
    <thumbnail-path>{PICTURE REPRESENTING THE SKIN}</thumbnail-path>
</skin>

For example:

<skin base-path="context://samples/blocks/portal/skins/nazou" name="nazou">
    <thumbnail-path>images/nazou_bg.jpg</thumbnail-path>
</skin>

4.    Add the following element into the tag map:global-variables (and edit the emphasized text) in the file build\webapp\samples\blocks\portal\sitemap.xmap – if it is not already there:

<skin>{SKIN NAME}</skin>

A.2.4      Integration Guide

Presentation Generation

There are two ways, how tools can create presentation for a user – either by straight-forward usage of the Cocoon framework, or by generation generating of the presentationit by making use of thewith the support of ITG-technology. The later is described in this section.

ITG-technology implements a kind of Cocoon ‘plug-in’, a generator. Using this generator tools can simply present their output. Tools have to create a simple presentation layer, which will:

1.    accept signals from the environment,

2.    transform them to requests on tool's services,

3.    take results from the services,

4.    send them back to the environment.

The presentation layer consists of Java classes (presentation classes) which should be concentrated into a stand-alone component. ITG-technology (the generator) will call individual methods of these classes (presentation methods) on the basis of HTTP requests coming from web browsers and send the results back to the browsers as HTTP responses.

In the case of an HTTP request, ITG-technology finds retrievesout the classname and the name of the method, which should be called by parsing parameters and values, which are transported in the HTTP request. These parameters are generated by the tool during the previous call. For a detailed description of the signature of such method see the section about communication with the environment.

To allow an easy way of presentation generation, tool presentation methods generate inputs for a user in a modified XHTML format. Such methods’ output is transformed by the generator and by a so called Cocoon transformer into the final HTML web page. The transformer is a special XSL file, and is also a part of the ITG-technology. The transformer is used also for generating web pages from static pages. Static pages are XML files (for example MyTool.xml) that are not generated in the run-time (typically a tool’s start screen).

The modified XHTML format allows using of attributes, which are not defined in the original XHTML. There is allowed to use almost any tags, while avoiding (unless it is necessary) usage of style and class attributes. The namespace of the XML documents must be set to http://www.fiit.stuba.sk/nazouforms.

Differences between the modified XHTML format and the original XHTML format are described in the following subsections.

Main Tag

Element body must be the root element of the XML documents. Do not use elements html or header.

Element body has two new attributes in comparison with its definition in XHTML: title and subtitle. Attribute title contains the name of the tool. Subtitle contains the name of the screen, for example ‘Input’, ‘Search results’, etc.

The namespace is set in the element body using the attribute xmlns:

xmlns="http://www.fiit.stuba.sk/nazouforms"

Automatic Redirection

There is a possibility to automatically redirect static page to a dynamically generated page. This can be done by these steps:

§  Define a form element in the static page and set its attributes (callClass and callType particularly).

§  Assign the attribute id (for example with value myForm) to it.

§  Use the following code in a new script element:

document.getElementById('myForm').submit();

Table

In order to display a table in the web page, use the standard element table. It has the same meaning as table in the original XHTML. The only difference is in a new attribute type, which is not mandatory and which describes display mode of table. It has only one value: results. If you use this attribute with this value, the look of the table is changed (frames are made, color is changed and so on).

Form

In order to display a form, the standard XHTML element form is used. Difference to the original meaning is in new attributes callClass, callMethod, callType, and legend and in the original attribute action. Example:

<form callClass="myPackage.MyClass" callMethod="myMethod">
...
</form>

The attribute callClass contains the full presentation class name or bean defined in Spring.

The attribute callMethod contains the presentation method name, which generates the required output. Signature of the method is described in the part about communication with the environment.

The attribute callType is not mandatory and it distinguishes whether there is a Spring bean or a Java class in the attribute callClass. It has two values: classic and spring. If this attribute is not set, then the value classic is implicitly taken.

The attribute action is automatically generated by the Cocoon generator, if it is not already set. If it is set, Cocoon doesn't change it.

In the case of using the attribute legend, which has the same meaning as the original attribute, the content of the form is put inside a fieldset element with an element legend.

The attribute elementid has its original meaning.

Editbox

The element editBox is a shortcut of the element input with type ‘text’ and thus all other attributes of the element input can be used.

Submit

The element submit provides sending of the form. It has the same meaning as the input element with the type ‘submit’. Other attributes from element input can be used.

Link – Reference

The original element a for a reference (e.g. hyperlink) is extended with some new attributes, with which a presentation method can be called.

The attributes callClass, callMethod and callType have the same meaning as in the case of form.

The attribute href is optional. If it is not set, the Cocoon generator fills it itself. Change of this attribute is not recommended, use the element file instead.

You can also pass attributes to the presentation method. It is allowed by the (optional) attribute params. Its content is a list of expressions of type name=value separated by ‘&’, where name is the name of the parameter and value is the parameter’s value. If this attribute is used, its content is concatenated to the value of href attribute (preferably generated by the Cocoon generator). It is appropriate when it is demanded to call the presentation method and pass it parameters, which are already known in the time of generation of the page.

Reference to External File

For the case of referencing an external file (web resource or file shared by several tools) which must not be processed by Cocoon and should be displayed directly in the web browser, the element file is used. It works like the element a with the difference that it uses only one attribute – href. Put the path to file to be displayed into this attribute. Examples:

<file href="http://nazou.fiit.stuba.sk/">Project NAZOU</file>

<file href="http://localhost:8888/nazou/tools/demo/example.log">Demo tool log</file>

Helper Class

To simplify the generating of output web pages, the class NazouFormsHelper was created. It contains several static methods, which generate frequently repeated blocks of XHTML elements. For more information see the class’ Javadoc documentation.

Communication with Environment

There are two kinds of application environment where ITG-technology can be used – non-portal application and portal application (see section about installation). The presentation generation and the invocation of the presentation methods (communication with the application environment) is the same in both environments.

The Cocoon generator (special for ITG-technology) catches HTTP requests and call appropriate presentation methods. In order to allow appropriate communication of the presentation method with the application environment, the generator sends to the method some additional information, e.g. parameters sent in the HTTP request (including the parameters which were set in the calling page), paths in file system, information about ITG-technology itself, etc.

The presentation method obtains this information from the interface NazouContext. The generator sends an object implementing this interface to the presentation method.

Each presentation method must keep specified signature (parameters and return value types), so the generator can call all presentation methods in the same way.

There existed two signatures in older versions of ITG-technology, which are replaced by one new signature in newer versions. The new signature is more flexible and easier to extend in the future. For the reason of backward compatibility the old signatures are still usable, but deprecated.

New Signature

New signature looks like this:

public String myMethod(NazouContext ctx) {...}

The method’s return value is a String object, which should contain the page to be displayed in the form of modified XHTML, described in the section about presentation generation. The instance of the interface NazouContext is provided by the Cocoon generator.

The interface’s services are described in its Javadoc documentation.

Old Signatures

There are two forms of the old signatures. They both send a map of parameters to the presentation method. These are the parameters which were set in the calling page, together with special parameters about the application environment.

The first form of an old signature is as follows:

public String myMethod(Map pars) {...}

The second form allows sending the Spring application context to the presentation method (needed when e.g. the Spring Dependency Injection functionality should be accessed):

public String myMethod(Map pars, ApplicationContext appCtx) {...}

User Management

ITG-technology allows obtaining information about the logged user. This functionality is usable only in JOP portal environment. It is accessible using the interface NazouContext.

Cooperation of Tools

Each tool represents an independent software component, which has a high degree of inner cohesion. On the other hand, a tool can use services of other tools, which means to be dependent on the services of the other tools. This is a drawback because the tool’s highly cohesive source code should not depend on classes of other tools.

An effective solution to this drawback is offered by the design pattern Dependency Injection (DI). ITG-technology uses Spring framework as an implementation of DI pattern, which contains a so-called light weight DI container.

Each tool can define its own components which should be visible from outside in the form of interfaces defining the provided services and classes implementing these interfaces. The other tool which wants to use a service needs to know only the interface of the service.

Each tool can define its Spring beans in an autonomous file. It is recommended to put this file into a separate subdirectory, so this file could not be directly downloaded (it can contain passwords to database access). The names of these beans should be unique in scope of the whole Cocoon.

These beans can represent also the presentation classes, so they can be called using the bean names.

The beans can also accept setting of other tools’ components published in the same manner (thus the injection of dependencies can occur).

If you want to define a simple bean of which you will not set any attributes, you can create the following file:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">

<beans>
    <bean id="demo.example" class="nazou.tools.demo.Example"/>
</beans>

This file must be registered in ITG-technology. This can be done by adding the following-like line to the file web-inf/classes/applicationContext.xml:

<import resource="../../nazou/tools/demo/beans/beans.xml" />

This code imports the bean declarations from the external file.

You can use Spring together with the object-relation mapper Hibernate in order to simplify work with persistent objects. More details about how to use Hibernate in Spring are in Spring documentation. ITG-technology uses this combination of the frameworks for user maintenance in the test environment (not under JOP portal). The beans representing the user database data sources (dataSourceMySQL, dataSourceHSQL) are defined in the file web-inf/classes/databaseBeans.xml this way:

<bean id="dataSourceMySQL" class="org.springframework.jdbc.datasource.DriverManagerDataSource">
    <property name="driverClassName">
           <value>org.gjt.mm.mysql.Driver</value>
    </property>
    <property name="url">
           <value>jdbc:mysql://localhost/nazou_main</value>
    </property>
    <property name="username"><value>root</value></property>
    <property name="password"><value>...</value></property>
</bean>

<bean id="dataSourceHSQL" class="org.springframework.jdbc.datasource.DriverManagerDataSource">
    <property name="driverClassName">
           <value>org.hsqldb.jdbcDriver</value>
    </property>
    <property name="url">
           <value>jdbc:hsqldb:hsql://localhost:9002</value>
    </property>
    <property name="username"><value>sa</value></property>
    <property name="password"><value></value></property>
</bean>

A session factory for Hibernate in Spring, which uses MySQL database (bean dataSourceMySQL), is defined in the same file this way:

<bean id="sessionFactoryMySQL" class="org.springframework.orm.hibernate3.LocalSessionFactoryBean">

    <property name="dataSource">
           <ref bean="dataSourceMySQL"/>
    </property>

    <property name="mappingResources">
           <list>
                 <value>user.hbm.xml</value>
                 <value>role.hbm.xml</value>
           </list>
    </property>

    <property name="hibernateProperties">
           <props>
                 <prop key="hibernate.dialect">
                        org.hibernate.dialect.MySQLDialect
                 </prop>
                 <prop key="hibernate.show_sql">true</prop>
           </props>
    </property> 

</bean>

The content of the variable mappingResource is a list of names of mapping files. In the mapping files there are defined mappings of class attributes to columns of database tables.

In the variable hibernateProperties there are stored standard parameters of Hibernate. The most important parameter, which must be always specified, is the SQL dialect.

The simplest way to use Hibernate is to extend the class HibernateDaoSupport. It presupposes to set an implementation of session factory to the proper property:

<bean id="IConsumerRegistration" class="nazou.om.cs.ConsumerStorage">
    <property name="sessionFactory">
           <ref bean="sessionFactoryMySQL"/>
    </property>
</bean>

The class ConsumerStorage (from ITG-technology) inherits from HibernateDaoSupport. A reference to bean sessionFactoryMySQL is injected to it.

Diagnostic Messages

Diagnostic messages are useful for debugging and tuning application or for watching and controlling an application run. Diagnostic messages are created by application components themselves.

The important issues to be addressed according to diagnostics are follows:

§  When to generate a message?

§  What to write into the message?

§  How to generate the message?

§  Where will the message be stored?

There are two possible extremes of generating messages. One case is to generate messages very occasionally or generate no messages at all. These messages are usually useless, because they do not provide enough information to deduce correct conclusions about the state of application or about causes of its crash. In the second case messages are generated everywhere and anytime it is possible. The consequence of this approach is overall slowing of the application.

The appropriate amount of diagnostic information can vary for the same application. Thus a solution to the situation is to assign a priority to the generated messages. Thus messages involving e.g. application crash can be distinguished from debugging messages.

Information written in diagnostic messages should be new and unpredictable in general. That means to not reply already stored information or information known beforehand.

A tool can use its own diagnostic functionality, but this is unnecessary work – there are already prepared solutions available. The most common used solution for Java is the library log4j, which is used also in ITG-technology.

The log4j interface is simplified in ITG-technology. The usage of diagnostic functionality of ITG-technology is easy and transparent. On the other side, messages from a tool are stored in a separate file and the hierarchic loggers and some other features of log4j can not be used.

In order to generate diagnostic messages using ITG-technology, you must gain reference on object of type NazouLog:

NazouLog log = NazouLog.getLogger("MyTool");

The argument of the getLogger method is the name of the tool. If a logger object with this name does not exist, it is created. If it exists it is returned, so objects of a particular tool share the same logger. With the logger object the tool can store messages using these methods (identical to log4j methods):

log.debug("this is debug level");
log.info ("this is inform level");
log.warn ("this is warning level");
log.error("this is error level");
log.fatal("this is fatal level");

Each method creates a diagnostic message with a particular priority. The methods are listed above in the order from less important to the most important one. Using log4j configuration, the priority level of logging can be set. The priority level filters less important messages and stores only messages with the same or higher priority.

This setting should be written in a tool’s separate configuration file, e.g. MyTool-log.properties (where MyTool is the name of the tool). The configuration file is stored in the configuration directory according to the common configuration. The configuration file may also contain other settings, which are supported by log4j.

The log files are stored in the common logging directory; see the section about tools’ configuration.

Common Configuration

Common configuration functionality of ITG-technology allows tools access shared files and their configuration files.

Common configuration supports:

§  Gaining the top (root) directory of all shared files, which can be used to access the files from tools. The root directory is set during ITG-technology installation – either as an environment variable NAZOU_HOME, or as a property ROOT_FOLDER in the file Nazou_Bootstrap.properties. The file Nazou_Bootstrap.properties is usually stored in the directory WEB-INF/classes.

§  Gaining the URL of the root directory in order to e.g. display shared files in web browser. The URL of the root directory is set similarly to the root directory – either as an environment variable NAZOU_HOME_URL, or as a property ROOT_URL in the file Nazou_Bootstrap.properties.

§  Loading a configuration file for a tool in the form of a Java properties file. The configuration file is stored in the subfolder config of the root folder. In the case when some attribute misses in this file, the default configuration file Nazou-Commons.properties in the same subdirectory is used.

§  Gaining common logging directory (the directory where the tools’ logs are stored, which is the subdirectory logs of the root directory) and common configuration directory (the directory where the configuration files are stored – see the previous bullet).

§  Gaining information about language preferences. These preferences are stored in the default configuration file – see the section about language support.

The access point of common configuration functionality is the Java class NazouConfiguration providing its services through static methods. These examples show retrieval of the root folder and accessing a tool’s configuration parameter:

String rootFolder = NazouConfiguration.getRootFolder();
    // retrieves the root directory

NazouProperties props = NazouConfiguration.getProperties("MyTool.properties");
    // creates a configuration object from the specified properties file

String property = props.getProperty("my_property");
    // retrieves the value of the specified property

For more information on the class NazouConfiguration or other related classes see their Javadoc documentation.

Language Support

Support of several languages in tools is carried out by ITG-technology. Language dependent text strings in tools usually have origin in three different sources:

§  the source code,

§  databases,

§  XML files.

Source Code

Language support allows retrieval of language dependent texts (originally stored in the source code) from special Java properties files. A tool should have properties files with the name <Tool’s name>_<Language>.properties, e.g. MyTool_EN.properties. Such files should be created for all languages that the tool wants to support.

The content of such file is a set of couples key=value, where key is the identifier of the localized text and value is the text itself in the specified language. Given a key, the language support can retrieve the text value in the proper language according to specified language preferences.

The language preferences are defined in the default configuration file Nazou-Commons.properties as an attribute LANGUAGE_HIERARCHY, e.g.:

LANGUAGE_HIERARCHY=EN;SK

The first language is the most preferred, the next is less preferred, and so on. The language support searches the language properties files according to the language preferences and for the given key, it retrieves the text in the most preferred language.

The language support is realized by the class NazouLocalization. At first, an instance of the class for the tool must be retrieved using a static method, e.g.:

NazouLocalization locale = NazouLocalization.getInstance("MyTool");

After initialization of that instance (including loading texts from the language files), this instance is saved within the class NazouLocalization. Any subsequent call of getInstance will return the same instance for the tool, thus preventing multiple loading of the language files.

The instance can be then used for retrieving language dependent texts using the method resolve with the one argument – the required text’s identifier, e.g.:

String text = locale.resolve("my_text_identifier");

Databases

In order to allow localization of external texts retrieved from e.g. a database (relational, ontological, etc.), the static method resolve should be used. It has the following parameters:

§  String[] allInfo – actual language dependent texts to be processed,

§  String[] langEntrieslanguages (EN, SK, etc.) of the texts in allInfo,

§  String[] labelslabels for the allInfo elements.

So the text allInfo[i] is specified in the language langEntries[i] and it has the label labels[i].

The static method resolve retrieves those texts from allInfo, which are unique for each label and are specified in the most preferred language according to the language preferences. Example:

String[] allInfo = {"Text 1", "Text 2", "Text 3", "Text 4"};
String[] langEntries = {"SK", "EN", "SK", "EN"};
String[] labels = {"LABEL_1", "LABEL_1", "LABEL_2", "LABEL_3"};

String[] result = NazouLocalization.resolve(allInfo,langEntries,labels);

According to the language preferences EN;SK, the result will contain {"Text 2", "Text 3", "Text 4"}.

XML files

Usage of localization in XML is not specially treated, because XML language offers its own mechanisms for solving this problem (mainly using xml:lang attribute).

Demonstration Tool

In order to show some of the specified functionality of ITG-technology, a demonstration tool Demo was created. Its source code can be seen in the ITG-technology distribution in the directory src. After the installation of ITG-technology, the tool can be tested in the web application environment.

The tool Demo contains demonstrations of the following features of ITG-technology:

§  a static page, where other demonstrations can be accessed,

§  presentation methods invocations using a hyperlink – with and without parameters and using Java class and Spring bean,

§  a form consisting of a table with editable texts which are sent to a presentation method,

§  diagnostic messages creation,

§  display of shared files, including the tool’s log with the created diagnostic messages.

A.3          Development Manual

A.3.1      Tool Structure

ITG-technology consists of the following packages (the package naming template is not consistent and was not changed for its backward compatibility):

§  nazou.infr.cocoon – provides classes for communication with the application environment.

§  nazou.infr.cocoon.generator – contains custom Cocoon generator (the ITG-technology generator used for presentation generation).

§  nazou.om – stores interfaces and classes for user management.

§  nazou.om.cs – contains the implementation of user identification.

§  nazou.tools.demo – holds an example application (Demo tool).

§  sk.nazou.config – supports common configuration for tools.

§  sk.nazou.locale – holds a class responsible for the localization of texts.

§  sk.nazou.log – contains support for tools’ logging.

A.3.2      Method Implementation

In this section, main classes of the specified packages are described. For their detailed description including the description of their methods see ITG-technology Javadoc documentation.

The package nazou.infr.cocoon contains the following main interface and class:

§  NazouContext (interface) – provides information about the application environment for tools, e.g. the logged user, HTTP request parameters, session attributes, etc.

§  NazouFormsHelper – provides help for presentation generation (few often XHTML constructs).

The package nazou.infr.cocoon.generator contains the following main class:

§  NazouFormsGenerator – is the custom Cocoon generator designated to presentation generation. When appropriate, invokes presentation methods and processes their output. It also implements the interface NazouContext.

The package nazou.om contains the following main interface and class:

§  IConsumerStorage (interface) – declares methods that are responsible for user management.

§  User – stores user information, mainly his login and identifier (ontology URI).

The package nazou.om.cs contains the following class:

§  ConsumerStorage – implements the interface IConsumerStorage.

The package nazou.tools.demo contains the following class:

§  Example – implementation of the tool Demo.

The package sk.nazou.config contains the following classes:

§  NazouConfiguration – provides information about common folders and URLs and reads configuration (properties) files.

§  NazouProperties – stores the properties read from a specified properties file.

The package sk.nazou.locale contains the following class:

§  NazouLocalization – enables retrieving of language dependent texts and stores language specific settings.

The package sk.nazou.log contains the following class:

§  NazouLog – supports creation of diagnostic messages.

A.3.3      Enhancements and Optimizing

ITG-technology bears signs of a long development. For the reason of backward compatibility, its naming conventions are not consistent and there are many deprecated classes and methods in it. In order to make it more readable and transparent, the packages should be changed according to one naming scheme and the deprecated elements should be deleted at all.

In order to lower the level of dependency of tools on ITG-technology, the technology should be also divided into more libraries. It should be divided into at least two components:

§  presentation generation,

§  other functionality.

A.4          Manual for Adaptation to Other Domains

ITG-technology is completely domain independent, so it is directly usable in any other information domain.