Data Model Generation

For using the data model generation, use the dmgen-maven-plugin. The data model is specified in a datamodel specification xml file, usually called datamodel.xml.  Its location is given by the parameter dmSpecFile of the dmgen-maven-plugin.  Based on that file, the generator can generate various kinds of source code.  The decision what to generate is given in a configuration file, usually called generator.xml.  Its location is given by the parameter dmConfigFile of the dmgen-maven-plugin.

A common usecase is having the datamodel.xml file in the api project, and using it for generation both in the api and in the impl project, with a generator.xml in both projects.  To make this work, one must include the datamodel.xml file into the api bundle as a resource, and then refer to it from the impl bundle.

The datamodel specification file

The datamodel specification xml file has the structure given below.  Some general notes:

• A code name is the name of an entity or an attribute defined in the datamodel, used in the Java code.
• Accordingly, a db name is the name of an entity or an attribute used on database level for defining tables etc.

The structure of the specification xml file:

• Node DataModel is the top level node.
  
  • Attribute transformCamelCaseForDB refers to the feature of automatically generate adjusted database names (table, columns, etc.) based on Java-style names given in the xml file.  If set, intra-name upper case letters are converted to lower case, and prefixed by a underscore.  E.g. MeasureProfileDef turns into measure_profile_def.  Note that this mechanism only works for entities and attributes whose name is defined by the xml attribute name, the db names specified by dbName are not overridden.
    
    • Default value "false": Do not generate database names automatically
    • Default value "true": Do generate database names automatically
  • Node Entity specifies a entity in the sense of the data model.  In generally, for each entity a dto and a table is generated, but transient entities (which have no counterpart on the database) are possible.
    
    • Attribute name specifies the name of the entity, and will be used both as code name and as db name.  You may either enter codeName and dbName, or name.
    • Attribute codeName specifies the code name of the entity
    • Attribute dbName specifies the db name of the entity
    • Attribute genCodeName TODO
    • Attribute abstract defines wether an entity is considered abstract.  For abstract entities, no database tables are generated, accordingly no DAO classes are generated, and the generated Dto will be abstract in the Java sense.
      
      • Default value "false": Entity is not abstract
      • Value "true": Entity is abstract.
    • Attribute transient defines wether an entity has a counterpart on the database.  It is similar to abstract, the difference is that transient entities are not considered abstract on Java level.
      
      • Default value "false": Entity is not transient
      • Value "true": Entity is transient.
    • Attribute base defines the base entity of an entity.  It is optionally, if entered, the codename of the base entity is expected as value.  The resulting database table will contain all attributes of the base entity, plus its own.  The resulting dto class will inherit the base entity dto class in the Java sense.
    • Node Attribute specifies an attribute of an entity, i.e. a column in the database sense and a member variable in the Java sense.
      
      • Attribute name specifies the name of the attribute, and will be used both as code name and as db name.  You may either enter codeName and dbName, or name.
      • Attribute codeName specifies the code name of the attribute.
      • Attribute dbName specifies the db name of the attribute.
      • Attribute type specifies the type of the attribute. Supported values are:
        
        • Double for double
        • Long for long
        • Integer for int
        • String for strings, the Java type will be String and the database type varchar.
        • Date for dates
        • Boolean for booleans.
      • Attribute dbType (currently) only serves for documentation purposes, and can contain a freetext db type string.  It will not influence the way a database will be generated, this is controlled by type. For transient attributes there's a pseudo dbType value.
      • Attribute feature specifies that the Attribute is to be treated specially in some way by the generator.  Currently, the following feature Strings are defined:
        
        • createTist can be used for Attributes of type Long, and makes the fillPreparedStatementFromDto method generated by the DAO generator fill the attribute with System.currentTimeMillis if and only if the value passed in the DTO is null.  Under the assumption that it will never be altered programmatically, the attribute will always reflect the creation timestamp of the tuple.
        • mutTist can be used for Attributes of type Long, and makes the fillPreparedStatementFromDto method generated by the DAO generator fill the attribute with System.currentTimeMillis always.  Under the assumption that it is never altered programmatically, the attribute will always reflect the timestamp of the last mutation of the tuple.
      • Attribute primaryKey specifies wether the attribute is a primary key (value "true"), or not (default value "false").
      • Attribute foreignKey specifies that the attribute is a foreign key to the given entity, which is given by its code name.
      • Attribute nullable specifies wether the attribute is nullable in the database sense (default value "true"), or not (value "false").
      • Attribute precision specifies the precision in the database sense of the attribute, e.g. the length of a varchar.
      • Attribute index specifies wether an index is to be generated for the corresponding database table (value "true"), or not (default value "false")
      • Attribute transient defines wether an attribute has a counterpart on the database or just serves temporary data holder purposes.
        
        • Default value "false": Attribute is not transient and is respected in equal() and hashcode()
        • Value "true": Attribute is transient and not used in equal() or hashcode()
    • Node DAO specifies details about the DAO to be generated for the entity.  Note that a DAO is generated (for all non-transient, non-abstract entities) even if this xml node is missing.
      
      • Attribute abstract specifies wether the DAO should be generated in an abstract manner (value "true"), i.e. prepared for extending it with a concrete DAO class containing customized, hand-written code, or not (default value "false").
      • Node FillJoinDto defines that some helper methods related to filling a join dto (which generally refers to multiple entities) should be generated in this DAO.
        
        • Attribute dto refers to the name of the join dto.
      • Node Join defines a join to be generated in the DAO, based on a Join Dto.  Join Dtos are described below.
        
        • Attribute dto specifies the name of the Join Dto to be used for the Join.
        • Attribute name specifies the name of the Join.
        • Node JoinParameter defines a parameter for the Join, i.e. a parameter passed to the DAO method where the join is implemented, to be used in one of the join clauses.
          
          • Attribute name defines the name of the parameter, must be unique within the scope of the Join.
          • Attribute type defines the type of the parameter, where the type is encoded the same way as the type of an Attribute, see above.
        • Node JoinCondition specifies a join condition, i.e. a sql clause of the form a.foreignKey = b.primaryKey where a and b are local names defined in the Join Dto.
          
          • Attribute from is the local name of the table where the foreign key starts, i.e. "a" in the example above
          • Attribute foreignKey is the code name of the foreign key to be used for the join clause
          • Attribute to is the local name of the table where the foreign key points to, i.e. "b" in the example above.
        • Node ValueCondition specifies a condition that refers to a JoinParameter as described above, e.g. an sql clause of the form a.foo = x, where x is a join parameter.
          
          • Attribute localName specifies the local name of the table to be used for the clause
          • Attribute attribute specifies the code name of the attribute to be used for the clause
          • Attribute param specifies the name of the parameter as defined in the corresponding JoinParameter node, see above.
        • Node ConstCondition specifies a equality condition on some attribute present in the JoinDto
          
          • Attribute localName specifies the local name of the table to be used for the clause
          • Attribute attribute specifies the code name of the attribute to be used for the clause
          • Attribute value specifies the value to be used for the clause
  • Node JoinDto specifies a Join Dto.  A Join Dto consists of a number of entities defined in the data model, and is used for transferring the results of a join across multiple tables (i.e. entities).  Optionally, one can specify that a Join Dto contains only a subset of the attributes of some particular entity.
    
    • Attribute name defines the name of the Join Dto, as used in particular in the Join nodes.
    • Node Entity defines that the given entity is part of the Join Dto.  Note that an entity may be part of a Join Dto multiple times, e.g. when joining a tree item with its parent.  To make this possible, in the context of joins, entities are not referred to by their names, but by local names defined in the Join Dto.
      
      • Attribute codeName specifies the code name of the entity.
      • Attribute localName defines the local name of the entity
      • Attribute attribdtoPackageutes is optional, and if given, it contains a comma separated list of attributes of the entity at hand to be part of the Join Dto.  If not given, simply all attributes of the entity are part of the Join Dto.

