This repository has been archived by the owner. It is now read-only.
Switch branches/tags
Nothing to show
Find file History


gvNIX quick start application

gvNIX is a Spring Roo distribution that focuses both enterprise knowledge and enterprise standards to build Java applications.

You must download, unpack and install the development environment for gvNIX 1.5+, to be able to follow this guide.

The goal of this quick start guide is to familiarize you with gvNIX. For this purpose, we will build an application following a domain-driven design philosophy:

  • Start with domain model (entities and logic) that captures the problem domain of the system being built.

  • Start without a service layer initially and only add services where the logic doesn’t belong in any domain entity.

  • Use Design by Contract (DbC), Automated Tests, CI and Refactoring to make the implementation as closely aligned as possible with the domain model.

The application presented in this guide is the Spring PetClinic application. The users of the application are employees of the clinic who, in the course of their work, need to view and manage information regarding veterinarians, the clients, and their pets.

Note this sample isn’t a real application which normally needs additional work like UI customization, performance improvement, database queries tunning, etc.

You can see an example of a generated web application using gvNIX here (user: admin | pass: admin)

Run from Git

If you want to preview this sample application, follow this steps on the following order. If you prefer to develop by your own, go to gvNIX Sample application Guide

  • Clone github repository

    $ git clone
  • Acces to quickstart-app

    $ cd quickstart-app
  • Execute application using maven:

    $ mvn clean compile tomcat7:run
  • Open your browser on http://localhost:8080/petclinic/

  • Access using admin as username and admin as password.

Build your own app

Create a new project

  1. Create a directory for the new project.

    $ mkdir clinic
    $ cd clinic
  2. Start gvNIX

  3. Execute command to create project:

    project --topLevelPackage com.springsource.petclinic --projectName petclinic

Create a new project using console

Persistence Setup

Execute the following command to set up persistence in your gvNIX project:

jpa setup --provider HIBERNATE --database HYPERSONIC_PERSISTENT
You can replace provider param and database param with your own configuration.

Build the domain model

The domain model

Pet Clinic Domain Entities

This class diagram represents a simplified model of the problem domain for the pet clinic problem domain, it is a good starting point for the application in order to deliver a first prototype.

Create the domain entities

Following the above class diagram, run the next commands to generate the petclinic domain entities:

  1. Create entities:

    entity jpa --class ~.domain.Pet --sequenceName PET_SEQ
    entity jpa --class ~.domain.Visit --sequenceName VISIT_SEQ
    entity jpa --class ~.domain.AbstractPerson --abstract
    entity jpa --class ~.domain.Vet --extends ~.domain.AbstractPerson
    entity jpa --class ~.domain.Owner --extends ~.domain.AbstractPerson
  2. Create PetType and Specialty enumerates to use in petclinic application:

    enum type --class ~.reference.PetType
    enum constant --name Dog
    enum constant --name Cat
    enum constant --name Bird
    enum type --class ~.reference.Specialty
    enum constant --name Cardiology
    enum constant --name Dentistry
    enum constant --name Nutrition
  3. Add fields to entities:

    field string --fieldName firstName --sizeMin 3 --sizeMax 30 --class ~.domain.AbstractPerson
    field string --fieldName lastName --notNull --sizeMin 3 --sizeMax 30
    field string --fieldName address --notNull --sizeMax 50 --sizeMin 1
    field string --fieldName city --notNull --sizeMax 30
    field string --fieldName telephone --notNull
    field string --fieldName homePage --sizeMax 30
    field string --fieldName email --sizeMax 30 --sizeMin 6
    field date --fieldName birthDay --type java.util.Date --notNull
    field string --fieldName description --sizeMax 255 --class ~.domain.Visit
    field date --fieldName visitDate --type java.util.Date --notNull --past
    field reference --fieldName pet --type ~.domain.Pet --notNull
    field reference --fieldName vet --type ~.domain.Vet
    field boolean --fieldName sendReminders --notNull --primitive --class ~.domain.Pet
    field string --fieldName name --notNull --sizeMin 1
    field number --fieldName weight --type java.lang.Float --notNull --min 0
    field reference --fieldName owner --type ~.domain.Owner
    field enum --fieldName type --type ~.reference.PetType --notNull
    field date --fieldName employedSince --type java.util.Calendar --notNull --past --class ~.domain.Vet
    field enum --fieldName specialty --type ~.reference.Specialty --notNull false
    field set --class ~.domain.Owner --fieldName pets --type ~.domain.Pet --mappedBy owner --notNull false --cardinality ONE_TO_MANY
    field set --class ~.domain.Vet --fieldName visits --type ~.domain.Visit --mappedBy vet --notNull false --cardinality ONE_TO_MANY
    field reference --fieldName owner --type ~.domain.Owner --class ~.domain.Vet
    field set --fieldName vets --type ~.domain.Vet --class ~.domain.Owner --cardinality ONE_TO_MANY --mappedBy owner
    field set --fieldName visits --type ~.domain.Visit --class ~.domain.Pet --cardinality ONE_TO_MANY --mappedBy pet
    You must to indicate field type, field name and the entity class.

