GRAG1.0

Introduction

You can use The GRails Application Generator (GRAG) to get started with Grails using an existing database. It will generate Grails domain objects including constraints and relations. After generating the domain objects, you can continue using Grails with all it's power.

click here to view a screenshot of the GUI

Grails Domain model generation from a database model

The process of generating Grails domain objects from a database model with GRAG breaks down into the following steps:

1. Application configuration
2. Creating entities
3. Editing the generated entities
4. Generating the domain objects
5. Exporting/Importing UML

Application configuration

An application generated by GRAG is based on an application file, an XML file containing information about the application.
There are several things that need to be configured before an application can be generated. These configurations settings are accessed via the configuration screens:

• Configuration
• Datasource

Here follows an explanation of the most important configuration settings:

Datasource settings

You can access the datasource settings screen by clicking on the 'Datasource' configuration node in the GRAG Application tree. The settings in this screen are:

• Database type: the application's database type (Hypersonic, MySQL and PostgreSQL are currently supported by default, but any JDBC Driver can be added).
• JDBC url: the JDBC connection URL pointing to the database.
• User name: the user login name to be used to authorise the application's database connections.
• Password: the password for the above user name.

Configuration > Template

Application generation templates are collections of individual template files that generate the Grails domain objects. The templates can be found in the templates directory of the GRAG distribution. Currently there is only one grails1 template directory that contains Velocity scripts for generating the grails domain objects. Custum templates can be easily added by copying the grails1 directory and changing description in the template.xml file

The template may be selected from the 'Configuration' screen by clicking the 'Select generation template' button and selecting a template directory.

Creating entities

GRAG supports a one-on-one mapping from a database table to an entity. It translates the table's columns into entity fields, and if relations are enabled, it creates relations to other entities using the table's foreign key columns.

To begin creating entities, you can either select Edit > Add > entity from the menu or click the   entity button on the toolbar. In order to create entities, GRAG must first be connected to the application database. Once connected you will be presented with a select tables dialogue where you can select the table (or multiple tables using SHIFT-click) that you want to convert into entities. Once you have completed the table selection, GRAG will inspect the database and create the appropriate entities. You will see the entity appear in the application tree view in the left-hand panel as they are created.

Editing the generated entities

You can browse a generated entity by selecting it in the tree view: an entity will 'open' to reveal its constituent fields and relations.
Fields and relations may be deleted by selecting Edit > Delete from the menu, by typing Ctrl-Delete, or by clicking on   in the toolbar.

Additional relations may also be added to the entity with Edit > Add > relation, Ctrl-R or by clicking   in the toolbar. Clicking on an entity or one of its constitutent parts will open up a configuration screen in the right-hand panel.

Entity configuration screen

This screen contains configuration options for the entity as a whole:

• Name: the name of the entity - this will be used in the class names of the generated entity model classes.
• Display Name: maps to a field of the entity that will be used in the toString method of the generated object. If left empty, the primary key field will be used
• Table name: the name of the database table behind this entity.
• Primary key: the unique primary key field in this entity (should be left empty if using a composite primary key).
• Primary key class: the fully-qualified class of the primary key
• Association entity: used for many-to-many relations. If the entity is marked as an association entity, the entity will not be generated as a domain model but used as the association table in the many-to-many relation
• Composite key?: specifies whether or not the entity has a composite (multiple-field) primary key.
• Description: a human-friendly description for the entity.

Field configuration screen

This screen contains configuration options for an entity field:

• Name: this is the field name, which must be a valid Groovy or Java field name.
• Type: the fully-qualified Groovy or Java class of this field.
• Column name: the database column that this field maps to.
• SQL type: the column type from the database.
• JDBC type: the type that the JDBC driver should map to when reading the column's value.
• Primary key: this is checked if the field is a primary key.
• Foreign key: this is checked for a foreign-key field (a field whose value relates to a primary key from another table).

This screen has a seperate area that describes the validations (if any) for this field. This is used for the automatic generation of model constraints. If can be regenerated at any time. Examples of values for this field are:

• nullable: true
• size: 0..100

Relation configuration screen

This screen contains configuration options for a relation:

• relation name: the name used to identify this relation.
• foreign key field: the field that is used for the relation
• foreign table: the database table that the foreign key points to.
• foreign table's primary key: the primary key column in the foreign-key table.
• cardinality: the relation may be one-to-one, one-to-many or many-to-many depending on the mapping between this entity and the related entity (NOTE: presently bidirectional one-to-one relations are NOT supported)..
• bi-directional relationship?: checked if the relation is bi-directional, i.e. the relation may be traversed in both directions.

Generating the domain objects

Once you have finished adding/editing/deleting the Entities in your application, you can then proceed to application generation. Application generation is started by choosing the menu File > Generate Application, or using the   button on the toolbar.

Generating an application with GRAG is a one step process, however before generation can take place GRAG will validate the application file that you have made.

Here is an overview of the various validations that are performed:

• Required fields must be filled in: e.g. the datasource URL.
• Entity primary key integrity checks.
• Duplicate field/relation names.

Once the validations have succeeded, you will be prompted to choose an output directory where the application files will be generated. Select the directory of your grails application (or generate a Grails application first with grails generate-app). The domain objects will be created in the model directory of your Grails application.

Exporting/Importing UML

Import the UML model into GRAG

In order for GRAG to be able to work with your UML design, you will first have to import it. The open source UML tool Argouml is known to work correctly with GRAG.

The import function can be found under the File menu, or it also accessible from the keyboard using the shortcut CTRL-I. You will be presented with a file chooser dialogue, from which you should select the XMI file that you saved from the UML modelling tool.

GRAG will read in the data from the UML model. If you use the correct stereotypes you should then see the entities from the model appear in the left-hand side of the GRAG application. Take a look at the example.xmi file to see how to use stereotypes with GRAG or take a look at this screenshot of an UML model exported by JAG and imported into ArgoUML.

Exporting a UML model from GRAG

You will also find in the File menu that there is an 'Export UML model..' function. This enables you at any stage to export the application back to your UML modelling tool by saving an XMI file.