JPOS

TM

Presentation Manager
Quick Guide v1.5

Table Of Contents
1 Abstract........................................................................................................................................................3 2 Copyright.....................................................................................................................................................4 3 Quick guide................................................................................................................................................. 5 3.1 Revision History.................................................................................................................................. 5 3.2 Before Starting.....................................................................................................................................6 3.3 Starting.................................................................................................................................................7 3.3.1 Location Files...............................................................................................................................7 3.3.2 Menu File.....................................................................................................................................7 3.3.3 Jetty File.......................................................................................................................................8 3.3.4 Application Resources................................................................................................................. 8 3.3.5 QBean.......................................................................................................................................... 8 3.3.6 Template.......................................................................................................................................9 3.3.7 Startup Log...................................................................................................................................9 3.4 Entities...............................................................................................................................................11 3.4.1 Weak-entity................................................................................................................................ 12 3.4.2 Highlights...................................................................................................................................12 3.5 Operations..........................................................................................................................................13 3.5.1 Definition................................................................................................................................... 13 3.5.2 Configuration............................................................................................................................. 13 3.5.3 Context.......................................................................................................................................13 3.5.4 Predefined Operations................................................................................................................14 3.5.5 Custom Operations.....................................................................................................................14 [Link] Define the Action............................................................................................................... 14 [Link] Define the Action class.......................................................................................................14 [Link].1 [Link]..............................................................15 [Link].2 [Link].................................................... 15 [Link].3 [Link]...................................................... 16 [Link].4 [Link]............................................................. 16 [Link] Define JSP page..................................................................................................................16 [Link] Icon & Style....................................................................................................................... 16 [Link] Naming and internationalization........................................................................................ 17 3.6 Fields..................................................................................................................................................18 3.6.1 Converters..................................................................................................................................18 [Link] Simple converters...............................................................................................................19 [Link] Advanced converters.......................................................................................................... 20 [Link] Generic converters..............................................................................................................20 [Link] Custom converters..............................................................................................................20 [Link] External Converters............................................................................................................22 3.6.2 Validators................................................................................................................................... 23 [Link] Predefined validators..........................................................................................................23 [Link] Custom Validators.............................................................................................................. 24 3.7 Security..............................................................................................................................................25 3.8 Monitors.............................................................................................................................................28 3.8.1 Introduction................................................................................................................................28 3.8.2 Existing sources......................................................................................................................... 29 3.8.3 Existing formatters.....................................................................................................................29 3.8.4 Examples....................................................................................................................................30

Jeronimo Paoletti - jPOS Presentation Manager Quick Guide

2 / 29

1 Abstract
This document is intended to be a fast guide to use jPOS Presentation Manager so, you will not have a detailed description or justification of the methodology here. Before starting with this document please read jPOS Project Guide and the jPOS Programmer's Guide. This document assumes that you have basic knowledge about jPOS, jPOS-EE and the documents above mentioned. It is also recommended to have a basic knowledge about JSP and Struts1.

Jeronimo Paoletti - jPOS Presentation Manager Quick Guide

3 / 29

2 Copyright
JPOS Copyright Notice jPOS Project [[Link] Copyright (C) 2000-2010 Alejandro P. Revilla This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

Jeronimo Paoletti - jPOS Presentation Manager Quick Guide

4 / 29

3 Quick guide

3.1 Revision History

Date 13/06/10 02/07/10 04/07/10 24/07/10 29/07/10 01/02/11 04/09/11 Author J. Paoletti J. Paoletti J. Paoletti J. Paoletti J. Paoletti J. Paoletti J. Paoletti Version Notes 1.0 1.1 1.2 1.3 1.4 1.5 1.6 Started document Some corrections. Added external location. Minor fixes. Added Operation Context description. Adjustments on validators section. Added order property to entities. Added security section content. Added monitor section content. Added chapter numeration Added external converters Updated a lot of stuff

Jeronimo Paoletti - jPOS Presentation Manager Quick Guide

5 / 29

3.2 Before Starting

If you use GIT you can get the submodules right from [Link]. You can do so with the following commands inside your already initialized git local repository:

git submodule add git://[Link]/jpaoletti/jpospm_core.git modules/jpospm_core git submodule add git://[Link]/jpaoletti/jpos_web_lib.git modules/jpos_web_lib git submodule add git://[Link]/jpaoletti/jpospm_struts.git modules/jpospm_struts git submodule add git://[Link]/jpaoletti/jpos_jetty7.git modules/jpos_jetty7 git submodule add git://[Link]/jpaoletti/jpospm_core_db.git modules/jpospm_ core_db git submodule add git://[Link]/jpaoletti/jpospm_security_ui.git modules/jpospm_ security_ui git submodule init git submodule update

Modules jpos_web_lib, jpospm_struts and jpos_jetty7 are optional but needed to use PM Struts implementation. Module jpospm_core_db is needed to use PM with a Data Base connection as Data Access. Module jpospm_security_ui is a set of entity definition that implements a visualization for PM security objects. Is useful as is and as example. Also, the following jPOS modules are required commons jpos constants

You can use the subversion repository but it is usually not up-to-date so use it at your own risk [Link] Note that an example of the PM can be downloaded at [Link] to show most of the functions.

Jeronimo Paoletti - jPOS Presentation Manager Quick Guide

6 / 29

3.3 Starting
As first step I highly recommend to create a new folder in your modules directory named project_ui. Inside it create the following folder structure:
modules project_ui src deploy cfg entities monitors webapps pm templates

Once you have this folders, you must create this must have files.

3.3.1 Location Files

Locations are a complex concept. It will be explained somewhere else. This file must have at last the following content.
cfg/[Link]

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE menu SYSTEM "[Link]"> <locations> <location id="pmstruts" class="[Link]"/> <location id="external" class="[Link]"/> </locations>

3.3.2 Menu File

This is the menu. Nesting is arbitrary and perm property only applies if you use pm_security.
cfg/[Link]

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE menu SYSTEM "[Link]"> <menu> <menu-list text="[Link]" perm=""> <menu-list text="[Link]" perm=""> <menu-item text="[Link]" perm=""> <location id="pmstruts" value="/[Link]?pmid=yyyy" /> </menu-item> <menu-item text="[Link]" perm=""> <location id="external" value="[Link] /> </menu-item> </menu-list> </menu-list> </menu>

Jeronimo Paoletti - jPOS Presentation Manager Quick Guide

7 / 29

Each text is an entry key in the application resource file. The perm is the permission needed to see this menu option when using security. The location is the way the menu builds the menu. pm_struts has two locations, one for internal use of pm entities and one for external calls to another pages.

3.3.3 Jetty File

Jetty file defines port used by web application. Just copy
modules/jetty7/cfg/[Link]

to
modules/project_ui/cfg/[Link]

3.3.4 Application Resources

This file is where all the text will live.
cfg/[Link]

[Link]=Some Title [Link]=Some Subtitle ...

3.3.5 QBean
The bean file must be created in the application deploy folder and is the running part of PM. The definition must be something like:
deploy/80_pm.xml

<presentation-manager class="[Link]" logger="Q2"> <property name="debug" value="false" /> <property name="template" value="default" /> <property name="appversion" value="1.0.0" /> <property name="login-required" value="true" /> <property name="ignore-db" value="false" /> <property name="title" value="[Link]" /> <property name="copyright" value="[Link]" /> <property name="contact" value="some@[Link]" /> <property name="subtitle" value="[Link]" /> <property name="default-data-access" value="[Link]"/> <property name="persistence-manager" value="[Link]"/> <property name="session-timeout" value="900" /> <property name="menu" value="cfg/[Link]" /> <!-- Struts Specific --> <property name="hideable-header" value="true" /> <property name="struts-ignored-extensions" value="css,gif,png,jpg,js" /> <property name="welcome-page" value="[Link]" />

Jeronimo Paoletti - jPOS Presentation Manager Quick Guide

8 / 29

<!-- External Converters <property name="external-converters" value="cfg/[Link]" /> <!-- ... <!-- Busissnes Entities --> <property name="entity" value="cfg/entities/[Link]" /> <!-- ... --> <!-- Monitors --> <property name="monitor" value="cfg/monitors/[Link]" /> <!-- ... --> </presentation-manager>

debug template

Activate some debugs Name of the folder containing the template to uses. Default uses modules/pm_struts/webapps/templates/default . A good practice is to copy this folder (full path) inside your project module to create your own template. Version shown in main page of your application If true the application uses authentication. If true, the application ignores everything related to Data Base access. ApplicationResource key for the title ApplicationResource key for the subtitle Default entity Data Access Copyright text Session timeout in milliseconds Path to menu file Contact mail With this option, the default converter can be changed. Not recommended. If true, menu bar and header can be hidden with a button A comma separated list with the extensions that will be ignored by the general filter when processing the http servlet so none of this extensions will have context processing A JSP page or struts action to change the index One or more external converters definition files One or more entities files One or more monitor files

appversion login-required ignore-db title subtitle default-data-access copyright session-timeout menu contact default-converter hideable-header struts-ignoredextensions welcome-page external-converter* entity* monitor*

Jeronimo Paoletti - jPOS Presentation Manager Quick Guide

9 / 29

3.3.6 Template
It is recommended to copy the default template (located at pm_struts module modules/pm_struts/webapps/pm/templates/default) into your own module, preserving the path but changing the name of the final folder. Something like:

cp -r modules/pm_struts/webapps/pm/templates/default modules/project_ui/webapps/pm/templates/mytemplate

You should configure your Qbean file as

<property name="template" value="mytemplate" />

After that, you can freely change the style of the site by modifying the css and images inside your folder.

3.3.7 Startup Log

When starting, Q2 server will show up some log for presentation manager. This log is something like:
<log realm="[Link]" ...> <info> <startup>Presentation Manager activated</startup> <configuration> (*) Template mytemplate (*) Default Data Access [Link] (*) Application version [Link] (*) Title [Link] (*) Subtitle [Link] (*) Contact [Link] (*) Login Required false (*) Persistance Manager [Link] <configuration> <entities> (*) sysconfig [Link] ... </entities> <monitors> (*) q2 [Link] (*) status [Link] ... </monitors> <locations> (*) pmstruts [Link] (*) external [Link] </locations> </info> </log>

Reference:
(*) () (?) (!) Item Weak Item Item correctly loaded. entity correctly loaded. correctly loaded but with an unknown class. with error. Look for the exception in previous log.

Jeronimo Paoletti - jPOS Presentation Manager Quick Guide

10 / 29

3.4 Entities
The entities files are recommended to go in cfg/entities of your ui module. General definition of an entity is:
<?xml version='1.0' ?> <!DOCTYPE entity SYSTEM "cfg/[Link]"> <entity id="anentity" clazz="[Link]" extendz=otherentity nocount=false> <dataAccess class="[Link]" /> <listFilter class=xxx /> <order>...</order> <highlights>...</highlights> <operations>...</operations> <field.../> </entity>

id clazz extendz no-count

Id of the entity. Must be global unique Class of the represented object Optional entity id to extends its fields If true, no operation use the count method of the data access. It has been made for entities with a large amount of instances. A list of avaible operations for this entity. The list of fields of the entity. Is an implementation of EntityFilter interface to filter the content of the list operation. In a near future, this will be a property of the operation list. String with a list of field ids that determine the order of the fields. May be separated with any separator. If a field is not included it goes to the tail.

dataAccess Overrides the default data access. operations field* ListFilter Order

The name of the entity is determined by the following line in the application resource file:
[Link]=Some name

It is recommended to save the file with the id of the entity as the filename. In this case

cfg/entities/[Link]

Before an entity become available, you must add the following line in deploy/80_pm.xml file

<property name="entity" value="cfg/entities/[Link]" />

Jeronimo Paoletti - jPOS Presentation Manager Quick Guide

11 / 29

3.4.1 Weak-entity
A weak-entity is an entity hardly dependent of another entity. That means that it only exists if the other entity contains it and cannot exists alone.
<entity id="..." clazz="..."> <owner> <entityId>xxxxx</entityId> <entityProperty>xxxxx</entityProperty> <entityCollectionClass>[Link]</entityCollectionClass> <localProperty>xxxxx</localProperty> <localPosition>xxxxx</localPosition> </owner> .... </entity>

entityId entityProperty entityCollectionClass localProperty localPosition

Parent entity id Parent entity field that points to a collection of weak entity instances Class of the entity parent collection of weak entity instances Optional, entity field pointing to parent Optional, entity field index for parent collection. Only needed in indexed collections.

3.4.2 Highlights
Highlights are a way to make some items stress on others on any operation but specially in list.
<entity id="..." clazz="..."> <highlights> <highlight field="xxx" value="xxx" style="xxx" scope="xxx" /> </highlights> </entity>

field value style scope

Id of the field that will be checked for highlight Value to determine if the highlight is applied Internal codification for styling. Struts module implement this as html classes. Could be instance (highligth all the instance) or property (just highlight the field)

Jeronimo Paoletti - jPOS Presentation Manager Quick Guide

12 / 29

3.5 Operations
3.5.1 Definition
Operations are the things you can do with an entity instance. For example, you can list the instances, add a new one, edit an existing, delete one, sort the list, filter the list and so on. Each operation may have its own properties and may show a confirmation dialog before execute.
<entity id="..." clazz="..."> <operations> <operation id="xxx" scope=xx display=xx enabled=xx confirm=xx> <context class="xxx" /> <properties> <property name="xxx" value="xxx"/> ... </properties> </operation> ... </operations> ... </entity>

3.5.2 Configuration
id scope display enabled confirm properties Unique global id. The same operation may be used on more than one entity but just once on the same entity. item | general . Item affects only one entity instance. General affects none of any instances. Operations id where this operation will be shown true | false . Determine if the operation is enabled. Disabled operations are not showed. true | false . Determine if a previous confirmation is needed. Operation specific properties

3.5.3 Context
A context may be defined for each operation. A context is a class implementing OperationContext or extending OperationContextSupport with three methods.

/** This method is executed at the very beginning of the process, before converting or replace any * data on objects. */ public void preConversion (PMContext ctx) throws PMException; /**This method is executed before trying to execute the main method of the * operation, that is before opening any transaction. * @param ctx The context

Jeronimo Paoletti - jPOS Presentation Manager Quick Guide

13 / 29

*/ public void preExecute

(PMContext ctx) throws PMException;

/**This method is executed after the main method of the operation. * @param ctx The context */ public void postExecute (PMContext ctx) throws PMException;

3.5.4 Predefined Operations

list. Have the following properties searchable: Add a little search paginable: Add pagination for the list show-row-number: Shows a little number near each row operation-column-width: Width of the first column of the list table sort-field: Id of the field taken for sorting sort-direction: asc / desc show add edit delete sort filter clearfilter

3.5.5 Custom Operations

NOTE: This is only for Struts implementation In pm_core, operations are just a definition. The PM implementation must define a way to execute this operations. In pm_struts, each operation is defined as an action with the path defined as the operation id. To define a new operation (lets say, named myoper) in pm_struts you need to do the following steps.

[Link] Define the Action

You need to create the following file in your module and append the following text.
cfg/[Link]

<action path="/myoper" type="[Link]"> <forward name="success" path="/pages/[Link]"/> </action>

This will add the new action. If you need to define an FormBean (remember that this is Struts 1) you can add it in the file cfg/[Link]. If you want to add a global forward, you can do it in cfg/[Link] .

[Link] Define the Action class

This may not be necessary as your action can be defined as a forward, but, if you need to, there is some help. In any case, you need extend your class from [Link] and

Jeronimo Paoletti - jPOS Presentation Manager Quick Guide

14 / 29

implement doExcecute method and most of time it will look something like this:

@Override protected void doExecute(PMStrutsContext ctx) throws PMException { final MyOperOperation op = new MyOperOperation("myoper"); if () { throw new PMForwardException(CONTINUE); } }

If this method ends without exceptions, then success forward is returned. If you want to return another forward, you can throws the following exception:
throw new PMForwardException(someforward);

If the operation returns false it indicate that its not finished and something else must be done before succeed. This is the common case of editing. First you need to show the edition page and after that you are done. This is a two-step operation. You can also throw a [Link] to forward to a not defined forward. MyOperOperation must implement [Link] interface or, better and recommended, extend from [Link] . This class provides almost any needed behavior. You can override the following protected methods to change the default behavior:

/** Default true. Throws an UnathorizedException if there is no user logged */ protected boolean checkUser(){ return false; } /** Default false. Opens a Data Access transaction before doExecute */ protected boolean openTransaction() { return false; } /** Default false. Forces execute to check if there is a selected item */ protected boolean checkSelected() { return true; } /** Default false. Forces execute to check if there is an entity defined in parameters*/ protected boolean checkEntity(){ return true; }

OperationCommandSupport adds a lot off help. Common definition of this subclasses overrides prepare and doExcecute methods. Operations are intended to be free of view stuff so keep them clean.

Jeronimo Paoletti - jPOS Presentation Manager Quick Guide

15 / 29

public class MyOperOperation extends OperationCommandSupport { public MyOperOperation(String operationId) { super(operationId); } @Override protected boolean prepare(PMContext ctx) throws PMException { [Link](ctx); // DO NOT FORGET THIS LINE if (!finished(ctx)) { // init some stuff return false; } else { // do some preprocessing return true; } } @Override protected void doExecute(PMContext ctx) throws PMException { [Link](ctx); // DO NOT FORGET THIS LINE // do some good stuff here }

[Link] Define JSP page

It is not always necessary, some action just do something without showing anything but, in the case you need to show a result, you will need to define a JSP page. This must be defined in the following folder:
modules/project_ui/webapps/pm/pages/[Link]

You can take any of the pm_struts pages as an example. You can also define your own custom tags in:
modules/project_ui/webapps/pm/WEB-INF/tags

You have also all the struts, JSTL tags and some useful stuff by using:
<%@include file="../inc/[Link]" %> <pm:page title="[Link]"> </pm:page>

Expression Language (EL) is also available, so you can use things like ${entity} ${field} ${operation} in your JSP.

[Link] Icon & Style

To add an icon associated to your action you must add a 16x16 transparent gif into the following folder:
modules/project_ui/webapps/pm/templates/mytemplate/img/[Link]

After that, you need to add in the [Link] the following lines:

Jeronimo Paoletti - jPOS Presentation Manager Quick Guide

16 / 29

modules/project_ui/webapps/pm/templates/mytemplate/[Link]

.myoper { background:url(img/[Link]) no-repeat 10px 8px; }

[Link] Naming and internationalization

Finally, you need to add a name to your operation. You can do this by adding the following line in your application resource file:
[Link]=Oper name

Jeronimo Paoletti - jPOS Presentation Manager Quick Guide

17 / 29

3.6 Fields
Fields are the representation of each instance variable of the represented class that you are going to visualize in each operation.
<entity id="..." clazz="..."> <field id="xx" property="xx" display="xx" align="xx" width="xx"> <converters> ... </converters> <validators> ... </validators> </field> ... </entity>

id property

Unique id for this field in this entity Optional, the dot represented name of the property that must have a getter and setter in the represented class. This could be something like description or [Link]. If not defined, id is taken for this purpose. Optional, a white separated list of operation ids where this field will be shown. all is the default. Optional, left (default) | center | right Optional, mainly used by list operation, this is the width of the column for this field.

display align width

The name of the field is determined by the following line in the application resource file:
[Link]=Some name

3.6.1 Converters
The converters for a field are the way it is visually shown in the site and also the way the visual representation is translated to a Java object. Each field may have more than one converter for several operations. General definition is:

<field id="xx" ...> <converters> <converter class="xxx" operations="xxx"> <properties> <property name="xxx" value="xxx" /> ... </properties> </converter> </converters> </field>

Jeronimo Paoletti - jPOS Presentation Manager Quick Guide

18 / 29

class operations properties

Class of the converter A white separated list of operation ids where this converter will be used for this field. A group of specific properties for this converter.

All the converters have this default properties: pad-count pad-char pad-direction prefix suffix If padding is applied, this is the number of characters to fill If padding is applied, this is the character used to fill the text If padding is applied, this is the direction of the pad. Could be left or right A text shown before the result text A text shown after the result text

[Link] Simple converters

Some of the most common converters are the following

<converter class="[Link]"> <properties> <property name="max-length" value="xx" /> </properties> </converter> <converter class="[Link]" /> <converter class="[Link]"> <properties> <property name="with-null" value="true | false (default)" /> </properties> </converter> <converter class="[Link]" /> <converter class="[Link]" /> <converter class="[Link]"> <properties> <property name="format" value="dd/MM/yyyy HH:mm:ss" /> </properties> </converter> <converter class="org....[Link]" /> <converter class="org....[Link]"/> <converter class="org....[Link]"/>

Jeronimo Paoletti - jPOS Presentation Manager Quick Guide

19 / 29

[Link] Advanced converters

There are more advanced converters to manipulate collections, objects and weak entities.
<converter class="[Link]"> <!-- This is for editing weak entities. Just take a look :) --> <properties> <property name="weak-entity" value="xx" /> </properties> </converter> <converter class="[Link]"> <!-- display a table with the instances of the other entity, those fields displayed on 'list' operation --> <properties> <property name="weak-entity" value="xx" /> </properties> </converter> <converter class="org....[Link]"> <!-- display a combo with the instances of the other entity--> <properties> <property name="entity" value="xxx" /> <property name="with-null" value="xxx" /> </properties> </converter>

[Link] Generic converters

Generic converter is a converter defined by a bash based xml usually located at cfg/converters/. It is used as every converter but the property filename must be defined.
<converter class="[Link]"> <properties> <property name="filename" value="cfg/converters/[Link]" /> </properties> </converter>

<converter class="[Link]"> <properties> <property name="filename" value="cfg/converters/[Link]" /> <property name="prefix" value="$ " /> <property name="suffix" value=" .-" /> <property name="format" value="0" /> </properties> </converter>

[Link] Custom converters

There are 2 ways to define a new converter. One is through a class extending Converter and define this 2 methods:

public String visualize(PMContext ctx) throws ConverterException; public Object build(PMContext ctx) throws ConverterException;

Visualize in pm_struts usually returns a JSP page name, which must be created in the following folder.

Jeronimo Paoletti - jPOS Presentation Manager Quick Guide

20 / 29

Build must take a string representation of the object and turn it into the final object. For example, Integer Converter turns a 5 into the integer representation, 5.
modules/project_ui/webapps/pm/converters

Usually, ShowSomethingConverter does not need to build nothing so you can just throw an IgnoreConvertionExteption(). Both methods has the following entries in context and helpers inherited by Converter: Field Field Value Instance Wrapper Entity Operation Getter for properties Getter for value Add generic properties [Link](PM_FIELD); [Link](PM_FIELD_VALUE); [Link](); [Link](); [Link](); public String getConfig (String name, String def) ; protected Object getValue(Object einstance, Field field); public String visualize(Object obj, String extra);

The other way is to create a generic converter file, which has the following definition:

<?xml version="1.0" encoding="UTF-8"?> <generic-converter> <visualize> return [Link](); </visualize> <build> throw new IgnoreConvertionException(""); </build> </generic-converter>

Both visualize and build are the same than a normal converter taking in mind that: Content is a Bean Shell script You have a value variable with the value of the field that you are converting. Its an Object. You have a converter variable to access all the properties and helper methods of the Converter class. Both definition must return the same value as a normal converter method.

This way is pretty useful to introduce new converters in a production server without compile or restarting the server.

Jeronimo Paoletti - jPOS Presentation Manager Quick Guide

21 / 29

[Link] External Converters

External converters is a meta definition of converters in a separated xml file. There are 3 goals for this functionality. 1. Is a way to reuse complex converters definition. 2. Is a simplify and modularize entities definitions. 3. Is a way to easy migrate from one visualization engine to another (for example, from Struts to Vaadin) without touching entities. The definition consists of several steps. First, the definition of one or more external converter files. An arbitrary number of files may be defined but ids must be globally unique. Converter definition is the same as in entity files.

cfg/[Link] <?xml version="1.0" encoding="UTF-8"?> <external-converters> <external-converter id="edit-50-string"> <converter class="...SomeEditStringConverter" operations="add edit"> <properties> <property name="max-length" value="50" /> </properties> </converter> </external-converter> <external-converter id="edit-string"> <converter class="...SomeEditStringConverter" operations="add edit"/> </external-converter> ... <external-converters>

Second, definition file must be added as a property inside PM bean.

80_pm.xml <property name="external-converters" value="cfg/[Link]" />

Finally, to link external converters to entities, converter definition in entities file must be replaced with its associated econverter .

Jeronimo Paoletti - jPOS Presentation Manager Quick Guide

22 / 29

For example, we can change this

... <field id="description"> <converters> <converter class="...SomeEditStringConverter" operations="add edit"> <properties> <property name="max-length" value="50" /> </properties> </converter> </converters> </field> ...

for this
... <field id="description"> <converters> <econverter id="edit-50-string"/> </converters> </field> ...

3.6.2 Validators
Validators are classes that check for unwanted situations, like invalid characters, out of range values and so on. A validator can be defined at field level or at operation level. Actually, a validator at field level will apply in all operations.
<field id="xx" ...> <!-- <operation id="xx"> --> <validator class="[Link]"> <properties> <property name="xxx" value="xxx" /> </properties> </validator> </field> <!-- </operation> -->

A field may have more than one validator a and each validator may have its own properties. Usually, each validator has a msg property that is a key of the resource file to show in an error box when the abnormal situation occurs.

[Link] Predefined validators

All of the following classes are in [Link] package IsNameValidator LengthValidator NotNull Validate the pattern name Uses the properties max-length, max-length-msg, min-length and minlength-msg to validate a string length. Check if the object is not null

Jeronimo Paoletti - jPOS Presentation Manager Quick Guide

23 / 29

[Link] Custom Validators

To create a custom validator you just need to implement [Link] interface but a better way is to inherit from [Link] which allow the use of properties. The validation method that must be implemented is
public ValidationResult validate(PMContext ctx);

Context content is the same in converters. ValidationResult is a class with 2 variables boolean successful List<PMMessage> messages True when validation was ok List of errors to be shown

A PMMessage has the following content: key message Arg0, arg1, arg2, arg3 Property for [Link]() method Message from application resource file Arguments for the message

Each PMMessage will be placed as a struts error messsage.

Jeronimo Paoletti - jPOS Presentation Manager Quick Guide

24 / 29

3.7 Security
Security is, at the moment, implemented in a simple way based on eecore3 user management. Basically, it has the same core + implementation concept than Presentation Manager. Implementing an interface you can define your own security or use the basic, database based security or not use at all. Basic PM security uses a powerful Bcrypt algorithm. The DB based implementation is at pm_core_db and also there is a PM based module that provides a basic but useful set of entities to directly include in your PM bean (80_pm.xml) at pm_security_ui. To make use of this modules, you must create the following file in your module_ui/deploy folder:

79_security.xml <security-manager class="[Link]" logger="Q2"> <property name="connector" value="[Link]" /> </security-manager>

The connector define the main interface to implement a security instance module. After including security bean, you must activate login in presentation manager bean:

80_pm.xml <property name="login-required" value="true" /> <property name="ignore-db" value="false" />

If you want to use the pm_security_ui entities you may also include the following lines to PM bean.
<!-Security Entities --> <property name="entity" value="cfg/entities/[Link]" /> <property name="entity" value="cfg/entities/[Link]" /> <property name="entity" value="cfg/entities/[Link]" /> <property name="entity" value="cfg/entities/[Link]" />

[Link] contains the mysql script to create security tables with a default user admin with test password. You must add this to your hibernate configuration file.
<mapping <mapping <mapping <mapping class="[Link]" /> class="[Link]" /> class="[Link]" /> class="[Link]" />

Result will be a login screen at startup and profile link when logged as a user. With security activated, now you can make use of the perm attribute of a menu item to show / hide items depending of defined permissions of each user.

Jeronimo Paoletti - jPOS Presentation Manager Quick Guide

25 / 29

3.8 Monitors
3.8.1 Introduction
Monitors are still under extension but main idea is to watch something over time, like a DB table or a file. Basic definition, similar to entities is an xml with a line attached to PM bean:

80_pm.xml ... <property name="monitor" value="cfg/monitors/[Link]" /> ...

A monitor definition is something like

<?xml version='1.0' ?> <!DOCTYPE entity SYSTEM "cfg/[Link]"> <monitor> <id>monitorId</id> <source class="[Link]" > <properties> <property name="xx" value="yy" /> </properties> </source> <formatter class="[Link]" > <properties> <property name="xx" value="yy" /> </properties> </source> <delay>xx</delay> <max>xx</max> <cleanup>true | false</cleanup> <all>true | false</all> </monitor>

id source formatter delay max Cleanup All

Id of the monitor (used on menu or anywhere it need to be referenced) Source is class extending abstract class MonitorSource and represents the where monitor takes information Formatter is a class extending MonitorFormatter (or even MonitorFormatter class) that get a MonitorLine generated by source and turn it into a string. Delay between each refresh (in ms) Maximun number of visible lines. False by default, If true, each refresh of the monitor clean ups the list. False by default. If true, each refresh of the monitor shows all the information given by the source

Jeronimo Paoletti - jPOS Presentation Manager Quick Guide

26 / 29

3.8.2 Existing sources

There are two predefined monitor source implementation. Module pm_core pm_core_db Class [Link] Description A monitor to watch a file. filename property is required.

[Link] A monitor to watch a database query. Three properties are needed: query: SQL text to get the monitor information last-line-query: SQL text to get the monitor last line id-column: column index which identifies the above query.

3.8.3 Existing formatters

There are two predefined monitor formatters. Module pm_core pm_core Class Description

[Link]. Simple formatter that receive a plain string and returns it as MonitorFormatter is [Link]. Formatter that receive an array of items and uses two properties BasicObjectArrayFormatter to format: pads: A string separated by # that represents the padding of each array item. See the example on next section for details. separator: a string that separates each array item.

Jeronimo Paoletti - jPOS Presentation Manager Quick Guide

27 / 29

3.8.4 Examples
Monitor for [Link] file
<?xml version='1.0' ?> <!DOCTYPE entity SYSTEM "cfg/[Link]"> <monitor> <id>q2</id> <source class="[Link]" > <properties> <property name="filename" value="log/[Link]" /> </properties> </source> <formatter class="[Link]" /> <delay>3000</delay> <max>100</max> </monitor>

Jeronimo Paoletti - jPOS Presentation Manager Quick Guide

28 / 29

Monitor file for status table of jPOS status module.

<?xml version='1.0' ?> <!DOCTYPE entity SYSTEM "cfg/[Link]"> <monitor> <id>status</id> <source class="[Link]" > <properties> <property name="query" value="SELECT id, name, state, detail, lastTick, timeout, timeoutState FROM status" /> <property name="last-line-query" value="SELECT id, name, state, detail, lastTick, timeout, timeoutState FROM status" /> <property name="id-column" value="0" /> </properties> </source> <formatter class="[Link]"> <properties> <property name="pads" value="[0,R, ,20] # [1,R, ,40] # [2,R, ,2] # [3,R, ,75]"/> <property name="separator" value=" | " /> </properties> </formatter> <delay>3000</delay> <max>100</max> <cleanup>true</cleanup> <all>true</all> </monitor>

pads formats contains 4 parts, [0, R, , 20] 1. Index of the array 2. R or L: right or left padding 3. Padding character 4. Padding length

Jeronimo Paoletti - jPOS Presentation Manager Quick Guide

29 / 29