IntroductionYou 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 modelThe process of generating Grails domain objects from a database model with GRAG breaks down into the following steps:
- Application configuration
- Creating entities
- Editing the generated entities
- Generating the domain objects
- Exporting/Importing UML
Application configurationAn 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:
Datasource settingsYou 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 > TemplateApplication 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 entitiesGRAG 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 entitiesYou 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 screenThis 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 screenThis 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).
- nullable: true
- size: 0..100
Relation configuration screenThis 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 objectsOnce 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.
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
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 GRAGYou will also find in the
Filemenu 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.