Finder methods

If you want to find data by different fields, you need to generate some methods. Execute the following commands in gvNIX shell to implements this functionality:

finder add --finderName findPetsByNameAndWeight --class ~.domain.Pet
finder add --finderName findPetsByOwner
finder add --finderName findPetsBySendRemindersAndWeightLessThan
finder add --finderName findPetsByTypeAndNameLike
finder add --finderName findVisitsByDescriptionAndVisitDate --class ~.domain.Visit
finder add --finderName findVisitsByVisitDateBetween
finder add --finderName findVisitsByDescriptionLike
You must to indicate unic finderName and entity class.

Web Layers

  1. Execute the following commands setup web layer and generate web layer:

    web mvc setup
  2. Execute the following command to generate CRUD views for all application entities:

    web mvc all --package ~.web
  3. Execute the following command to generate other controller and CRUD views for an entity:

    web mvc scaffold --class ~.web.VetListController --backingType ~.domain.Vet --path vetlist
    You can create several controllers for the same entity.
  4. To generate web layers of all the generated finders above, run the next commands:

    web mvc finder all
  5. (Optional) If you want to install some differents languages to use in your application, execute de following commands:

    web mvc language --code es
    web mvc language --code de

JQuery, Datatables & Bootstrap Setup


Spring MVC - jQuery integration.

  • Converts Dojo based views into jQuery based views

  • Adds form validation support

  • Reduces the contents of small JavaScript code into the HTML document

  • Includes jQuery UI

Looks how easy you can transform your Dojo based project into jQuery based project:

  1. To use jQuery components in your project, you must to execute the following command:

    web mvc jquery setup
  2. Configure all your views to use jQuery components running the next command:

    web mvc jquery all
  3. Optionally, you can convert view-by-view to jQuery

    web mvc jquery add --type ~.web.PetController


To activate the Datatables feature on project, execute the following command:

web mvc datatables setup


To activate Bootstrap style on application pages execute the next command:

web mvc bootstrap setup

Enable Datatables Inline Editing

To use InlineEditing Datatables functionalities, you must to generate ajax methods. You can generate them using the following commands.

  1. Generate batch methods to entities

    jpa gvnix setup
    jpa batch all
  2. Generate batch methods to controllers

    web mvc batch setup
    web mvc batch all

List views with Datatables

Improve List views

After setup Datatables components run the following commands to improve list views with Datatables components:

web mvc datatables add --type ~.web.VetController --mode show
web mvc datatables add --type ~.web.VetListController
web mvc datatables add --type ~.web.PetController
web mvc datatables add --type ~.web.OwnerController
web mvc datatables add --type ~.web.VisitController --inline true --ajax true
Use --mode param with show value, to display only a record per page. Use --inlineEditing param with true value to enable inline creation and inline update

Include ToMany relationships inside List views (Master-details pattern)

After create Datatables master patterns, you can add detail list views which represent ToMany relationships with other entities.

  1. To create the following relation "Owner ToMany Pets" use the next command:

    web mvc datatables detail add --type ~.web.OwnerController --property pets
  2. To create the following relation "Owner ToMany Vet" use the next command:

    web mvc datatables detail add --type ~.web.OwnerController --property vets
    Master Datatable Vet uses mode show to display data, so this detail displays a datatable with show mode.
  3. To create the following relation "Owner ToMany Pets ToMany Visits" use the next command:

    web mvc datatables detail add --type ~.web.PetController --property visits
    The above example, shows three levels of details (Master, detail and detail of the detail)
  4. To create the following relation "Owner ToMany Vets ToMany Visits" use the next command:

    web mvc datatables detail add --type ~.web.VetController --property visits