The generator xml file

The generator xml file defines, which pieces of code are generated at which location.  It consists of a top level node called GeneratorConfig, and a number of child nodes called Generate.  Each of those child nodes corresponds to one code concept to be generated.  At present, only generation of various kinds of Java code is supported. The following attributes of node Generate must be given always:

• concept defines the concept to be generated, e.g. Dto classes, or the table definitions class.  See below for a detailed list.
• package defines the package where the generated classes live.

The following concepts are supported; some of them with specific parameters which are given as attributes of node Generate:

• dto triggers generation of Dto classes for all entities.
  
  • implementedInterface is an optional parameter, if given all generated Dtos implement the given interface (given by its fully qualified name).
• joinDto triggers generation of JoinDto classes for all Join Dtos.
  
  • dtoPackage is a mandatory parameter, and specifies the package where the dto classes live / were generated to.
  • implementedInterface works the same way as for concept dto
• tableDefinitions triggers the generation of the table definitions class.
• daoInterface triggers the generation of DAO interfaces.
  
  • dtoPackage is a mandatory parameter, and specifies the package where the dto classes live
  • joinDtoPackage is a mandatory parameter, and specifies the package where the join dto classes live
• jdbcDAO triggers the generation of jdbc DAO classes.
  
  • dtoPackage and joinDtoPackage work the same way as for concept daoInterface
  • tableDefinitionsClass is a mandatory parameter, and must contain the fully qualified name of the TableDefinitions class.
  • daoInterfacePackage is a mandatory parameter, and contains the package where the dao interfaces live.
  • supportImpExp is an optional parameter (values "true" or "false"), and specifies wether the generated jdbc DAOs should support import and export.  The default is "true".  If enabled, all jdbc DAO classes will implement the interface ImportExportDAO, which contains two methods that are needed by the importer to do its work.