1 Before to read........................................................................ 7
2 Introduction........................................................................... 8
2.1 Decoupling Solution For Seamless Integration................................................ 8
2.2 Fast Development............................................................................... 8
2.3 Advanced Technology........................................................................... 9
3 Get and install....................................................................... 10
3.1 Pre-requirements............................................................................... 10
3.2 Install from binaries........................................................................... 10
3.3 Install from sources............................................................................ 10
3.3.1 Get sources..................................................................................................... 10
3.3.2 Compile sources............................................................................................... 11
3.3.3 Test the installation.......................................................................................... 12
4 Create your first application....................................................... 13
4.1 Create the project............................................................................. 13
4.2 Project scaffolding............................................................................. 13
4.3 Write domain classes.......................................................................... 14
4.4 Write the application flow..................................................................... 16
4.5 Adding persistence and CRUD to an application............................................ 18
5 The Meta-Framework concept..................................................... 23
5.1 Aspects.......................................................................................... 23
5.1.1 Aspects Overview............................................................................ 24
5.2 Modules.......................................................................................... 25
5.2.1 Modules Overview........................................................................... 25
5.3 DDD Domain Driven Development............................................................ 27
5.3.1 DDD Resources................................................................................................. 28
5.4 Enrich you model using annotations.......................................................... 28
5.4.1 Annotations table............................................................................................. 28
5.4.2 Java Annotations............................................................................................... 28
5.4.3 XML Annotations............................................................................................... 29
6 CRUD................................................................................. 31
6.1 CRUD Working.................................................................................. 34
6.2 Customize a CRUD............................................................................. 35
6.2.1 Change the GUI................................................................................................ 35
6.2.2 Adding other search conditions.......................................................................... 36
6.2.3 Order the result............................................................................................... 38
6.2.4 Adding pre and post operations events................................................................ 38
6.2.5 How to get different CRUDs................................................................................ 40
6.2.6 CRUDHelper..................................................................................................... 40
7 Conventions.......................................................................... 42
7.1 Inherit by Composition........................................................................ 42
7.2 Override default behaviour................................................................... 42
7.2.1 Predefined Events............................................................................................. 43
7.2.2 Override Collection behaviour (List and Tables)..................................................... 43
8 Best Practices....................................................................... 45
8.1 Separate domain classes from presentation classes....................................... 45
9 Controller............................................................................ 46
10 View Aspect........................................................................ 47
10.1 How Roma renders POJOs................................................................... 47
10.1.1 Fields area.................................................................................. 48
10.1.2 Actions area................................................................................. 48
10.1.3 Custom areas............................................................................... 48
10.1.4 Customize form layout..................................................................... 48
10.2 Screen and Area concepts.................................................................... 49
10.3 Configurable Screens......................................................................... 49
10.4 Component placement........................................................................ 50
10.5 Get the underlying Echo2 components of the XML
Configurable Screen................ 50
10.6 Architecture of View Aspect................................................................. 51
10.7 Rendering modes............................................................................. 51
10.8 Form Validation............................................................................... 56
10.8.1 Field Validation............................................................................................... 56
10.8.2 Custom Validation............................................................................................ 57
10.8.2.1 Throw multiple exceptions in one shot............................................................ 58
10.8.2.2 Change the Look & Feel................................................................................. 58
10.9 Annotations.................................................................................... 59
10.9.1 @ViewClass..................................................................................................... 59
10.9.2 @ViewField..................................................................................................... 60
10.9.3 @ViewAction................................................................................................... 61
10.9.4 XML layout..................................................................................................... 63
10.10 Implementation: Echo2..................................................................... 64
10.10.1 Stylesheets................................................................................................... 64
10.11 Implementation: Html...................................................................... 64
10.12 Examples..................................................................................... 64
11 I18N Aspect........................................................................ 65
11.1 Interface....................................................................................... 65
11.2 Implementations.............................................................................. 65
12 Persistence Aspect................................................................. 67
12.1 Choose the right strategy.................................................................... 67
12.2 Atomic strategy............................................................................... 68
12.3 Change strategy for a single operation..................................................... 68
12.3.1 Select the strategy on Query execution............................................................. 68
12.3.2 Select the strategy on object loading................................................................ 68
12.4 Java Interface................................................................................. 68
12.5 Query Patterns................................................................................ 70
12.5.1 Query by example........................................................................................... 70
12.5.2 Query by filter................................................................................................ 71
12.6 Persistence Technologies.................................................................... 73
12.6.1 JDO............................................................................................................... 73
13 Reporting Aspect................................................................... 76
13.1 Render Types.................................................................................. 77
13.2 Template Generation......................................................................... 79
13.3 Template Manager............................................................................ 79
14 Scripting Aspect.................................................................... 81
14.1 Interface....................................................................................... 81
14.2 Implementation............................................................................... 81
15 Monitoring Aspect.................................................................. 82
15.1 Implementations.............................................................................. 82
16 Semantic Aspect................................................................... 83
16.1 Introduction................................................................................... 83
16.2 The SemanticAspect purpose................................................................ 83
16.3 Interface....................................................................................... 83
16.3.1 Annotations.................................................................................................... 83
16.3.2 Example Usage................................................................................................ 85
16.4 Implementation............................................................................... 87
17 Admin module...................................................................... 88
17.1 Info and InfoCategory........................................................................ 88
17.2 Realms......................................................................................... 88
17.3 Plug-ins........................................................................................ 88
17.4 Active sessions................................................................................ 89
17.5 Application Logs.............................................................................. 89
17.6 Database....................................................................................... 89
17.7 Environment................................................................................... 90
17.7.1 What is an Environment................................................................... 90
17.7.2 Use Environment objects.................................................................. 90
17.7.3 Admin module to handle environment objects.......................................... 91
17.8 How to access Admin functionalities....................................................... 91
18 Users module....................................................................... 92
18.1 Dependencies.................................................................................. 92
18.2 Login........................................................................................... 92
18.2.1 Set the login form as the first POJO to display.................................................... 92
18.2.2 Write your own Login behaviour........................................................................ 92
18.3 Activity Log.................................................................................... 93
18.4 Accounts....................................................................................... 94
18.5 Profiling system............................................................................... 94
18.5.1 How to use it?................................................................................................. 95
18.6 Base Group.................................................................................... 95
19 Designer............................................................................ 96
20 Messaging module.................................................................. 97
20.1 Dependences.................................................................................. 97
20.2 Display Messaging menu inside your application menu................................... 97
21 Workflow Aspect................................................................... 98
21.1 Implementations.............................................................................. 99
22 ETL................................................................................ 100
22.1 What is ETL.................................................................................. 100
22.2 Etl Aspect architecture...................................................................... 100
22.3 Defining a custom ETL procedure......................................................... 101
22.3.1 The ETL descriptor........................................................................................ 101
22.3.2 The Record................................................................................................... 101
22.3.3 defining extraction strategy............................................................................ 102
22.3.4 defining transformation strategy...................................................................... 104
22.3.5 Defining load procedure................................................................................. 105
22.3.6 The import procedure description................................................................... 105
22.4 A custom ETL: from JDBC to JDBC........................................................ 107
22.5 Validating imported data................................................................... 109
23 Session Aspect.................................................................... 110
23.1 Interface...................................................................................... 110
23.2 Usage Example............................................................................... 110
23.3 Implementations............................................................................. 111
24 Scheduling......................................................................... 112
25 Chart.............................................................................. 113
25.1 Introduction.................................................................................. 113
25.2 What kind of objects can be represented as charts..................................... 113
25.3 What kind of charts can be represented.................................................. 113
25.4 Installing the chart module................................................................. 115
25.5 Rendering a chart........................................................................... 115
25.5.1 Maps and Collections...................................................................................... 116
25.5.2 The ChartRenderer class................................................................................. 116
25.5.3 The ChartRepresentable interface................................................................... 117
25.5.4 The ChartViewer class.................................................................................... 118
25.5.5 Using Chart Module to build images.................................................................. 118
26 Service Aspect.................................................................... 119
26.1 How to expose a service.................................................................... 119
26.2 Implementations............................................................................. 120
26.2.1 @ServiceClass................................................................................................ 120
27 About Romulus.................................................................... 121
28 License............................................................................ 122
29 Bibliography....................................................................... 125
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:
All commands to execute are wrapped inside a gray block with
the prompt at the beginning:
2
Introduction
Roma is a new way to develop enterprise level java
applications with low effort.
Using the Meta-Framework approach you
can integrate the latest breaking technology in your application without
modifying your domain and custom application logic.
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 licensed.
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 “meta” framework. Using Roma you're definitely free from the
technology you're using. How it works? Roma provides very generic behaviour
interfaces called “Aspects”. 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 DDD (Domain Driven Design)
approach.
How does it work ?
You start off by defining the entities/classes of your
domain. You can write them by using 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 Annotations. Annotation can be under the form of Java Annotation (introduced with Java version 5) or Xml Annotation.
By using annotations 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 is based on the most advanced technology available on
the market. First of all it is component based. Every component is handled by
the IoC container. By default Roma uses the Spring Framework but you can
replace it if you want. So all the configuration information resides in XML
files.
Roma allows you to select the modules required during the
building process.
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 Sun's Java
Home page to download the right SDK.
3.2
Install from binaries
You can download Roma binaries from Roma web site (http://www.romaframework.org). You
will find many packages, one for each module. For a quick start you just need
to download
l
Download a binary distribution
l
Extract the downloaded archive to a directory in your file system
l
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 SVN
since official releases are published every 3-4 months.
3.3.1.1
From Source distribution
- Download
a sources distribution
- 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
- Type:
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 Annotations and Typed
Collections. You can download it here.
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 here.
3.3.2.2
Compile it all
Follow these steps:
1. Change current
directory to the Roma's dev
directory and execute:
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).
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
If the installation succeeded, the help will appears.
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
By typing ’roma create’, 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-pa