Run application

At this point, you can run your generated gvNIX application. To do it:

  1. Open shell on the main folder of your project.

  2. Use the following command to execute your application on tomcat server:

    mvn clean compile tomcat7:run

Running gvNIX application Running gvNIX application. Works!

At this moment, you can access to your gvNIX application at http://localhost:8080/petclinic/. The application must have the following appearance:

Petclinic sample application

Loupe Fields

The Loupe fields provide new functionality to handle ToOne relationship more easily than using combobox.

To implement Loupe fields in your gvNIX application you need to execute the following commands:

  1. Setup Loupe components:

    web mvc loupe setup
  2. Add some necessary functions to the controller:

    web mvc loupe set --controller ~.web.VisitController
  3. Convert related fields to loupe elements on create and update views:

    web mvc loupe field --controller ~.web.VisitController --field pet --caption name --additionalFields name,weight --max 5
  4. As you have created vet controller with show mode, you need to use your second vet CRU views (managed by VetListController) to display vet data as a list.

    web mvc loupe field --controller ~.web.VisitController --field vet --listPath vetlist/list --additionalFields firstName,lastName
You can configure callbacks functions for fields above editing 'scripts/loupefield/loupe-callbacks.js'. You can add onDraw function and onSet function to manage that events.

Menu Setup

To install gvNIX menu, use the following command:

menu setup

Add Spring Security

To set up Spring Security in your gvNIX project, use the next command:

security setup
You need to execute web mvc bootstrap update command after security setup to displays login as Bootstrap appearance.


If you need to print reports of your application data, you can add simple reports using the next commands:

web report setup
web report add --controller ~.web.OwnerController --reportName report_owners

Optimistic Concurrency Control

With Optimistic Concurrency Control application compare the old and new entity state without the need to alter legacy database tables with version columns.

To add concurrency control to an specific entity in your project, use the following command:

occ checksum set --entity ~.domain.Pet

JUnit and Selenium Tests


Add JUnit tests to your application entities using the next commands:

test integration --entity ~.domain.Vet
test integration --entity ~.domain.Owner
test integration --entity ~.domain.Pet
test integration --entity ~.domain.Visit


Add Selenium tests to your application entities using the next commands:

selenium test --controller ~.web.OwnerController
selenium test --controller ~.web.PetController
selenium test --controller ~.web.VetController
selenium test --controller ~.web.VetListController
selenium test --controller ~.web.VisitController


gvNIX provides web services that can be accessed by external applications. To implements this functionalities, use the following commands:

remote service define ws --class --serviceName ws_get_all_pets
remote service operation --name ws_list_pets --service


gvNix provides a visual tree component which has the next features:

  • Data is represented as a tree.

  • Elements can be edited on the widget: rename, delete, create new childs, etc.

  • Drag and drop.

  • Customizable skin. You can choose one of the installed skins or customize your own skin.

  • Custumizable componentes. You can use objects, like buttons, and implement their functions.

To include this widget in your proyect, you need to follow the next steps:

  1. You need to have installed jQuery

  2. Activate FancyTree component:

    web mvc fancytree setup
  3. Create a tree to show vets:

    web mvc fancytree add show --controller ~.web.VetController --page tree
  4. Create a tree to show and edit pets:

    web mvc fancytree add edit --controller ~.web.PetController --page editable_tree


Audit feature tracks when and who creates and updates entities. To include audit on all your entities, you need to execute the next commands:

jpa audit setup
jpa audit all
These commands add audit fields in your entity views automatically. To avoid that user changes audit field values, you need to hide them in your create and update views by setting their z parameter to user-managed and add render=false parameter.


Monitoring allows to control the consumption of generate and execute views, queries, scripts, etc.

To include a new page where montorize all application entities you need to execute the next commands:

monitoring setup
monitoring all

If you do not need to monitorize all your entities, you can use the next commands:

  • To monitorize an entity:

    monitoring add class
  • To monitorize an entity method:

    monitoring add method
If the method belongs to an .aj file, you need to push-in this method.
  • To monitorize a package:

    monitoring add package


At the end of this tutorial, and if you follow all steps above, you will have a petclinic application with following appearance

sample application login sample application home sample application pet creation sample application pet list sample application visit inline sample application visit inline edit

gvNIX is based on Spring Roo project.

To implement some previous functionalities gvNIX uses different libraries like: