Roma
<Meta> Framework
Handbook
"Let's think to the application domain,
then model it in simple Java Classes,
write the business logic and
Roma will make all the rest"
by
Luigi Dell'Aquila, Luca Garulli, Giordano Maestro
Last updated on: 16 December 2008
Revision n. 481
Roma Meta Framework Hand Book - Rev. 481
Page 1 of 167
Document Disclaimer
Information contained in this manual is subject to change without notice. Please check the
web site (see Download Information) to make sure you have the most recent information.
Download Information
For download this document go to
Documentation page.
Trademarks and Service Marks:
Java is a trademark of Sun Microsystems Inc.
JDO is a trademark of Sun Microsystems Inc.
Microsoft, Windows, and Windows NT are either registered trademarks or
trademarks of Microsoft Corporation in the United States and/or other countries.
UNIX is a registered trademark in the United States and other countries, licensed
exclusively through X/Open Company Limited.
All brand names and product names are trademarks or registered trademarks of their
respective companies.
Roma Meta Framework Hand Book - Rev. 481
Page 2 of 167
Contents
1 Before to read............................................................................................9
2 Introduction.............................................................................................10
2.1 Decoupling Solution For Seamless Integration.........................................................10
2.2 Fast Development.........................................................................................10
2.3 Advanced Technology.....................................................................................11
2.4 Semantic Web..............................................................................................11
3 Get and install..........................................................................................13
3.1 Pre-requirements..........................................................................................13
3.2 Install from binaries.......................................................................................13
3.3 Install from sources.......................................................................................13
3.3.1 Get sources.........................................................................................................13
3.3.2 Compile sources...................................................................................................14
3.3.3 Test the installation..............................................................................................15
4 Create your first application.........................................................................16
4.1 Create the project.........................................................................................16
4.2 Project scaffolding........................................................................................16
4.3 Write domain classes......................................................................................17
4.4 Write the application flow...............................................................................19
4.5 Adding persistence and CRUD to an application......................................................21
5 The Meta-Framework concept.......................................................................26
5.1 Aspects......................................................................................................26
5.1.1 Aspects Overview........................................................................................27
5.2 Modules......................................................................................................28
5.2.1 Modules Overview.......................................................................................28
5.3 Accessing to Aspects and Components.................................................................31
5.4 DDD Domain Driven Development.......................................................................31
5.4.1 DDD Resources.....................................................................................................31
5.5 Enrich you model using annotations....................................................................31
5.5.1 Annotations table.................................................................................................32
5.5.2 Java Annotations..................................................................................................32
5.5.3 XML Annotations...................................................................................................33
5.6 Change the meta-model at run-time...................................................................34
6 Console...................................................................................................35
6.1 Console create command.................................................................................36
6.1.1 Syntax...............................................................................................................36
6.1.2 Usage................................................................................................................36
6.2 Console info command....................................................................................37
6.2.1 Syntax...............................................................................................................37
6.2.2 Usage................................................................................................................37
6.3 Console list command.....................................................................................37
6.3.1 Syntax...............................................................................................................37
6.3.2 Usage................................................................................................................37
6.4 Console switch command.................................................................................38
Roma Meta Framework Hand Book - Rev. 481
Page 3 of 167
6.4.1 Syntax...............................................................................................................38
6.4.2 Usage................................................................................................................38
6.5 Console get command.....................................................................................38
6.5.1 Syntax...............................................................................................................38
6.5.2 Usage................................................................................................................38
6.6 Console set command.....................................................................................39
6.6.1 Syntax...............................................................................................................39
6.6.2 Usage................................................................................................................39
6.7 Console add command....................................................................................39
6.7.1 Syntax...............................................................................................................39
6.7.2 Usage................................................................................................................39
6.8 Console crud command...................................................................................40
6.8.1 Syntax...............................................................................................................40
6.8.2 Usage................................................................................................................40
6.9 Console check command..................................................................................40
6.9.1 Syntax...............................................................................................................40
6.9.2 Usage................................................................................................................40
6.10 Console install command................................................................................41
6.10.1 Syntax.............................................................................................................41
6.10.2 Usage..............................................................................................................41
6.11 Console update command...............................................................................42
6.11.1 Syntax.............................................................................................................42
6.11.2 Usage..............................................................................................................42
6.12 Console JSP command...................................................................................43
6.12.1 Syntax.............................................................................................................43
6.12.2 Usage..............................................................................................................43
7 CRUD.....................................................................................................44
7.1 CRUD Working..............................................................................................48
7.2 Customize a CRUD.........................................................................................48
7.2.1 Change the GUI....................................................................................................48
7.2.2 Adding other search conditions.................................................................................50
7.2.3 Order the result...................................................................................................51
7.2.4 Adding pre and post operations events........................................................................51
7.2.5 How to get different CRUDs.....................................................................................54
7.2.6 CRUDHelper........................................................................................................54
8 Conventions.............................................................................................56
8.1 Extension by Composition................................................................................56
8.1.1 Advantages.........................................................................................................57
8.2 Override default behaviour..............................................................................58
8.2.1 Predefined Events.................................................................................................58
8.2.2 Override Collection behaviour (List and Tables).............................................................59
9 Best Practices...........................................................................................60
9.1 Separate domain classes from presentation classes..................................................60
9.2 Dirty approach: dirty you hands when required.......................................................60
10 Controller..............................................................................................62
10.1 Controller in action......................................................................................63
10.2 Field transparent binding...............................................................................63
11 View Aspect............................................................................................65
Roma Meta Framework Hand Book - Rev. 481
Page 4 of 167
11.1 How Roma renders POJOs...............................................................................65
11.2 Area concept..............................................................................................66
11.4 Create your form layout.................................................................................67
11.4.1 Fields area........................................................................................................67
11.4.2 Actions area......................................................................................................68
11.5 Screen and Area concepts...............................................................................68
11.6 Configurable Screens....................................................................................68
11.7 Component placement in screens......................................................................69
11.8 Get the underlying Echo2 components of the XML Configurable Screen.........................69
11.9 RenderingResolver: how to select the component to render......................................70
11.10 Rendering modes........................................................................................71
11.11 Layout mode.............................................................................................75
11.11.1 XPath like syntax...............................................................................................77
11.12 Order the fields and actions...........................................................................77
11.12.1 Ordering embedded instances................................................................................78
11.13 Form Validation.........................................................................................79
11.13.1 Field Validation.................................................................................................80
11.13.2 Custom Validation..............................................................................................81
11.13.2.1 Throw multiple exceptions in one shot...................................................................82
11.13.2.2 Change the Look & Feel.....................................................................................82
11.14 Annotations..............................................................................................82
11.14.1 @ViewClass......................................................................................................82
11.14.2 @ViewField......................................................................................................83
11.14.3 @ViewAction....................................................................................................85
11.14.4 XML layout.......................................................................................................86
11.15 Push commands.........................................................................................88
11.15.1 Download file...................................................................................................88
11.15.2 Open a new window...........................................................................................88
11.15.3 Redirect to a location.........................................................................................89
11.15.4 Refresh a form..................................................................................................89
11.15.5 Show a form.....................................................................................................89
11.16 Implementation: Echo2................................................................................90
11.16.1 Using JSP.........................................................................................................90
11.16.2 Stylesheets......................................................................................................91
11.17 Implementation: Html and CSS2......................................................................93
11.17.1 Architecture.....................................................................................................93
11.17.2 Basic usage......................................................................................................94
11.17.3 Customization through CSS...................................................................................94
11.17.4 Global (application level) CSS................................................................................96
11.17.5 Class level CSS..................................................................................................96
11.17.6 Customization through HTML/JSP...........................................................................96
11.17.7 Customization of automatic behaviour.....................................................................98
12 I18N Aspect...........................................................................................100
12.1 Interface.................................................................................................100
12.2 Implementations........................................................................................100
13 Persistence Aspect..................................................................................102
13.1 Choose the right strategy..............................................................................102
13.2 Atomic strategy.........................................................................................103
Roma Meta Framework Hand Book - Rev. 481
Page 5 of 167
13.3 Change strategy for a single operation..............................................................103
13.3.1 Select the strategy on Query execution....................................................................103
13.3.2 Select the strategy on object loading.......................................................................103
13.4 Java Interface...........................................................................................103
13.5 Query Patterns..........................................................................................105
13.5.1 Query by example..............................................................................................105
13.5.2 Query by filter..................................................................................................106
13.6 Persistence Technologies..............................................................................108
13.6.1 JDO...............................................................................................................108
14 Reporting Aspect....................................................................................111
14.1 Render Types............................................................................................112
14.2 Template Generation...................................................................................114
14.3 Template Manager......................................................................................115
14.4 Implementations........................................................................................115
14.4.1 Jasper Reports Module........................................................................................115
15 Logging Aspect.......................................................................................117
15.1 Example of usage.......................................................................................117
15.2 Messages conventions..................................................................................118
15.3 The Loggers..............................................................................................118
15.4 Annotations reference.................................................................................119
15.5 Implementations........................................................................................119
15.5.1 Bundled core logging...........................................................................................119
16 Scripting Aspect.....................................................................................120
16.1 Interface.................................................................................................120
16.2 Implementations........................................................................................121
16.2.1 Java6 Scripting Module........................................................................................121
17 Monitoring Aspect...................................................................................122
17.1 Implementations........................................................................................122
18 Semantic Aspect.....................................................................................123
18.1 Introduction.............................................................................................123
18.2 The Semantic Aspect purpose.........................................................................123
18.3 Interface.................................................................................................124
18.3.1 Annotations......................................................................................................124
18.3.2 Example of usage...............................................................................................125
18.4 Implementation.........................................................................................128
19 Admin module........................................................................................129
19.1 Info and InfoCategory..................................................................................129
19.2 Realms....................................................................................................129
19.3 Plug-ins...................................................................................................129
19.4 Active sessions..........................................................................................130
19.5 Application Logs.........................................................................................130
19.6 Database.................................................................................................130
19.7 Environment.............................................................................................131
19.7.1 What is an Environment.............................................................................131
19.7.2 Use Environment objects............................................................................131
19.7.3 Admin module to handle environment objects..................................................132
19.8 How to access Admin functionalities.................................................................132
Roma Meta Framework Hand Book - Rev. 481
Page 6 of 167
20 Users module.........................................................................................133
20.1 Dependencies............................................................................................133
20.2 Login......................................................................................................133
20.2.1 Set the login form as the first POJO to display............................................................133
20.2.2 Write your own Login behaviour.............................................................................133
20.3 Activity Log..............................................................................................134
20.4 Accounts..................................................................................................135
20.5 Profiling system.........................................................................................135
20.5.1 How to use it?...................................................................................................136
20.6 Base Group...............................................................................................136
21 Designer...............................................................................................137
22 Messaging module...................................................................................138
22.1 Dependences............................................................................................138
22.2 Display Messaging menu inside your application menu............................................138
23 Workflow Aspect.....................................................................................139
23.1 Implementations........................................................................................140
23.1.1 Tevere Flow module...........................................................................................140
24 ETL.....................................................................................................141
24.1 What is ETL..............................................................................................141
24.2 Etl Aspect architecture................................................................................141
24.3 Defining a custom ETL procedure....................................................................142
24.3.1 The ETL descriptor.............................................................................................142
24.3.2 The Record......................................................................................................142
24.3.3 defining extraction strategy..................................................................................143
24.3.4 defining transformation strategy............................................................................145
24.3.5 Defining load procedure.......................................................................................146
24.3.6 The import procedure description...........................................................................146
24.4 A custom ETL: from JDBC to JDBC...................................................................148
24.5 Validating imported data..............................................................................151
25 Session Aspect.......................................................................................152
25.1 Interface.................................................................................................152
25.2 Usage Example..........................................................................................152
25.3 Implementations........................................................................................153
26 Scheduling............................................................................................154
27 Chart...................................................................................................155
27.1 Introduction.............................................................................................155
27.2 What kind of objects can be represented as charts...............................................155
27.3 What kind of charts can be represented............................................................155
27.4 Installing the chart module............................................................................157
27.5 Rendering a chart.......................................................................................157
27.5.1 Maps and Collections...........................................................................................158
27.5.2 The ChartRenderer class......................................................................................158
27.5.3 The ChartRepresentable interface..........................................................................159
27.5.4 The ChartViewer class.........................................................................................160
27.5.5 Using Chart Module to build images.........................................................................160
28 Service Aspect.......................................................................................161
28.1 How to expose a service...............................................................................161
Roma Meta Framework Hand Book - Rev. 481
Page 7 of 167
28.2 Implementations........................................................................................162
28.2.1 @ServiceClass...................................................................................................162
29 About Romulus.......................................................................................163
30 License................................................................................................164
31 Bibliography..........................................................................................167
Roma Meta Framework Hand Book - Rev. 481
Page 8 of 167
1 Before to read
Symbols used in the document.
Warning, reading this box is very important
Additional information to know
Web resource
All the code is wrapped inside a gray block:
if( true ){
}
All commands to execute are wrapped inside a gray block with the prompt at the
beginning:
> roma add
Roma Meta Framework Hand Book - Rev. 481
Page 9 of 167
2 Introduction
Roma allows you to develop enterprise level Java applications with low effort following a
real Domain Driven Design approach. It's a new way to conceive the application: anything
is a POJO, from the GUI forms to the persistent objects.
Using the Meta-Framework approach you can integrate the latest breaking technology in
your application without modifying your domain and application logic because they are
Roma provides you automatic support for every layer and aspect for your application, from
dynamic web user interface and persistence, to report functionalities, portlet development
and semantic technologies.
Roma is Open Source and commercial friendly
2.1 Decoupling Solution For Seamless Integration
Every day a new tool or framework appears on the market. Using a technology means to
have a marriage with it, very often forever. What happens if you want to change the DBMS
you're using or the engine that persist your objects? Or again your web framework?
Divorces, you know, are costly. Many technologies don't follow standards so the migration
cost is huge. Often it's cheaper to rewrite it from scratch.
Roma is the only "
" framework. Using Roma you're definitely free from the technology
you're using. How it works? Roma provides very generic behaviour interfaces called
". Aspects enclose the most common use cases. Using the tool and framework
through the Aspect allow to leave your code clean from the technology.
But if I need to dirt my hands using the technology directly, can I do it with Roma? Sure.
You can always reach the implementation under the hood. Just remember you had to
migrate that pieces of code in case tomorrow you'll change the technology. In the
documentation you can find some best practice to make migration the easiest possible.
Abstracting the technologies let you to have the development team aware of their. This
can be translated as minor skill requested, therefore less cost.
2.2 Fast Development
I know. So many times you thought that applications were quite similar. You're right!
Technologies are horizontal and you can use the same ones in very different contexts.
What really changes is the Domain. The Domain is the real value of your application,
because you've analyzed it, studied it and shared it with the client.
Roma lets you focus on the domain and treat the rest as a minor detail. It's a pure
How does it work ?
You start off by defining the entities/classes of your domain. You can write them by using
Roma Meta Framework Hand Book - Rev. 481
Page 10 of 167
an IDE of choice or you could have your preferred UML tool do the class generating for you.
Once your model is well documented, let Roma worry about the rest. I'm talking about the
presentation, the persistence of your objects, the internationalization, etc. They can all be
auto-determined figured out by analyzing your domain model.
Since the Java language syntax is not enough to represent the complexity of your domain
(think of all kinds of relationships) you could have the need to enrich your model by adding
same details using
. Annotation can be under the form of
(introduced with Java version 5) or
you can tell Roma to hide a field in your form or to render it in a
different way, to express the kind of relationship between two entities, and much more.
Since you're you're not coupling your application to any specific technology and your
domain is defined as a collection of POJO's, you can generate a fully featured web
application in a short time and without writing one single line of HTML or SQL. Aspect
implementations will deal with it. But remember you always own great powerful in
customization if you need.
This greatly reduces development time and allows your team to focus on the domain,
without them having to be skilled up on every single technology you're using.
Roma is the framework of choice of hundreds of developers who employ it, as we speak,
to build very complex applications in a fraction of the time in comparison to conventional
technologies.
2.3 Advanced Technology
Roma aims to provide integration with the most advanced technologies in the market. Each
module cooperates with the available modules using the common Aspect interface
mechanism. An Aspect is a Java Interface describing the behaviour of a set of modules.
Think to the Persistence Aspect: it defines the most common operation against persistent
objects like: load, update, delete, query, etc.
All the modules and your business logic will collaborate with the Aspects in generic way
using the interfaces. The Aspect implementation will worry about the rest. Continuing with
the example above you can plug a
module as implementation of the Persistence
Aspect to works with your repository in transparent way.
Each component is handled by the
container. By default Roma uses the
2.4 Semantic Web
Web 3.0 has become a reality; the number of web sites that provide semantic information
is growing every day; semantic languages such as RDF, OWL and SPARQL are now well-
established.
Is your application ready for this revolution? What do you have to do to expose your
application domain as semantic web data? And what about importing in your application
Roma Meta Framework Hand Book - Rev. 481
Page 11 of 167
data coming from semantic web sources?
With Roma Meta-Framework you can expose your application data as semantic information
without effort. You can also read semantic information from the Web and translate it in
your application domain. Roma knows how to transform your POJOs into Semantic Web
syntax such as RDF and how to bind semantic information in your applicaitno domain. You
don't have to know RDF, you just have to write POJOs, adding them annotations with
semantic information such as predicates, and Roma SemanticAspect will do the trick.
Roma Meta Framework Hand Book - Rev. 481
Page 12 of 167
3 Get and install
Roma Meta-Framework can be obtained from the web site, as a binary distribution or from
Sourceforge SVN repositories, as a source distribution.
3.1 Pre-requirements
Roma Meta-Framework is a Java framework. In order to implement applications with Roma
you have to install on your computer a Java compiler. Although most of Roma components
are compiled and work with Java 5, in order to take advantage of all Roma functionalities,
you should have Java 6 SDK installed. Go to
SDK.
3.2 Install from binaries
. You will find many packages, one for each
module. For a quick start you just need to download the WebWizard file containing most
useful modules to develop Web applications.
Then follow these steps:
Extract the downloaded archive to a directory in your file system
Set the ROMA_HOME environment variable to the Roma's binary installation
directory just created.
3.3 Install from sources
3.3.1 Get sources
First of all you need to get the sources in order to compile its. We suggest to get always
the latest sources from
since official releases are published every 3-4 months.
3.3.1.1 From Source distribution
1.
2. Extract the downloaded archive to a directory in your file system
3.3.1.2 By checking out from Subversion repository
1. Open a shell and goto in the path where you want to download the sources
2. Assure SubVersion binary directory is in the system path
3. Type:
Roma Meta Framework Hand Book - Rev. 481
Page 13 of 167
romaframework
You can use simpler tools than console SVN such as
information about Sub Version take a look to the
3.3.2 Compile sources
3.3.2.1 Before compile
Before to compile and install the latest version of Roma assure to have the following tools:
Java5+
Java SDK 5.0+. Previous releases don't work since Roma uses Java5 features such as
and Typed Collections. You can download it
Java6+ for some additional modules
If you use additional modules such as Scripting-Java6 please use JDK 6 since it needs
advanced feature contained in Java 6.
Please assure to download the JDK (Java Development Kit) and not JRE (Java Runtime
Environment)
Apache Ant
Apache Ant version 1.7.0 or major. You can download
3.3.2.2 Compile it all
Follow these steps:
1. Change current directory to the Roma's dev directory and execute:
> ant install
2. Wait for building and when finished set the ROMA_HOME environment path to the
dist directory just created by the compilation process (it's at the same level of dev
directory).
Roma Meta Framework Hand Book - Rev. 481
Page 14 of 167
3.3.3 Test the installation
After the download and install test if anything is ok by changing current directory to the
ROMA_HOME and executing the ROMA console:
Under Linux/Unix systems
> cd $ROMA_HOME
> roma.sh
Under Windows systems
> cd %ROMA_HOME%
> roma
If the installation succeeded, the help will appears.
Roma Meta Framework Hand Book - Rev. 481
Page 15 of 167
4 Create your first application
Before we talk about Roma architecture, conventions and so much theory let's create our
very first simple application. Then you can go deeper by reading the rest of the document
learning advanced features and internal behaviour.
4.1 Create the project
to help in generating stuff. Assure to be in the
$ROMA_HOME directory or just set once for ever the $ROMA_HOME directory in the PATH.
' (roma.sh create for Linux/Unix users. The full syntax
for the create wizard will be shown. See below:
ROMA Framework CONSOLE [http://www.romaframework.org]
Use this syntax:
roma create <project-type> <project-name> <src-root-package> [<project-path>]
where: <project-type> is the type of project between types locally availables
(see below)
<project-name> is the name of project to create
<src-root-package> Is the root package for sources
<project-path> is the path where to place the project scaffolding;
if not specified, the current path is taken
Project types locally availables (discovered in the $ROMA_HOME/modules directory):
- simple
- web
- webready
Example:
roma create web blog com.mycompany.blog C:/temp
4.2 Project scaffolding
Now let's create our very first project using the Roma console. Type as follow:
Your brand new application will be waiting for you at the specified directory
(
The create wizard generates the appropriate
metadata files so that your project is
ready to be imported into the IDE.
Roma Meta Framework Hand Book - Rev. 481
Page 16 of 167
If you use another IDE you can create a new project and point it to the project
directory.
Select the menu
Select 'Existing Projects into Workspace'
Change the root directory to 'C:/temp/blog'
Select 'blog' application between the project listed
Click on Finish
Right Click on the Project just imported and then "Properties"
Goto "Java Build Path" item and then select the "Libraries" tab
Assure JDK 5.0 or superior is the used compiler.
Assure in the project properties Java Compiler tab has Compiler compliance level ==
5.0
has a strange bug: the project can't see the
libraries under WEB-INF/libs until you close and repoen the project. If you notice this
issue just close and repoen the project
In some configuration the project won't start unless you add the Jasper Libraries.
is now aware of your project and you can start writing your first domain class.
But before doing that, we must add the other modules we need.
Application needs a front-end. Thus we select the Echo2 framework module for Ajax web
application and we'll use the useful
roma add view-echo2
4.3 Write domain classes
Now let's create the class that represents the Blog entity. Remember that in Roma the very
important thing is the Domain. Other aspects are secondary and driven by the Domain
Model. Create the following classes under it.demo.blog.domain package (Right click on
src/it.demo.blog.domain and the "New Class"). Your may use menu to clean up the code:
package it.demo.blog.domain;
import java.util.List;
Roma Meta Framework Hand Book - Rev. 481
Page 17 of 167
import java.util.ArrayList;
public class Blog {
private String name;
private String title;
private String author;
private List<Post> posts = new ArrayList<Post>();
public String getAuthor() {
return author;
}
public void setAuthor(String author) {
this.author = author;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public List<Post> getPosts() {
return posts;
}
public void setPosts(List<Post> posts) {
this.posts = posts;
}
public String getTitle() {
return title;
}
public void setTitle(String title) {
this.title = title;
}
}
This class represent a Blog entity. Note that Blog class is a simple POJO (or also a
JavaBeans, but we have not created constructor yet). It's a good practice to set attributes
private and generate Getters and Setters for them. Eclipse generate Getter/Setter
automatically by Right Click on the source window, selecting "Source" and then on
"Generate Getters and Setters". Select all attributes and then Ok.
package it.demo.blog.domain;
import java.util.Date;
public class Post {
private Date postedOn;
private String title;
private String content;
public String toString() {
return title != null ? title : "new";
}
Roma Meta Framework Hand Book - Rev. 481
Page 18 of 167
public String getContent() {
return content;
}
public void setContent(String content) {
this.content = content;
}
public Date getPostedOn() {
return postedOn;
}
public void setPostedOn(Date postedOn) {
this.postedOn = postedOn;
}
public String getTitle() {
return title;
}
public void setTitle(String title) {
this.title = title;
}
}
This class represent a Post entity that is part of a Blog. Note that Blog contains a collection
of references to Post. This relationships will be saved in database transparently.
Remember to initialize any POJO's collections or they cannot handle values!
The toString() method tells Roma what to display in list component. The object will be
displayed in short form as the String returned by toString() method, and in this case the
post title.
4.4 Write the application flow
By default Roma empty project shows the HomePage class, in our example generated under
src/it.demo.blog.view.domain directory. Open it. You can note that this class is a POJO
too. HomePage is under the domain package of view. View stands for View Aspect. So
HomePage is a domain class but regarding view aspect only. All domain classes common to
the applications should reside in it.demo.blog.domain. This package is reachable by every
aspects and it's the base for other Aspect's Domain Classes.
Now add a piece of code to see your Blog instance. Rename the button method in
editBlog() and add a line of code as follow:
package it.demo.blog.view.domain;
import org.romaframework.aspect.flow.annotation.FlowAction
import org.romaframework.aspect.view.annotation.ViewClass;
import org.romaframework.aspect.view.desktop.config.ScreenManager;
import org.romaframework.aspect.view.echo2.screen.ConfigurableScreen;
Roma Meta Framework Hand Book - Rev. 481
Page 19 of 167
import org.romaframework.aspect.view.echo2.form.TopForm;
import org.romaframework.core.flow.ObjectContext;
import it.demo.blog.domain.Blog;
@ViewClass(layout = "screen://body")
public class HomePage {
public HomePage() {
Screen screen = ObjectContext.getInstance()
.getComponent(ScreenManager.class)
.getScreen("main-screen.xml");
ObjectContext.getInstance().getComponent(ViewAspect.class)
.setScreen(screen);
}
@FlowAction(next=Blog.class)
public void editBlog() {
}
}
Now you need to know that: ObjectContext singleton class is the only class of Roma your
POJOs will see. setScreen() replace current Screen. A Screen is the place where View
Aspect will show components. A Screen knows where to place components.
Here we use the default screen defined in
:
it.demo.blog.view.domain.screen.main-screen.xml
@FlowAction annotation tells to show an instance of class Blog as next step. Each user
session has a pool of instanced POJO. FlowAction check if an instance of specified class is
already present in the pool then use it, otherwise create a new instance and insert that in
the pool for further use (such as the "back" operation)
Now you are able to start your new application. Instead of creating a WAR file and
deploying it in to the Application Server everytime, we suggest to use Jetty during the
development time and for debugging.
Jetty as Servlet Container:
roma add web-jetty
Now configure a Run Task in Eclipse. This is needed only the first time:
1. Select the menu Run
Open Debug Dialog...
2. Select Java Application
3. Click on New button
4. Select in the Project field the blog project
Roma Meta Framework Hand Book - Rev. 481
Page 20 of 167
5. Insert in the Main class field the value org.mortbay.jetty.Server
6. Select the Arguments tab
7. Write src/jetty.xml in the Program arguments field
8. Write -Djetty.webapp=WebContent in the VM arguments field
9. Click Apply button and then Run
10. Now open the browser at this address: http://localhost:8080/roma/app
Every time you want to re-start the application go to Window -> Open Perspective ->
Debug, right click on the running instance of Jetty and select "Terminate and Relaunch". If
you want to debug your application, right click on the running instance of Jetty and select
"Terminate". Then click on the "Debug" button on the Eclipse Toolbar to start it in the
debugger.
Once running in your browser press the "Edit Blogs" button and you will see the Blog entity
automatically rendered by Roma.
The "Posts" field shows a list of posts. The "Add", "View", "Modify", "Remove" buttons
create and manipulate posts in the list. "Author", "Title", and "Name" fields are global for
the blog with the respective meaning.
Note that we have written no HTML code but our application it's web based and works
totally using Ajax technology. Furthermore anything is Internationalized (I18N) based on
the Locale setting of the browser connected (in the screenshot above is Italy).
Obviously you can change the graphic layout by:
changing the stylesheet file in src directory
create a custom Desktop
4.5 Adding persistence and CRUD to an application
In the previous section we have seen how to create an Ajaxed Web Application in short
time.
Now we need to add the persistence aspect so we can enrich the Blog application with
is another buzzword and it stands for: Create Read Update
Delete. These are the operations you often execute against your business objects.
The most of applications need to store information in persistent way. Very often the
repository is a Relational DBMS. With Roma doesn't matter the kind of DBMS selected or
the brand of DBMS since its Persistence Aspect uses the JDO 2.0 technology. JDO is a
standard to works with Objects in heterogeneous repositoties. It can be also an Object
Database such as Orient ODBMS.
Roma Meta Framework Hand Book - Rev. 481
Page 21 of 167
The JDO implementation bundled with Roma distribution is DataNucleus (that is the
, however supported by Roma as the module persistence-
jpox), the Reference Implementation of
. You can use DataNucleus with
Too much words...Let's add the Persistence Aspect to our application:
roma add persistence-datanucleus
Now Roma needs to know which classes will be treated as persistents. We must specify it in
the file package.jdo in the source domain package. In our example is
src/it.demo.blog.domain. Change the package.jdo file as follow:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE jdo PUBLIC
"-//Sun Microsystems, Inc.//DTD Java Data Objects Metadata 2.0//EN"
"jdo_2_0.dtd">
<jdo>
<package name="it.blog.domain">
<class name="Blog" detachable="true">
<field name="posts" default-fetch-group="true">
<collection element-type="Post" />
</field>
</class>
<class name="Post" detachable="true"/>
</package>
</jdo>
As you can see we specify the class of objects that Roma will place in the database.
Current release need to specify always the attribute detachable="true" foreach classes.
DataNucleus will auto-discover the class structure to gather fields information. The only
thing to specify is the embedded instance for collection and map types.
In the snippet above, we have declared that posts attribute is a collection and it contains
objects of type Post.
CRUDs in Roma are themselves POJO classes.
Roma's CRUD is divided in two parts:
Runtime library, some classes inside
roma-core library that handle CRUD events
Generated classes by the wizard "crud".
You can change the sources generated adding more properties, actions or changing the
default behaviour inherited by CRUDMain, CRUDSelect and CRUDInstance classes placed in
the runtime library.
At this point we can let to Roma the
for the Blog class. Generation
must be executed foreach domain classes we need a CRUD. Type this:
Roma Meta Framework Hand Book - Rev. 481
Page 22 of 167
roma crud it.demo.blog.domain.Blog
Now you can refresh the project on Eclipse IDE to see the new package where the CRUD
was generated (it.demo.blog.view.domain.blog). Here there are all CRUD classes
generated by the wizard.
We need to change the application flow to display the CRUD entry point when the user
presses the "Edit Blog" button.
Replace the old HomePage.java class with this one:
package it.demo.blog.view.domain;
@ViewClass(layout = "screen://body")
public class HomePage {
public HomePage() {
Screen screen = ObjectContext.getInstance().
getComponent(ScreenManager.class).getScreen("default-screen");
ObjectContext.getInstance().getComponent(ViewAspect.class).setScreen(screen);
}
@FlowAction(next=BlogMain.class)
public void editBlog() {}
}
As you can see we have changed only the content of FlowAction's "next" attribute. Now we
create a BlogMain instance. @FlowAction set as back object of the BlogMain this to allow
back operation and return to the HomePage instance.
Roma Controller checks always if the "next" instance inherit the BackHandler
interface. That interface handle the back operation. All CRUD entry points inherit
the CRUDMain class that implements the BackHandler interface.
Before to run the application you had to execute the "Persistence Compile" Ant
Task. This step is needed by DataNucleus to change the bytecode of classes to be
persistence capable. Fortunately is totally transparent for the developer
You can find the build.xml file in your Eclipse project. Right click on it and select
"Run As Ant Build". In the Eclipse Console Window you can see the DataNucleus
report of enhancement process. "BUILD SUCCESSFUL" means that Ant build
succeeds.
Run the application by clicking on the Play button of Eclipse. Now open the browser
at this address: http://localhost:8080/roma/app And clicking on the "Edit Blogs"
you'll see something like this:
1Remember to execute it at every change of your business classes.
Roma Meta Framework Hand Book - Rev. 481
Page 23 of 167
Figure 2.1: Blog's Crud
What confuse form! Let me explain a little bit the CRUD rendering. By default Roma
render all fields of objects unless you tell something different.
In our Blog example, the posts property in the Filter has not sense. You can change default
rendering specifying rules in a separated XML file. The file name must be equals to the
class, but with .xml extension. usually xml files are in the same directory of .java/.class
files.
So let's update the file it.demo.blog.view.domain.blog.BlogFilter.xml and specify the
visible="false" property for the view aspect of field posts, just as follow:
<?xml version="1.0" encoding="UTF-8"?>
<class xmlns="http://www.romaframework.org/xml/roma"
xmlns:xsd="http://www.w3.org/2001/XMLSchema-instance"
xsd:schemaLocation="http://www.romaframework.org/xml/roma
http://www.orientechnologies.com/roma/schema/roma.xsd">
<fields>
<field name="entity">
<aspects>
<view layout="expand" />
</aspects>
<class>
<fields>
<field name="posts">
<aspects>
<view visible="false" />
</aspects>
Roma Meta Framework Hand Book - Rev. 481
Page 24 of 167
</field>
</fields>
</class>
</field>
</fields>
</class>
Once you have saved the file above, you can see in the Eclipse Console Window the
following message:
18:00:40,044 INFO [SchemaClass] [SchemaClass] Reload entity BlogFilter
Roma catches file modification and reload it. So, without stop the application, click the
"Back" button and "Edit Posts" again. You'll see the form changed 2.2:
Figure 2.2: Customized blog's CRUD
Now let's play with the CRUD creating new blogs, update them, delete someone, and so
on; for more information about CRUD customization refer to the chapter
Roma Meta Framework Hand Book - Rev. 481
Page 25 of 167
5 The Meta-Framework concept
5.1 Aspects
Roma Meta-Framework architecture is based on Aspects: an Aspect represents an aspect of
the application, such as view or persistence. An Aspect is then implemented by one or
more Modules. The aspect is the concept upon which Roma implements the Meta-
Framework architecture: Roma Aspects are implemented as Java interfaces and using these
interfaces you can write your application without being aware of the underlying
implementation, so you can replace the current module that implements an Aspect with
another one that uses a different technology without re-writing the application logic.
In this chapter we present a quick overview of Roma Aspects, describing their purpose. In
the following chapters we will describe each Aspect in detail.
Roma Meta Framework Hand Book - Rev. 481
Page 26 of 167
5.1.1 Aspects Overview
Aspect name
Description
AuthenticationAspect
Is responsible of user authentication, with password encryption, group
and realm hierarchies etc.
FlowAspect
Handles the application flow
I18NAspect
Manages application localization
LoggingAspect
Is responsible of application logs
MonitoringAspect
Allows business objects to be monitored from outside the application
PersistenceAspect
Covers the persistence of objects. Its task is to allow object
manipulation in persistent way.
ReportingAspect
Allows to generate reports from POJOs
ServiceAspect
Exposes POJOs as services
SchedulerAspect
Allows to schedule events in Roma applications
ScriptingAspect
Adds scripting capabilities to Roma applicaitons
SemanticAspect
Generates semantic (Web 3.0) information from POJOs
SessionAspect
Handles user sessions
ViewAspect
Provides view functionalities to the application
WorkflowAspect
Adds workflow functionalities to the application
Roma Meta Framework Hand Book - Rev. 481
Page 27 of 167
5.2 Modules
Modules are components that provide functionalities to Roma applications. A Module can
implement one or more Aspects. In this chapter we present an overview of Roma modules
available in the official Roma distribution and that are supported by Roma development
group. Anyway the Meta-Framework approach or Roma allows everyone to develop a new
Roma Module and to plug it in Roma applications.
5.2.1 Modules Overview
Module name
Implemented
Aspects
Dependencies
Description
Admin
-
-
Provides basic administration functionalities,
like user profiling, application log and session
monitoring etc.
Chart-JFreeChart
-
-
Enriches ViewAspect and ReportingAspect
with the ability of rendering POJOs as charts.
This module is based on JfreeChart library.
Roma Meta Framework Hand Book - Rev. 481
Page 28 of 167
Core
Core
I18N
Flow
-
Is the core module of all Roma applications.
It contains Aspect interfaces, application
controller and other basic functionalities. All
Roma Modules depend on Core Module.
This module also contains basic
implementations of FlowAspect and
I18NAspect
Designer
-
View-Echo2
Allows to customize applications at runtime,
changing POJO configurations in respect of
enabled aspects.
ETL-XPath
-
-
Provides the ability to execute Spring XML
based procedures to import data in Roma
applications. This module is based on Spring
IoC and Reverspring.
Messaging
-
-
Adds mail and messaging functionalities to
Roma applications, with complete email GUI
and SMTP/POP3 support. This module is
based on JavaMail technology.
Monitoring-JMX
Monitoring
-
Adds monitoring functionalities to Roma
applications. This module is based on JMX
technology.
Monitoring-MX4J
Monitoring
-
Adds monitoring functionalities to Roma
applications. This module is based on MX4J
technology.
Persistence-
Datanucleus
Persistence
Persistence-
JDO
Provides persistence capabilities to the
application. This module is based on
DataNucleus technology.
Persistence-JDO
Persistence
-
This is an abstract JDO implementation of the
PersistenceAspect. Other modules, such as
Persistence-Datanucleus and Persistence-
JPOX are based on this Module.
Persistence-JPOX
Persistence
Persistence-
JDO
Provides persistence capabilities to the
application. This module is based on JPOX
technology.
Portal-Solo
-
-
Provides simple portal functionalities for
Roma web applications
Reporting-JR
Reporting
-
This is an implementation of ReportingAspect
based on JasperReports library.
Scheduler-Quartz
Scheduler
-
Adds to Roma applications the ability to
schedule events. This module is based on
Roma Meta Framework Hand Book - Rev. 481
Page 29 of 167
Quartz scheduler.
Scripting-Java6
Scripring
-
Adds scripting capabilities to Roma
applications. This module is based on Java6
Rhino JavaScript engine.
Semantic-Jena
Semantic
-
Allows to export POJOs as RDF feeds. This
module is being developed under the Romulus
Project, so it is not hosted in Roma
repository.
Service-CXF
Service
-
Exposes POJOs as web services. This module
is based on Apache CXF technology.
Users
-
Admin
Provides users authentication functionalities.
View-Echo2
View
Session
Web
Adds view capabilities to Roma applications,
rendering POJOs as Echo2 AJAX pages
View-HTML
View
Session
Web
Adds view capabilities to Roma applications,
rendering POJOs as HTML pages. This module
is being developed under the Romulus
Project, so it is not hosted in Roma
repository.
Web
View
-
This is an abstract implementation of the
ViewAspect based on HTTP. Web based
ViewAspect implementations such as View-
Echo2 and View-HTML rely on this module.
Workflow-POJO
Workflow
-
Adds basic workflow capabilities to the
application
Workflow Tevere
Engine
-
-
Adds complex workflow capabilities to the
application. This module is being externalized
as an independent project called TevereFlow.
Workflow Tevere
GUI
-
-
A web-based, AJAX GUI for Workflow Tevere
Engine. This module is being externalized as
an independent project called TevereFlow.
Roma Meta Framework Hand Book - Rev. 481
Page 30 of 167
5.3 Accessing to Aspects and Components
Roma allows to access to each registered component and aspect by ObjectContext
singleton class.
Get by class type. Convention wants each aspect's implementation is registered in
the IoC system with the name of the interface:
ObjectContext.getInstance().getComponent(ViewAspect.class).show(employee)
Get the component by the registered name:
ObjectContext.getInstance().getComponent("MyComponent")
Get the component in context. Useful for
transaction.
ObjectContext.getInstance().getContextComponent(PersistenceAspect.class).
updateObject(employee)
5.4 DDD Domain Driven Development
Using Roma allowa to place to the domain the center of the development.
To know more about DDD methodology take a look at
5.4.1 DDD Resources
5.5 Enrich you model using annotations
The Roma development is fully focused on domain. But since Java language is not enought
to express complex domain model you need to use an enriched one.
Roma provides annotations under the form of
Remember that on conflict
Below an example of the same annotation in Java and XML.
ContactInstance.java:
public class ContactInstance{
@ViewField(render = ViewConstants.RENDER_SELECT, selectionField = "entity.type")
private List<ContactType> types;
Roma Meta Framework Hand Book - Rev. 481
Page 31 of 167
}
ContactInstance.xml:
<?xml version="1.0"?>
<class>
<fields>
<field name="types">
<aspects>
<view render="select" selectionField="entity.type"/>
</aspects>
</field>
</fields>
</class>
5.5.1 Annotations table
Below the table of available annotations divided in Aspects.
Aspects
Classes
Fields (properties)
Actions (methods)
Core
View
Monitoring
Flow
I18N
Semantic
5.5.2 Java Annotations
Annotations
are
a
new
feature
of
Java
5
platform
"annotate" classes, attributes and methods with the following syntax:
@<Annotation Name>[(<attribute> = <value>*)]
Where the annotation name is such composited:
<AspectName>Class:
to annotate the class under the aspect <AspectName>
<AspectName>Field:
to annotate the field under the aspect <AspectName>
<AspectName>Action: to annotate the action under the aspect <AspectName>
Roma Meta Framework Hand Book - Rev. 481
Page 32 of 167
5.5.2.1 Use XML Annotation instead
Remember you can always use the
things separated.
5.5.2.2 Example
Below a complete example:
@ViewClass(render="popup")
@MonitoringClass(enabled=AnnotationConstants.TRUE)
class MyWindow{
@ViewAction(validate=AnnotationConstants.TRUE)
public void save()
{
saveAllInfoToDatabase();
}
@ViewField(label="Window position")
public int getPosition()
{
return 4;
}
@FlowAction(next="WizardStep1")
public void next()
{
}
@ViewField(label="Name of the window")
private String name;
}
5.5.3 XML Annotations
are
a
new
feature
of
Java
5
platform
"annotate" classes, attributes and methods with the following syntax:
Someone prefer to separate the code from the meta model. For this reason you can use
Xml Annotation instead of
. In the case Roma finds a
a Xml Annotation, the Xml Annotation wins.
A Xml Annotation must be written in a file with the same name of the class you want to
apply the annotation but with .xml suffix. Example: if you want to define a Xml Annotation
for the class Customer.java you had to define the Xml Annotation in a file called
Customer.xml. By convention the Xml Annotation file resides in the same package of Java
class, but Roma find it just if is in the domain class-path.
Writing the Xml Annotation assure it validates against the Xml Schema:
5.5.3.1 Example
Below a complete example:
<?xml version="1.0" encoding="UTF-8"?>
Roma Meta Framework Hand Book - Rev. 481
Page 33 of 167
<class xmlns="http://www.romaframework.org/xml/roma" xmlns:xsd="http://www.w3.org/
2001/XMLSchema-instance"
xsd:schemaLocation="http://www.romaframework.org/xml/roma
<actions>
<action name="search">
<aspects>
<view label="$default.refresh" />
</aspects>
</action>
<action name="send" />
<action name="forward" />
<action name="create">
<aspects>
<view visible="false" />
</aspects>
</action>
</actions>
</class>
5.6 Change the meta-model at run-time
You can change the meta-model at run-time in the following ways:
If you're in debug mode change the Java source and save it. Roma will catch the
changes and will reload it.
By changing the Xml Annotation and save the file. Roma will catch the changes and
will reload it.
Via APIs. Example:
ObjectContext.getInstance().setClassFeature( this, ViewAspect.class,
ViewClassFeatures.LABEL, "My playlist" );
ObjectContext.getInstance().setFieldFeature( this, ViewAspect.class,
"account", ViewActionFeatures.VISIBLE, false );
ObjectContext.getInstance().setActionFeature( this, ViewAspect.class,
"save", ViewActionFeatures.ENABLED, false );
Roma Meta Framework Hand Book - Rev. 481
Page 34 of 167
6 Console
is developing graphic plugins for Eclipse and Netbeans IDE. The
Eclipse plugin is planned for the begin of 2009.
Roma comes with a console tool able to interact with the developer. To invoke the
console:
·
In Windows systems open the "Prompt of commands" and type:
roma
·
In Linux/Unix systems open a shell and type:
roma.sh
Assure you have the roma distribution in your path or change the current directory to the
roma distribution before to type the command above. The result will be something like
this:
ROMA Framework CONSOLE v.1.0 [http://www.romaframework.org]
Please specify the wizard to use between the following wizards discovered in the
classpath:
- check [new]
- get [<variable-name>]
- set <variable-name> '<variable-value>'
- install [[new] <module-name> [<version-name>]]
- add <module-name> [-p<project-name>]
- create <project-type> <project-name> <src-root-package> [<project-path>]
- info [-p<project-name>]
- list
- switch <project-name> [<project-path>]
- update [-p<project-name>][<module> [<module-version>]]
- crud <domain-class> [<output-class>] [-p<project-name>]
Example: roma create web blog org.test.blog C:/temp
Roma Meta Framework Hand Book - Rev. 481
Page 35 of 167
6.1 Console create command
This command create a new project.
6.1.1 Syntax
Syntax: roma create <project-type> <project-name> <src-root-package> [<project-path>]
Where: <project-type>
is the type of project between types locally availables (see below)
<project-name>
is the name of project to create
<src-root-package> Is the root package for sources
<project-path>
is the path where to place the project scaffolding; if not specified, the current
path is taken. Optional
Project types are themselve modules installed under the modules directory. Currently the
project types that came with the official distribution are:
simple
Create a simple Java project
web
Create a Web Java project
webready
Create a Web Java project ready to be launched. It contains some modules in order to start
developing in a flash.
6.1.2 Usage
roma create webready blog com.mycompany.blog C:/temp
Creates a new project called "blog" of type webready under the directory
using the Java package com.mycompany.blog.
1.1
Roma Meta Framework Hand Book - Rev. 481
Page 36 of 167
6.2 Console info command
This command shows the information about the current project.
6.2.1 Syntax
Syntax: roma info [-p<project-name>]
Where: <project-name>
is the name of project to create. Optional
6.2.2 Usage
roma info
Shows the information about current project.
roma info -pdemo
Shows the information about the "demo" project.
6.3 Console list command
This command displays all the project configured in Roma. This command reads the file
placed under $ROMA_HOME/config/projects.xml. Feel free to change it by hand, but
respects the XML formatting.
6.3.1 Syntax
Syntax: roma list
6.3.2 Usage
roma list
Displays all projects configured.
Roma Meta Framework Hand Book - Rev. 481
Page 37 of 167
6.4 Console switch command
This command switch the current project to another one. The project to set as current can
be already configured or not. If it's already configured you can just specify the name of the
project to switch, otherwise the command needs the path of the project.
Use the switch command to change a project path.
6.4.1 Syntax
Syntax: roma switch <project-name> [<project-path>]
Where: <project-name>
is the name of project to create
<project-path>
is the path where to place the project scaffolding; if not specified, the current
path is taken. Optional
6.4.2 Usage
roma switch demo
Switch to the 'demo' project.
roma switch blog C:/temp/blog
Switch to the 'blog' project located under
directory. If the project is already
configured it will be updated with the new path, otherwise a new entry will be created.
6.5 Console get command
This command returns one or all configuration values.
6.5.1 Syntax
Syntax: roma get [<variable-name>]
Where: <variable-name>
is the name the variable. Optional
6.5.2 Usage
roma get
Displays all the configured variables.
roma get author
Displays the author variable.
Roma Meta Framework Hand Book - Rev. 481
Page 38 of 167
6.6 Console set command
This command set the value of a variable.
6.6.1 Syntax
Syntax: roma set <variable-name> '<variable-value>'
Where: <variable-name>
is the name the variable
<variable-value>
is the value of the variable
6.6.2 Usage
roma set author 'Luke Skywalker (luke.skywalker@starwars.com)'
Set the author variable to "Luke Skywalker (
generated code will contain such author in JavaDoc comments.
6.7 Console add command
This command adds a module in a user project. If no project is specified the current will be
taken.
6.7.1 Syntax
Syntax: roma add [[<module-name>] [-p<project-name>]]
Where: <module-name>
is the name the module to add. Optional
<project-name>
is the name of the configured project. Optional
6.7.2 Usage
roma add
Displays all the modules installed.
roma add web-jetty
Add the module web-jetty to the current project.
roma add persistence-datanucleus -pblog
Add the persistence-datanucleus module in the project configured as "blog".
Roma Meta Framework Hand Book - Rev. 481
Page 39 of 167
6.8 Console crud command
in a user project. If no project is specified the current will
be taken. Roma will generate a set of files all under the package called as <application-
package>.view.<domain-class> unless you specify the <output-class> parameter.
6.8.1 Syntax
Syntax: roma crud <domain-class> [<output-class>] [-p<project-name>]
Where: <domain-class>
the domain class where to generate the CRUD
<output-class>
the package where to place classes. By default is <application-
package>.view.<domain-class>
<project-name>
is the name of the configured project. Optional
6.8.2 Usage
roma crud org.romaframework.blog.domain.Blog
Generates the CRUD classes for the domain class Blog.
6.9 Console check command
This command checks for new version of installed modules. It will search in all the
configured repositories placed under $ROMA_HOME/config/repositories.xml file.
6.9.1 Syntax
Syntax: roma check [new]
Where: new
Check for new modules
6.9.2 Usage
roma check
Check for a new version of all installed modules
roma check new
Check for all the modules not installed in the local distribution.
Roma Meta Framework Hand Book - Rev. 481
Page 40 of 167
6.10 Console install command
This command install a module in the local distribution.
6.10.1 Syntax
Syntax: roma install [[new] <module-name> [<version-name>]]
Where: new
Install as a new module
<module-name>
Name of the module to install
<version-name>
Version to install. Optional, default is the latest one
6.10.2 Usage
roma install
Install the latest version of all modules.
roma install scheduler-quartz
Install the latest version of "scheduler-quartz" module.
roma install scheduler-quartz 1.1
Install the version 1.1 of "scheduler-quartz" module.
roma install new view-echo2
Install the latest version of "view-echo2" module never installed before.
roma install new scheduler-quartz 1.1
Install the version 1.1 of "view-echo2" module never installed before.
Roma Meta Framework Hand Book - Rev. 481
Page 41 of 167
6.11 Console update command
This command update a Roma project with a new module installed locally.
6.11.1 Syntax
Syntax: roma update [-p<project-name>][<module> [<module-version>]]
Where: <project-name>
is the name of the configured project. Optional
<module>
Name of the module to update
<module-version> Module version to update in the project
6.11.2 Usage
roma update persistence-jpox
Updates the module 'persistence-jpox' of the current project to the version available
locally.
roma update admin 1.0.3
Updates the module admin of the current project to the version 1.0.3.
roma install scheduler-quartz 1.1
Install the version 1.1 of "scheduler-quartz" module.
roma install new view-echo2
Install the latest version of "view-echo2" module never installed before.
roma install new scheduler-quartz 1.1
Install the version 1.1 of "view-echo2" module never installed before.
Roma Meta Framework Hand Book - Rev. 481
Page 42 of 167
6.12 Console JSP command
This command generates Java Server Pages (JSP) to customize how a POJO is rendered. It
works along with the View-HTML module (not the Echo2). The generated JSP will have all
class members expanded. It uses the View-HTML module JSP tag library.
This is a 3
rd
party contribution from the
6.12.1 Syntax
Syntax: roma jsp <domain-class>|* [-p<project-name>]
Where: <project-name>
is the name of the configured project. Optional
<domain-class>
he domain class where to generate the JSP. To generate JSP for all the classes
under a such package use <package>.*
6.12.2 Usage
roma jsp org.test.domain.Airport
Generates the JSP called Airport.jsp under the directory <project-
path>/WebContent/dynamic/base/view/Airport.jsp.
roma jsp org.test.domain.*
As above, but it generates a JSP foreach class found in the package org.test.domain.
Roma Meta Framework Hand Book - Rev. 481
Page 43 of 167
7 CRUD
CRUD stands for Create Read Update Delete and represents the very common operations
you can execute to entities. Many pieces of applications are composed by CRUD forms
where you can handle entities.
Roma Framework supports CRUD natively, allowing fast development of CRUD against
domain classes.
To explain the CRUD creation and customization we are going to use a bank application
domain.
package
org.romaframework.test.presentation.domain;
import
java.util.Date;
public
class
Person {
protected
String
name
;
protected
Date
birthDate
;
public
Person
() {
super
();
}
public
Person
(String name, Date birthDate) {
super
();
this
.
name
= name;
this
.
birthDate
= birthDate;
}
public
String
getName
() {
return
name
;
}
public
void
setName
(String name) {
this
.
name
= name;
}
public
Date
getBirthDate
() {
return
birthDate
;
}
public
void
setBirthDate
(Date birthDate) {
this
.
birthDate
= birthDate;
}
}
package
org.romaframework.test.presentation.domain;
import
java.util.Date;
import
java.util.List;
public
class
BankAccount {
Person
owner
;
List<BankTransaction>
transactions
;
Integer
currentAmmount
;
Date
created
;
Roma Meta Framework Hand Book - Rev. 481
Page 44 of 167
public
Integer
getCurrentAmmount
() {
return
currentAmmount
;
}
public
void
setCurrentAmmount
(Integer currentAmmount) {
this
.
currentAmmount
= currentAmmount;
}
public
Date
getCreated
() {
return
created
;
}
public
void
setCreated
(Date opened) {
this
.
created
= opened;
}
public
Person
getOwner
() {
return
owner
;
}
public
void
setOwner
(Person owner) {
this
.
owner
= owner;
}
public
List<BankTransaction>
getTransactions
() {
return
transactions
;
}
public
void
setTransactions
(List<BankTransaction> transactions) {
this
.
transactions
= transactions;
}
}
package
org.romaframework.test.presentation.domain;
import
java.util.Date;
import
org.romaframework.module.admin.domain.Info;
public
class
BankTransaction {
protected
Date
when
;
protected
Float
ammount
;
protected
String
cause
;
@ViewField(visible = false)
protected
BankAccount
account
;
protected
Info
type
;
public
Info
getType
() {
return
type
;
}
public
void
setType
(Info type) {
this
.
type
= type;
}
public
BankAccount
getAccount
() {
return
account
;
}
public
void
setAccount
(BankAccount account) {
Roma Meta Framework Hand Book - Rev. 481
Page 45 of 167
this
.
account
= account;
}
public
Date
getWhen
() {
return
when
;
}
public
void
setWhen
(Date when) {
this
.
when
= when;
}
public
Float
getAmmount
() {
return
ammount
;
}
public
void
setAmmount
(Float ammount) {
this
.
ammount
= ammount;
}
public
String
getCause
() {
return
cause
;
}
public
void
setCause
(String cause) {
this
.
cause
= cause;
}
}
Best practice: Avoid to use primitives java types for fields (int, float, etc..) because
they can't be null. Even though Roma works well with literals, the CRUDs will search
using the
. It uses the NULL values to exclude fields in the search. So
if you need to generate CRUD against domain entity classes use the Object types such
as Integer, Float, etc.
Best practice: Avoid to assign values in the object construction (constructors and/or
field declaration). Roma create an empty object as filter in the CRUD page by calling
the empty constructor of domain entity class. If you initialize some fields at this point
the CRUD filter will result not empty (as usual) but with the field already filled.
To auto-generate a CRUD for a domain class you can use the Roma console. Below an
example of how to generate CRUD for BankAccount class.
> ./roma.sh crud org.romaframework.test.presentation.domain.BankAccount
This will generate in your project the following Java source files.
Roma Meta Framework Hand Book - Rev. 481
Page 46 of 167
BankAccountMain.java: I
s the "main" class of the CRUD. Is composed by a filter of type
BankAccountFilter and a result of type List. Executing the search the filter will be used to
filter persistent instances and returning the result in "result" property (of type List).
BankAccountFilter.java:
Is the class that handle the filter that read the search method.
BankAccountInstance.java:
Is the class that handle creation, updating and reading of
selected instances.
BankAccountListable.java:
Is showed inside the result table.
BankAccountSelect.java:
As for BankAccountMain, but is showed in a popup and
contains the additional actions: Select and Cancel.
The BankAccountFilter, BankAccountInstance, BankAccountListable are wrapper of the
class BankAccount (based on the Composed Entity pattern), so if you add or remove a
field from a domain object you don't need to generate the CRUD again
To display the entrypoint of your brand new CRUD you should display a BankAccountMain
instance, using the flow to call the CRUD-Main.
@FlowAction
(
next
= BankAccountMain.
class
)
Roma Meta Framework Hand Book - Rev. 481
Page 47 of 167
CRUDMain
BankAccountMain
ComposedEntityInstance
<
BankAccount
>
CRUDInstance
CRUDSelect
BankAccountInstance
BankAccountListable
BankAccountFilter
Repository
BankAccountRepository
Delegates all database access
*
1
1
1
public
void
showBankAccountManager
() {}
This piece of code allow to choose the Posts to insert in the collection
BestPostsOfTheYear.posts.
7.1 CRUD Working
By default the CRUD entry point form (CRUDMain class) is composed by:
The Filter, an instance of the generated VankAccountFilter class.
The Result, as a collection of instances of generated class BankAccountListable
class.
The filter is for search purpose: every filled fields of the filter instance will acts as filter
condition on the search query. Now all query conditions use the AND operator, but we're
working on it. This is a simple implementation of Query By Example pattern.
For example if I fill the currentAmmount field with the value "100" and then click Search,
the CRUDMain class will compose the query in JDOQL: currentAmmount == '100'.
You can express complex queries using
directly, but the Query By Example
satisfy the most common needs: execute a query specifying filters on some fields. Using
the Query By Example you don't have to write JDOQL/SQL code.
Result contains the query result filled from the execution of the method
CRUDMain.search() method invoked by clicking the "Search" button.
BlogFilter, as the other classes generated by the wizard, extends the class
ComposedInstance<BankAccount>; Roma handles the BankAccountFilter as a class that
extends Blog, but using the Composition pattern.
Why this? Because in this way BankAccount objects can be retrieved and stored in the
database without conversion. If BankAccountFilter inherits BankAccount directly, the
persistence layer recognize BankAccountFilter class as Non Persistent.
Instead Roma handles everything transparently by retrieving and storing the instance
contained inside the class extends ComposedInstance.
7.2 Customize a CRUD
7.2.1 Change the GUI
From the initial generation of the BankAccount CRUD we get this result:
Roma Meta Framework Hand Book - Rev. 481
Page 48 of 167
First of all we want to remove the transactions in the filter, so we open the
BankAccountFilter.xml and we modify it obtaining:
<?
xml
version
=
"1.0"
encoding
=
"UTF-8"
?>
<
class
xmlns
=
"http://www.romaframework.org/xml/roma"
xmlns:xsd
=
"http://www.w3.org/2001/XMLSchema-instance"
xsd:schemaLocation
=
"http://www.romaframework.org/xml/roma
http://www.romaframework.org/schema/roma.xsd"
>
<
fields
>
<
field
name
=
"entity"
>
<
aspects
>
<
view
layout
=
"expand"
/>
</
aspects
>
<
class
>
<
fields
>
<
field
name
=
"transactions"
>
<
aspects
>
<
view
visible
=
"false"
/>
</
aspects
>
</
field
>
</
fields
>
</
class
>
</
field
>
</
fields
>
</
class
>
Then we modify the BankAccountListable.xml to set change the fields order and hide the
transactions column:
<?
xml
version
=
"1.0"
encoding
=
"UTF-8"
?>
<
class
xmlns
=
"http://www.romaframework.org/xml/roma"
xmlns:xsd
=
"http://www.w3.org/2001/XMLSchema-instance"
xsd:schemaLocation
=
"http://www.romaframework.org/xml/roma
http://www.romaframework.org/schema/roma.xsd"
>
<
fields
>
<
field
name
=
"entity"
>
<
aspects
>
<
view
layout
=
"expand"
/>
</
aspects
>
<
class
>
<
aspects
>
<
view
explicitElements
=
"true"
></
view
>
</
aspects
>
<
fields
>
<
field
name
=
"owner"
></
field
>
Roma Meta Framework Hand Book - Rev. 481
Page 49 of 167
Figure 1: Initial CRUD
<
field
name
=
"created"
></
field
>
<
field
name
=
"currentAmmount"
></
field
>
</
fields
>
</
class
>
</
field
>
</
fields
>
</
class
>
7.2.2 Adding other search conditions
In our example we have in the filter the field currentAmmount, and the basic crud uses it
to generate the condition currentAmmount == '$inserted_value'; this kind of search isn't
usefull for the bankAccounts object, it would be better to have the a condition like
currentAmmount >= '$inserted_value'.
So we modify the BankAccountFilter adding two properties, the ammountLessThan and
ammountMoreThan:
package
org.romaframework.test.presentation.view.domain.bankaccount;
import
org.romaframework.aspect.view.annotation.ViewClass;
import
org.romaframework.core.entity.ComposedEntityInstance;
import
org.romaframework.test.presentation.domain.BankAccount;
@ViewClass(
entity
= BankAccount.class,
label
= "")
public
class
BankAccountFilter extends ComposedEntityInstance<BankAccount> {
private
Float
ammountMoreThan
;
private
Float
ammountLessThan
;
public
BankAccountFilter
() {
this
(new
BankAccount
());
}
public
BankAccountFilter
(BankAccount iBankAccount) {
super
(iBankAccount);
}
public Float
getAmmountMoreThan
() {
return
this
.ammountMoreThan;
}
public
void
setAmmountMoreThan
(Float ammountMoreThan) {
this.
ammountMoreThan
= ammountMoreThan;
}
public
Float
getAmmountLessThan
() {
return
ammountLessThan
;
}
public
void
setAmmountLessThan
(Float ammountLessThan) {
this
.
ammountLessThan
= ammountLessThan;
}
}
We hide the currentAmmount that is no more used as filter condition changing the XML and
finally, we override the search method of the BankAccountMain CRUD:
...
<
field
name
=
"currentAmmount"
>
Roma Meta Framework Hand Book - Rev. 481
Page 50 of 167
<
aspects
>
<
view
visible
=
"false"
/>
</
aspects
>
<
/field
>
...
@Override
public
void
search
() {
QueryByFilter query =
new
QueryByFilter
(BankAccount.
class
);
BankAccountFilter filter =
getFilter
();
if
(filter.
getAmmountMoreThan
() !=
null
) {
query.
addItem
(
"currentAmmount"
, QueryByFilter.
FIELD_MAJOR_EQUALS
,
filter.
getAmmountMoreThan
());
}
if
(filter.
getAmmountLessThan
() !=
null
) {
query.
addItem
(
"currentAmmount"
,
QueryByFilter.
FIELD_MINOR_EQUALS
,
filter.
getAmmountLessThan
());
}
super
.
searchByExample
(query);
}
After this changhes to the code we get this result:
7.2.3 Order the result
Than if you want to order the result you can add to the previous code this line of code
query.
addOrder
(
"created"
, QueryByFilter.
ORDER_ASC
);
So the result will be ordered by the creation date.
7.2.4 Adding pre and post operations events
Sometimes we need to perform a set of operations when we are going to create, update,
view or save the object, we have all we need to intercept this events in the
BankAccountInstance class:
Roma Meta Framework Hand Book - Rev. 481
Page 51 of 167
Figure 2: Customized CRUD
@Override
public
void
onCreate
() {
}
@Override
public
void
onRead
() {
}
@Override
public
void
onUpdate
() {
}
public
void
validate
()
throws
ValidationException {
}
public
void
save
() {
super
.
save
();
}
as you can see we also have a method validate, that should be used only if the normal
validation through annotations cannot reach the target because we need a really complex
validation condition.
First of all we will add the date field to the BankAccountInstance:
protected
Date
lastUpdate
;
public
Date
getLastUpdate
() {
return
lastUpdate
;
}
public
void
setLastUpdate
(Date lastUpdate) {
this
.
lastUpdate
= lastUpdate;
}
Reminder: we don't need to generate the crud again after this change
Then we change the bankAccountInstance as follows:
private
static
final
String
VALIDATION_ERROR_MESSAGE
=
"Last update date
cannot be before creation date"
;
@Override
public
void
onCreate
() {
entity
.
setCreated
(
new
Date
());
}
@Override
public
void
onRead
() {
}
@Override
public
void
onUpdate
() {
entity
.
setLastUpdate
(
new
Date
());
Roma Meta Framework Hand Book - Rev. 481
Page 52 of 167
}
public
void
validate
()
throws
ValidationException {
if
(
getMode
() == CRUDInstance.
MODE_CREATE
)
return
;
if
(
entity
.
getCreated
().
compareTo
(
entity
.
getLastUpdate
()) > 0) {
throw
new
ValidationException
(
this
,
"lastUpdate"
,
VALIDATION_ERROR_MESSAGE
,
null
);
}
}
public
void
save
() {
if
(
entity
.
getTransactions
() !=
null
) {
for
(BankTransaction transaction :
entity
.
getTransactions
()) {
transaction.
setAccount
(
entity
);
}
}
super
.
save
();
}
As you can see when we create or update an object we set the creation and update date,
during the save we test for the upadate date major than the creation and we set on all the
transactions added the currentBankAccount.
Finally we change the BankAccountInstance.xml to render this fields as label, so the users
cannot change them:
<?
xml
version
=
"1.0"
encoding
=
"UTF-8"
?>
<
class
xmlns
=
"http://www.romaframework.org/xml/roma"
xmlns:xsd
=
"http://www.w3.org/2001/XMLSchema-instance"
xsd:schemaLocation
=
"http://www.romaframework.org/xml/roma
http://www.romaframework.org/schema/roma.xsd"
>
<
fields
>
<
field
name
=
"entity"
>
<
class
>
<
aspects
>
<
view
explicitElements
=
"true"
/>
</
aspects
>
<
fields
>
<
field
name
=
"owner"
></
field
>
<
field
name
=
"created"
>
<
aspects
>
<
view
render
=
"label"
/>
</
aspects
>
</
field
>
<
field
name
=
"lastUpdate"
>
<
aspects
>
<
view
render
=
"label"
/>
</
aspects
>
</
field
>
<
field
name
=
"currentAmmount"
>
</
field
>
<
field
name
=
"transactions"
>
<
aspects
>
<
view
render
=
"table"
/>
</
aspects
>
</
field
>
</
fields
>
</
class
>
</
field
>
</
fields
>
</
class
>
Roma Meta Framework Hand Book - Rev. 481
Page 53 of 167
7.2.5 How to get different CRUDs
Sometime you may need to define different GUI for the management of Object, so what
happen if you need to CRUD of the same object type but using different instance, listable
or filter class? Or how can I have on the same crud a different instance class for creation
and modification?
Best practice: Don't create a new CRUD for each extension but extend existent CRUD in
order to inherit CRUD customizations.
In this case you all you need to do is to define your own object and override the CRUDMain
constructor, so we added a constructor to BankAccountMain:
public
BankAccountMain
(Class<?
extends
ComposedEntity<?>> listClass, Class<?>
createClass, Class<?> readClass, Class<?> editClass) {
super
(listClass, createClass, BankAccountInstanceForVisualization.
class
,
editClass);
}
As you can this contructor accept the class to be used as listable, for creation, read and
update, so you can replace, in the example above we changed the visualization class.
7.2.6 CRUDHelper
If you need advanced controll and manage of a CRUD there is the CRUDHelper Class, there
are three usefull method to show and bind a crud with a POJO:
public
static
Bindable
show
(Bindable iSelectObj, Object iSourceObject, String
iSourceFieldName){}
public
static
<T
extends
Bindable> T
show
(Class<T> iClass, Object iSourceObject,
String iSourceFieldName, Object iCaller) {}
public
static
<T
extends
Bindable> T
show
(Class<T> iClass, Object iSourceObject,
String iSourceFieldName) {}
You can use this methods to bind a field to a CRUDSelect object in this way:
public
class
BankAccountMigration {
private
ArrayList<BankAccount> accounts;
public void
selectAAccountForMigration
() {
CRUDHelper.
show
(BankAccountSelect.class, this, "accounts");
}
}
or if you need a to initialize a CRUDSelect with some value on the filter you can use the
other version of the method:
Roma Meta Framework Hand Book - Rev. 481
Page 54 of 167
public
class
BankAccountMigration {
private
ArrayList<BankAccount> accounts;
public
void
selectAAccountForMigration
() {
BankAccountSelect select =
new
BankAccountSelect
();
select.
getFilter
().
setAmmountMoreThan
(300000);
CRUDHelper.
show
(select, this, "accounts");
}
}
Roma Meta Framework Hand Book - Rev. 481
Page 55 of 167
8 Conventions
8.1 Extension by Composition
The best way to extend a domain class is not to inherit it, but using the Composite
Pattern. Roma Framework provide the interface ComposedEntity< T > and its extensions
as:
EntityPage< T >
CRUDInstance< T >
Below a common use case: extend domain Profile class adding the confirmPassword
property useful to make a double check on password input. confirmPassword must not
reside in the domain class since is concerned to the presentation only aspect!
Example:
public class Profile {
private String name;
@ViewField( render = "password" )
private String password;
}
This was the base entity class and below the extension using the composition:
@ViewClass( entity=Profile.class )
public class ProfileInstance extends ComposedInstance<Profile> implements
CustomValidation {
private String confirmPassword;
public void validate() {
if( !confirmPassword.equals( entity.getPassword() ) )
throw new ValidationException( this, "confirmPassword", null );
}
}
Roma will treat the ProfileInstance class as a class that extends the Profile class.
Roma Meta Framework Hand Book - Rev. 481
Page 56 of 167
8.1.1 Advantages
The entity object is passed among layers using the ValueObject pattern
No cloning
Roma Meta Framework Hand Book - Rev. 481
Page 57 of 167
ComposedEntityInstance
<Employee>
EmployeeFilter
Employee
EmployeeFilter
Classic Inheritance
Extension by Composition
Not works very well with some
frameworks such as JDO and
Hibernate: you need to use the
class declared in the ORMapping
tool and not its extension.
All Employee fields and actions
are merged with Employee ones.
You can override fields, actions
and events just redefine it in the
EmployeeFilter class
The object contained is in the
field called "entity".
8.2 Override default behaviour
The Roma approach "Convention over Configuration" allows to save much time on
development. However often you need to override the default behaviour. That's why you
can write some callbacks or intercept and override an events. Event definition
All events in Roma must have the following syntax:
public void on<Field|Action|Event>[<Operation>](){
...
}
Where:
Field/Action/Event is the name of the field/action/event to catch the event.
Operation is optional and want to specify the associate operation to catch. Usually
is mandatory only for Collection to intercept single operations.
8.2.1 Predefined Events
8.2.1.1 Callback onShow()
You can write a callback called by Roma before an object is displayed. This is specially
useful for objects reused more times, so constructor is not called after the first time.
To write the callback just implement the ViewCallback interface and the onShow()
method. Example:
public class CarForm implements ViewCallback {
public void onShow(){
// SHOW A MODAL POPUP TO CONTINUE
ObjectContext.getInstance().getComponent( ViewAspect.class ).
show( new MessageOk( "message", "Warning!", null,
"Click OK to continue" ) );
}
}
8.2.1.2 Callback onDispose()
You can write a callback called by Roma when an object is not more visible. This is
specially useful to free resources you don't need anymore.
To write the callback just implement the ViewCallback interface and the onDispose()
method. Example:
public class CarForm implements ViewCallback {
public void onDispose(){
socket.close();
}
}
Roma Meta Framework Hand Book - Rev. 481
Page 58 of 167
8.2.2 Override Collection behaviour (List and Tables)
Roma renders Collection fields as Lists or Tables provided by View, Add, Remove and
Update buttons to work with element contained inside of it.
If you want to override default management you had to write an event within the
Operation to override. Example:
public class CarForm {
private Set<Person> owners;
public void onOwnersAdd(){
// SHOW THE CRUD SELECT INSTEAD TO CREATE A NEW INSTANCE
CRUDHelper.show( PersonSelect.class, this, "owners" );
}
}
The code above shows the Selection CRUD of Person instances and bind the user selection
(if any) to current class (this), in the field owners.
For any Collections you can override the default behavior by defining one or all these
methods:
on<Field>View()
on<Field>Add()
on<Field>Remove()
on<Field>Edit()
Roma Meta Framework Hand Book - Rev. 481
Page 59 of 167
9 Best Practices
9.1 Separate domain classes from presentation classes
It's a really good practice to divide classes in own aspect-package. A common use case is to
place the REAL domain class in <application-package>.domain and presentation classes in
<application-package>.view.domain.
<application-package>.domain should contain basic domain classes avoiding to dirty with
other concerns. Usually that classes will be stored also in database.
Example:
public class Profile {
private String name;
@ViewField( visible = AnnotationConstants.FALSE )
private City city;
}
@ViewClass( entity=Profile.class )
public class ProfileInstance extends ComposedInstance<Profile> implements
ViewCallback {
// OMITTED GETTER AND SETTER, IN YOUR APP WRITE THEIR!
@ViewField( selectField = "entity.city", render = "select" )
private City[] cities;
public ProfileInstance(){
cities =
ObjectContext.getInstance().getComponent( PersistentAspect.class ).query( new
QueryByExample( City.class, null ) );
}
}
ProfileInstance extends the Profile class by
component with all cities to select. Selection will be bound to real city property (contained
in entity property of ProfileInstance, see ComposedInstance.java).
In this way presentation concerns are seperated from others.
9.2 Dirty approach: dirty you hands when required
Roma wants cover the most common use cases. It's utopian to imagine covering all user
requirements since they are so many and frameworks can be so much differents between
their.
So if you need to access directly to the tool and framework in the behind you had to know
that you can do it. Just remember that piece of code will be not portable across
implementation when, and if, you'll decide to migrate to another one.
Roma Meta Framework Hand Book - Rev. 481
Page 60 of 167
Roma Meta Framework Hand Book - Rev. 481
Page 61 of 167
10 Controller
Roma binds the POJO directly to the form generated. The relationship is 1-1: if you change
the content of a field in the browser, it will be updated in you Java object and viceversa.
When you push any button, the action associated will be executed.
Fast to write, easy to debug, simple to handle!
Roma Meta Framework Hand Book - Rev. 481
Page 62 of 167
public class Customer{
private String name;
private String surname;
private String city;
private String web;
private String notes;
public void ok(){}
public void cancel(){}
public void print(){}
}
10.1 Controller in action
10.2 Field transparent binding
Roma controller acts between Forms and POJOs. Every time the user change some field
values Roma binds changes to the POJO. This usually happens before an actions is called.
You can avoid to make automatic binding by setting the "bind" annotation to false (use
Java/Xml annotation):
@ViewAction(bind=AnnotationConstants.FALSE)
public void reload(){
...
}
If you change some field values of your POJO you had to tell it to Roma in order to refresh
Roma Meta Framework Hand Book - Rev. 481
Page 63 of 167
Controller
Invoking
"OK"
Action
POJO
Bind changed
form fields to the
POJO
Call ok() method
against the
POJO
@FlowAction(next=HomePage.class)
public void ok(){
sendMessageToRemoteService();
}
@ViewField(required=true, min=2)
private String name;
public void validate(){
if( name == null ||
name.trim().length() == 0){
throw new ValidationException(
this, "name",
"Please insert the name!");
}
}
Validate
POJO's rules
+ validate()
method if any
HomePage.java
the updated values on the form when the Controller receives the control again. Use this:
public void reload(){
name = "";
ObjectContext.getInstance().fieldChanged(this, "name");
}
Roma Meta Framework Hand Book - Rev. 481
Page 64 of 167
11 View Aspect
View aspect has the difficult mission to provide a GUI (Graphical User Interface) to the
application. Roma can be used to build any kind of application. However most of users use
Roma as a RAD to build Web Applications.
View aspect mainly aims to render POJOs automatically, without the need to explicitly
define GUIs. Obviously you can override default behaviour by enhancing the class model
11.1 How Roma renders POJOs
Roma can render each POJO automagically. How it works? It's very easy:
Each fields (or Java properties) are rendered basis on their nature. For example
Date properties as Calendar, String as Text Fields, etc.
Each actions (or Java public-void methods) are rendered as links.
You have 1-1 relationship between your POJO and your GUI.
to place graphical components in the right place. By
default each form is divided in two areas: "fields" and "actions". If exist custom areas are
displayed after the default one, but you can change the order.
Roma Meta Framework Hand Book - Rev. 481
Page 65 of 167
main:COLUMN
default:GRID(4)
notes:COLUMN
actions:ROW
Ok
Cancel
Print
Name
City
Zion's citizen
Notes
Web
Surname
Luca
Garulli
Luca
zioncity
11.2 Area concept
To have a form layout really portable across technologies and frameworks we can't use
HTML to define the layout neither the Swing or the SWT way. We need a new generic way
to tell to Roma the aspect our form should be have.
Areas aim to divide your form in multiple parts. Each one must describe the way it place
the component: the "area rendering mode". By default is the placeholder, namely an
area type that replace itself with the component rendered (and only one). You can use all
the modes between the supported ones:
Area Rendering
Mode
Component
s min-max
Behaviour Description
Placeholder
1
Replace the
current
component
The Default. Similar to cell, but on creation is empty.
<area name="foo" />
Cell
1
Replace the
current
component
As the Placeholder, but a empty component is created.
<area name="top_dx" type="cell" />
Column
1-N
Add the
component
to the
bottom
Place the components vertically as in a column.
<area name="main" type="column" />
Row
1-N
Add the
component
to the right
Place the components horizontally as in a row.
<area name="actions" type="row" />
Grid
1-N
Add the
component
to the right
until
column size
is reached,
then in a
new row
Place the components in a grid. The number of
columns are taken by the "size" attribute.
<area name="fields" type="grid" size="4" />
Areas only describe the layout form. To handle the presentation aspect much deeper you
need to work with the View Aspect implementation in the behind. If you're using Echo2
module you had to work with the Xml stylesheet files contained under the package <your-
apppackage>.view.style.
Roma team choosen to not generalize features like component width, heights, colors, etc.
since they are so many and so much technology-related that it's much simpler to work
directly with the View Aspect implementation way it offers.
11.3 Note: Remember that your application will be portable across technologies and
Roma Meta Framework Hand Book - Rev. 481
Page 66 of 167
frameworks. It can run as Web Application or as Swing Desktop application. But GUI
details will be lost and need to be translated in the technology you want to use!
11.4 Create your form layout
Starting from release 1.0rc3 Roma allows to specify custom form layout in easy way by
To define the form layout write the areas in a file called <Class>.xml where Class is the
class name you want change the default layout. When Roma try to discover the layout to
use, it follows the class inheritance. So you can create form layouts in super-classes and all
extensions will use it.
Under the package domain of your application you can find the Object.xml file. Since
Object is the base class of all classes in Java, it will be used if sub-classes doesn't declare a
layout form. By default Object.xml contains:
<?xml version="1.0" encoding="UTF-8"?>
<class xmlns="http://www.romaframework.org/xml/roma" xmlns:xsd="http://www.w3.org/
2001/XMLSchema-instance"
xsd:schemaLocation="http://www.romaframework.org/xml/roma
<aspects>
<view>
<form>
<area name="main" type="column">
<area name="title" />
<area name="fields" type="grid" size="2" />
<area name="actions" type="row" />
</area>
</form>
</view>
</aspects>
</class>
This is the explanation:
main: sub-areas will be placed in vertical ("column" mode)
fields: 2 columns: label + field
actions: will be placed in horizontal ("row" mode)
11.4.1 Fields area
where the fields of a POJO are placed.
Object.xml contains the definition of the "fields"
as a grid component. You can
specify how many columns is composed the grid to optimize the layout.
For each field are always rendered two graphical objects: the label and the field content.
Roma Meta Framework Hand Book - Rev. 481
Page 67 of 167
If you define an empty label it will be not displayed and only the field content will.
The field order is specified by
@CoreClass( orderFields = "name surname city" )
11.4.2 Actions area
where the actions of a POJO are placed.
The order followed is expressed in
orderActions:
@ViewClass( orderActions = "ok cancel print" )
11.5 Screen and Area concepts
Roma renders POJO inside a screen. A screen is a set of
. In this way you can compose very complex GUI playing with screens
and form layouts.
By convention POJO are rendered always in the last screen
11.6 Configurable Screens
Starting from v. 0.9.9 Roma allows to use screens configured via XML. First of all assure
your applicationContext-core.xml file contains the following services:
<bean id="ScreenManager"
class="org.romaframework.aspect.view.echo2.screen.Echo2ScreenManager"
singleton="true"/>
<bean id="ScreenConfigurationLoader"
class="org.romaframework.aspect.view.screen.config.ScreenConfigurationLoader"
singleton="true"/>
By convention, place you screen files under [you package].view.domain.screen. However
Roma will search it inside all configured domains packages.
Example:
default-desktop.xml:
<?xml version="1.0" encoding="UTF-8"?>
<screen xmlns="http://www.romaframework.org/xml/roma"
xmlns:xsd="http://www.w3.org/2001/XMLSchema-instance"
xsd:schemaLocation="http://www.romaframework.org/xml/roma
<area name="mainPanel" type="column">
<area name="header" />
Roma Meta Framework Hand Book - Rev. 481
Page 68 of 167
<area name="topmenu" />
<area name="centralPanel" type="row">
<area name="leftMenu" />
<area name="body" />
</area>
<area name="log" />
<area name="footer" />
</area>
</screen>
To use a configurable Xml screen, write (generally in HomePage class or when you want to
change the screen):
Screen screen = ObjectContext.getInstance().getComponent(ScreenManager.class).
getScreen( "default-screen");
ObjectContext.getInstance().setScreen(screen);
11.7 Component placement in screens
Once you have defined the screen layout you can easy place Roma component by
specifiying throught layout feature: by Java Annotation or by
Example using Java annotations:
@ViewClass( layout = "screen://body" )
public class HomePage{
...
@ViewField( layout = "screen:centralPanel/leftMenu" )
protected MyMenu menu = new MyMenu();
...
}
In the example above we have used screen://body to express the body
Instead for the menu component we want to render it in screen:centralPanel/leftMenu
under centralMenu (XPath-like syntax) .
11.8 Get the underlying Echo2 components of the XML
Configurable Screen
From any point in the roma-based application to obtain the root element of the xml
screen:
ConfigurableScreen screen = (ConfigurableScreen)
ObjectContext.getInstance().getDesktop();
AreaInstance rootArea = screen.getRoot();
Roma Meta Framework Hand Book - Rev. 481
Page 69 of 167
Starting from the root element you can navigate the entire tree using a XPath-like syntax:
AreaInstance myArea = rootArea.searchNode( "//MyAreaName" );
Component c = myArea.getComponent();
Example:
<?xml version="1.0" encoding="UTF-8"?>
<screen xmlns="http://www.romaframework.org/xml/roma"
xmlns:xsd="http://www.w3.org/2001/XMLSchema-instance"
xsd:schemaLocation="http://www.romaframework.org/xml/roma
<area name="main" type="column">
<area name="header" />
<area name="dashboard" type="dashboard" size="2">
<area name="menubar" />
<area name="userSession" />
<area name="body" />
<area name="help" />
</area>
<area name="footer" />
</area>
</screen>
To obtain the "body" cell of the desktop:
ConfigurableScreen cScreen = (ConfigurableScreen)
ObjectContext.getInstance().getDesktop();
AreaInstance area = cScreen.getRoot();
AreaInstance bodyArea=area.searchNode( "//body" );
Component bodyEcho2Component= bodyArea.getComponent();
11.9 RenderingResolver: how to select the component to
render
Roma select automatically the right graphical component for each action and field reading
the type. Obviously you can always overwrite default behaviour using
single action/type you want. However sometimes can be useful change the default
behaviour.
You can do it by changing the mapping between types and components in the bean called
RenderingResolver
placed in the file:
WebContent/WEB-INF/applicationContext-view-echo2.xml:
<
bean
id
=
"RenderingResolver"
singleton
=
"true"
class
=
"org.romaframework.aspect.view.echo2...ConfigurableRenderingResolver"
>
<
property
name
=
"configuration"
>
<
map
>
Roma Meta Framework Hand Book - Rev. 481
Page 70 of 167
<
entry
key
=
"action"
value
=
"link"
/>
<
entry
key
=
"object"
value
=
"object"
/>
<
entry
key
=
"java.lang.String"
value
=
"text"
/>
<
entry
key
=
"java.lang.Integer"
value
=
"text"
/>
<
entry
key
=
"java.lang.Float"
value
=
"text"
/>
<
entry
key
=
"java.lang.Double"
value
=
"text"
/>
<
entry
key
=
"java.lang.Boolean"
value
=
"check"
/>
<
entry
key
=
"java.util.Date"
value
=
"date"
/>
<
entry
key
=
"java.util.Collection"
value
=
"list"
/>
<
entry
key
=
"java.util.Set"
value
=
"list"
/>
<
entry
key
=
"java.util.Map"
value
=
"table"
/>
</
map
>
</
property
>
</
bean
>
The Echo2 ViewAspect will search for the right component to place in this component. By
convention the entry with key "action" is the component to use for actions; "object" for
embedded objects.
11.10 Rendering modes
Rendering modes are the way Roma can render objects, fields and methods. By default the
View Aspect delegates to the
component to resolve it. You can override
the default behavior by assigning the rendering you want by using the
(Java/Xml).
In this section we are going to describe all the possible rendering modes currently
supported by Roma View Aspect. Some rendering modes can be applied to classes, fields,
methods (actions) or some of the three.
Rendering Mode
Applies to
Description
Default
Classes,
Fields,
Actions
If no rendering mode is defined for a particular class, field or
method, Roma will render it in a default way. Only public fields
and methods can be represented by Roma in the user interface.
Anyway, public fields can be explicitly hidden. The default
behaviour for rendering fields depends on the field type:
String, Integer, Float, Double, int, float, double fields are
rendered in Text rendering mode. Boolean and boolean fields
are rendered in Check rendering mode. Date fields are
rendered in Date rendering mode. Collections are rendered in
List rendering mode. Fields that don't match the previous
requirements are rendered in Objectlink rendering mode.
Methods that are not getters or setters, whose name doesn't
start by "on", that don't take parameters, are rendered in
Button rendering mode.
Accordion
Fields
Accordion is a vertical two-level menu, where, selecting a first
level element, its sub-elements list is expanded, and other sub-
elements lists are shrinked.
Button
Actions
This rendering mode shows a button having as label the method
Roma Meta Framework Hand Book - Rev. 481
Page 71 of 167
name or the declared label. In some implementations a button
can be enriched with an image.
Chart
Fields
Chart rendering mode is not implemented by default, but can
be enabled adding a module that implements the
ChartRendering mode (see Errore: sorgente del riferimento non
trovata). The current implementation of the Charting module
allows to render Collections and Maps as different types of
charts, such as pie charts, line charts, bar charts etc.
Check
Fields
(Boolean)
Check is a simple check box (checked if the field value is true).
Colset
Fields
(Collection)
This rendering mode renders a collection as a set of columns.
For each column is expanded an element of the collection.
Date
Fields (Date) Date rendering mode shows a complete interactive calendar
Roma Meta Framework Hand Book - Rev. 481
Page 72 of 167
Datetime
Fields
Date rendering mode shows a complete interactive calendar
with time
Html
Fields
When a field is rendered as Html, its value is inserted in the
page without being interpreted. If its value contains HTML tags,
these will be inserted in the page and interpreted by the
browser.
Image
Fields (String) A field can be rendered as an image if its value is the file name
of an image that is present in the package
[applicationPackage].view.image
Imagebutton
Fields
An ImageButton is a normal Image, but can be clicked. The
method that is invoken when the user clicks on the image is the
corresponding "on" method (e.g. if the field name is myField,
the method that will be invoked, if it exists, is onMyField()).
Label
Fields
The field is rendered as a text label. The represented value is
the toString() value of the object.
Link
Fields,
Actions
The field is rendered as a clickable text label. If the rendering
mode is applied to a Field, the method that is invoken when
the user clicks on the link is the corresponding "on" method
(e.g. if the field name is myField, the method that will be
invoked, if it exists, is onMyField()).
List
Fields
(Collection)
Collections can be rendered as lists of elements. In the list is
displayed, for each element, its toString() value. This rendering
also provides buttons to add, remove, view, edit and move up/
down elements (only for ordered Collections).
Roma Meta Framework Hand Book - Rev. 481
Page 73 of 167
Menu
Classes, Fields This rendering mode allows to render objects as hierarchical
menus. Fields in a menu can be rendered as sub-menus;
Methods will be rendered as links.
Objectlink
Fields
An object that is rendered as an ObjectLink is represented as a
clickable element. The displayed value is the toString() value
of the object; when clicking on the element, the corresponding
object is expanded (by default as a popup).
Objectembedded
Fields
An object that is rendered as ObjectEmbedded is expanded
inside the view of its parent object.
Password
Fields
Password rendering mode is a simple text box that shows points
or asterisks (the classic obfuscated characters) instead of the
real text.
Popup
Classes
This rendering mode renders an object as a modal popup
window.
Progress
Fields
(integers
between 0
and 100)
This rendering mode renders an object as a progress bar. The
minimum value of the bar is 0, the maximum value is 100. The
value of the field should be inside this interval. NOTE: this
rendering mode is not yet implemented.
Roma Meta Framework Hand Book - Rev. 481
Page 74 of 167
Radio
Fields
Collections and arrays can be represented as a group of radio
buttons. The selected value is set on the field indicated in the
selectionField attribute of ViewField annotation (see Errore:
Richtext
Fields (String) This rendering mode displays a rich text editor.
Rowset
Fields
(Collection)
This rendering mode renders a collection as a set of rows. For
each row is expanded an element of the collection.
Select
Fields
(Collection)
Collections and arrays can be represented as a select box. The
selected value is set on the field indicated in the selectionField
attribute of ViewField.
Tab
Fields (Map) Maps can be represented as tabbed panes: each entry in the
map represents a different tab, whose name is the entry key
and whose content is the entry value.
Table
Fields
(Collection)
Collections can be rendered as tables. Each row contains a
value in the map; each column represents a property of the
beas contained in the collection.
Tableedit
Fields
(Collection)
Collections can be rendered as editable tables. Each row
contains a value in the map; each column represents a property
of the beas contained in the collection. Cells in the table are
editable.
Text
Fields (String) This rendering mode renders an object as a text field.
Textarea
Fields (String) This rendering mode renders an object as a text area.
Time
Fields
This rendering mode renders a text field containing the hour in
the format chosen in I18N configuration.
Tree
Fields
(implements
TreeNode)
This rendering mode renders a tree structure as an expandable
tree.
Upload
Fields
(Stream)
This rendering mode allows to upload a file as a
org.romaframework.core.domain.type.Stream
11.11 Layout mode
Layout mode is the way a component will be placed. By default every single field is placed
Roma Meta Framework Hand Book - Rev. 481
Page 75 of 167
if defined (just create one and assign the same name of the field),
otherwise will go in the "fields"
. Every single action will follow the same behavior but
, Roma will place it in the "actions"
by using annotation and specifying a type between these:
Layout Mode
Applies to
Description
Default
Classes,
Fields,
Actions
If no layout mode is defined for a particular class, field or
method, Roma will use this as the default.
For classes they will be placed in the last area used, otherwise
in the "screen:/body" area.
For fields they will be added to the "form://fields" area if any,
otherwise will be created a new one.
For actions they will be added to the "form://actions" area if
any, otherwise will be created a new one
Form
Classes,
Fields,
Actions
Allow to place components inside
to express nested areas. Example:
"form:/main/bottom"
Block
Fields,
Actions
We strongly suggest to avoid block layout mode in
favour of "form" rendering using areas.
A new block will be created. If you want to assign a name to
the block use the syntax "block:foo" where "foo" is the name of
the new block just created. Use the same block to group fields
at run-time.
Example:
@ViewField( layout = "block:area1" )
If more than one field/action declare the same custom area
(they have the same block name), then the fields/actions will
be displayed in succession based on the order declared.
Example using Java Annotations:
@CoreClass( orderFields = "name surname city web",
orderActions = "ok cancel print" )
public class Customer{
private String name;
private String surname;
private String city;
private String web;
@ViewField( layout = "block:notesArea" )
private String notes;
public void ok(){}
public void cancel(){}
Roma Meta Framework Hand Book - Rev. 481
Page 76 of 167
public void print(){}
}
Screen
Classes,
Fields,
Actions
Allow to place components inside
to express nested areas. Example:
"screen:/main/bottom".
Expand
Fields
Expand all the fields of embedded object inside current fields
Popup
Classes
Layout objects as Popups
public class Task{
@ViewField( render = "richtext", layout = "form://bottom" )
private String description;
}