Reference |
This section provides an overview of the most commonly used Emeraldjb tags.
Project
A PROJECT is the outer most container of an Emeraldjb project. A project is the model generally created for an application, application module, or an Application Programming Interface (API). It defines the general and global information for the project like default packages.
<PROJECT NAME="Customer Order System"> <PATTERN NAME='value.classpath' VALUE='com.mycompany.values'/> <PATTERN NAME='stream.classpath' VALUE='com.mycompany.stream'/> <PATTERN NAME='stream.proto_version' VALUE='1'/> <PATTERN NAME='dao.classpath' VALUE='com.mycompany.dao'/> ... </PROJECT>
The PATTERN tag is used to provide default packages for the generated classes. For instance, all of the generated DTO objects will be placed in the "com.mycompany.values" package.
Section
The Section area of the Emeraldjb project allows developers to organize work by module. Often times, different parts of a project may be organized in different sub folders for better understanding and organization. However, it is perfectly ok to have the entire project in one section. The section may also overide the default project package with its own.
<SECTION NAME="Section1" MODULE="MULTI"
DEFAULT_PACKAGE="com.my.company.db"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="/dev/emeraldjb/schemas/emeraldjb.xsd">
...
</SECTION>
Header
The Header is where general developer and company information is stored. This information is used for documentation purposes.
<HEADER> <DEVELOPER>John Doe</DEVELOPER> <FILE_HEADER> * Copyright (c) 2003 by Company, Inc. </FILE_HEADER> </HEADER>
Entity
An ENTITY is an object that is represented in the database by a record with a primary key. For example, a users information is represented in the database by a single record in the USERS table. Essentially, entities defined in XML become tables in the database. Entities are Bean Managed Persistence (BMP) Java beans that allow developers to create and update single database records via methods in Java classes. The generated SQL uses fast-performing PreparedStatements, with type-safe parameter passing.
<ENTITY NAME="CUSTOMER_INFORMATION">
<JAVADOC>
<DESCRIPTION>Table that contains all customers in the system.</DESCRIPTION>
<SINCE>1.0</SINCE>
</JAVADOC>
<MEMBER NAME="CUSTOMER_ID" FROM_SEQ='CUSTOMER_ID_SEQ' TYPE='int' NULL_ALLOWED='FALSE'/>
<MEMBER NAME="ACTIVE" TYPE='boolean' DEFAULT='1' NULL_ALLOWED='FALSE'/>
<MEMBER NAME="FIRST_NAME" COL_LEN='75' TYPE='string' NULL_ALLOWED='FALSE'/>
<MEMBER NAME="LAST_NAME" COL_LEN='75' TYPE='string' NULL_ALLOWED='FALSE'/>
<MEMBER NAME="ADDRESS" COL_LEN='175' TYPE='string' NULL_ALLOWED='FALSE'/>
<MEMBER NAME="ACCOUNT_ACTIVATION_DATE" TYPE='date'/>
<MEMBER NAME="ACCOUNT_DEACTIVATION_DATE" TYPE='date' NULL_ALLOWED='FALSE'/>
<PRIMARY_KEY COLS='CUSTOMER_ID' NAME="customer_info_pk"/>
</ENTITY>
In general, the entity contains a database table name, member field names, indexes and database constraints. In addition, both the entity and its member fields may contain JavaDoc documentation. The NAME tag defines the database table name that follows the following conventions:
- Each word of the database table name should be capitalized.
- If a multi-word table name is provided all spaces should be substituted with an underscore '_'.
- The name must conform to the underlying database restrictions for table names.
Member Fields
The MEMBER and MEMBER_SPEC tags define the databse entity fields. The only diffrence between the two tags is the MEMBER_SPEC tag may include the JAVADOC tag. The attributes are listed in detail on the definitions page.
<MEMBER NAME="CUSTOMER_ID" FROM_SEQ='CUSTOMER_ID_SEQ' TYPE='int' NULL_ALLOWED='FALSE'/>
<MEMBER_SPEC NAME="CUSTOMER_ID" FROM_SEQ='CUSTOMER_ID_SEQ' TYPE='int' NULL_ALLOWED='FALSE'>
<JAVADOC>
<DESCRIPTION>
The id assigned to every customer.
</DESCRIPTION>
<DEPRECATED>CUSTINDEX has been replaced by CUSTOMER_ID</DEPRECATED>
<SEE>com.mycompany.CustomerInformation#getCustomerId()</SEE>
<SINCE>1.1</SINCE>
</JAVADOC>
</MEMBER_SPEC>
The MEMBER and MEMBER_SPEC name attribute conforms to the following conventions:
- The field name is capitalized, limited in length by the underlying database.
- If a multi-word field name is provided all spaces should be substituted with an underscore '_'.
- As within the database table each field name must be unique.
- The generated Java classes follow Sun's naming conventions making the first word lowercase. With each subsequent words first letter capitalized.
- The generated Java classes follow Sun's JavaBean conventions using setter and getter methods for each field.
Primary Key
A PRIMARY_KEY is used to uniquely identify each record within a database table. It consists of one or more entity member fields. If multiple MEMBER fields are used the generator automatically creates a Primary Key class.
A single member primary key <PRIMARY_KEY COLS="CUSTOMER_ID" NAME="customer_id_pk"/> A multi-member primary key <PRIMARY_KEY COLS="ORDER_ID,CUSTOMER_ID" NAME="ordier_id_cust_id_pk"/>
Foreign Key
A FOREIGN_KEY is a reference to a PRIMARY_KEY or INDEX in antoher database table. An Entity can have zero or more FOREIGN_KEY tags. The foreign key consists of one or more member fields that are references to fields in other table(s). The REFERENCES attribute name must be the same as the underlying database names. This allows foreign keys that are not defined in this XML file. Additonally, the types of the COLS and REFERENCES fields must match.
<FOREIGN_KEY COLS="CUSTOMER_ID" REFERENCES="CUSTOMER_INFORMATION(CUSTOMER_ID)" NAME="order_cust_id_fk"/>
Nugget
In general a NUGGET is a stateless object that is the representation of a view in the database. It is used to create a single view from multiple tables and is optimized for read-only database access. This allows the developer to take advantage of the mightiest performance tool they have - the database. The advantage of searcher nuggets is that cross table selects are now possible.
<NUGGET NAME="CustomerOrderNugget">
<JAVADOC>
<DESCRIPTION>
The orders a customer has placed.
</DESCRIPTION>
</JAVADOC>
<FROM>CUSTOMER_INFORMATION c, ITEM i, ORDER_ITEM oi, CUSTOMER_ORDER o</FROM>
<FIELD NAME="customerId" TYPE='int' SRC='c.CUSTOMER_ID' />
<FIELD NAME="firstName" TYPE='String' SRC='c.FIRST_NAME' />
<FIELD NAME="lastName" TYPE='String' SRC='c.LAST_NAME' />
<FIELD NAME="itemId" TYPE='int' SRC='i.ITEM_ID' />
<FIELD NAME="itemDescription" TYPE='String' SRC='i.ITEM_DESCRIPTION' />
<FIELD NAME="orderId" TYPE='DATE' SRC='o.ORDER_DATE' />
<FINDER NAME="findByCustomerId">
<PARAMS>int customerId</PARAMS>
<SQL>
WHERE
c.CUSTOMER_ID = '%$P(customerId)%'
AND o.CUSTOMER_ID = c.CUSTOMER_ID
AND oi.ORDER_ID = o.ORDER_ID
AND i.ITEM_ID = oi.ITEM_ID
ORDER BY o.ORDER_DATE
</SQL>
<JAVADOC>
<DESCRIPTION>
Returns all items a customer has ordered by customer id.
</DESCRIPTION>
</JAVADOC>
</FINDER>
</NUGGET>
Nugget Fields
The FIELD and FIELD_SPEC tags define the link between a specific database column and nugget member attribute. Like the MEMBER and MEMBER_SPEC tags the only diffrence between the two is the FIELD_SPEC tag may include the JAVADOC tag. The available data-types are the same as the MEMBER and MEMBER_SPEC tags.
<FIELD NAME="customerId" TYPE='int' SRC='c.CUSTOMER_ID' />
<FIELD_SPEC NAME="customerId" TYPE='int' SRC='c.CUSTOMER_ID'>
<JAVADOC>
<DESCRIPTION>
The customer id form the CUSTOMER_INFORMATION table.
</DESCRIPTION>
<SINCE>1.1</SINCE>
</JAVADOC>
</FIELD_SPEC>
The SRC attribute contains the table-scoped database column name.
The FIELD and FIELD_SPEC name attribute conforms to the following conventions:
- The field name must be the same as the underlying table column.
- The field type should be the same as the underlying database.
- Aliases can be used to reference the same column name for multiple tables.
- Each accessor name must be unique (contents of the field tag)
- The generated Java classes follow Sun's JavaBean conventions using setter and getter methods for each field.
Finder
A Finder is the mechanism to allow for a query against the database with or without parameters from the application. They can be associated with entities and nuggets. Here are a few examples of how to use finders:
- Query the database for a record with a parameter other than the primary key.
- Retrieve a list of records from the database to populate application select lists.
- Retrieve a collection of view records to present master views in the application.
<ENTITY NAME="ORDER_ITEM">
<JAVADOC>
<DESCRIPTION>Table that contains all order items in the system.</DESCRIPTION>
<SINCE>1.0</SINCE>
</JAVADOC>
<MEMBER NAME="ORDER_ITEM_ID" FROM_SEQ='ORDER_ITEM_ID_SEQ' TYPE='int' NULL_ALLOWED='FALSE'/>
<MEMBER NAME="ORDER_ID" TYPE='int' NULL_ALLOWED='FALSE'/>
<PRIMARY_KEY NAME="order_item_pk" COLS='ORDER_ITEM_ID'/>
<FINDER NAME="getItemsByOrderId">
<PARAMS>int orderId</PARAMS>
<SQL>
WHERE
ORDER_ID = '%$P(orderId)%'
</SQL>
<JAVADOC>
<DESCRIPTION>
Returns all items by order id.
</DESCRIPTION>
</JAVADOC>
</FINDER>
</ENTITY>
The PARAMS tag contains a comma-delimited list of parameters. The SQL tag contains the actual SQL code that defines the WHERE and ORDER BY clauses. This may contain any arbitrary SQL that references the actual column names in the enclosing entity or nugget. A CDATA section encloses the SQL, thus preserving the less than < and greater than > operators that would ordinarily be interpreted as XML symbols. The SQL references parameters using the $P(paramName) syntax, where paramName appears in the PARAMS signature tag. The generator replaces these parameters replaced by the '?' symbol and are added to the appropriate position within the generated prepared statement.
