To enable Signsoft intelliBO to store objects of the class Person inside the database, you have to provide the information which attributes of a class are persistent (persistence-capable) and which attribute corresponds to which field in a database table.
All mapping information is stored in an external XML file, the so called JDO file (extension .jdo).
The content of this file is specified by the JDO specification. The JDO file may either be associated with a JDO schema (XSD) or a doctype definition (DTD).
You can provide a JDO file either for every class or for every package in your application. The file must have the same name as your class and must reside in the same directory.
The following listing shows the structure of a JDO. The jdo tags include the package tag, which contains tags for the classes (in this case only for one class Person ), which again includes the descriptions of the several fields.
<?xml version="1.0" encoding="UTF-8"?>
<jdo xmlns="http://java.sun.com/xml/ns/jdo/jdo"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/jdo/jdo
http://java.sun.com/xml/ns/jdo/jdo_2_0.xsd">
<package name="com.intellibo.sample.firststeps">
<class name="Person">
<field name="firstName">...</field>
...
</class>
</package>
</jdo>
The JDO specification even defines rules for the mapping of classes and fields depending on their type. Signsoft intelliBO uses these rules to detect the persistence fields automatically and set the default attributes. For example, if a field of a class is not specified in the JDO file, it is persistent by default and the mapping itself usually is made using a simple direct field mapping. That means, the attribute is mapped to exactly one field in a database table. Every class- and field-attributes which are not explicitly described in the JDO file are set to default values too.
You may find more detailed information on this rules and defaults in chapter 18 "XML-Metadata" of the JDO specification.
Using this rules enables to build very small and clear JDO files. So the minimal mapping description of a persistence-capable class only consists in the class tag with the name of the class.
To indicate a class as persistence-capable, we have to create a class tag within the package tag of the JDO file. For the sake of simplicity we would like to use the default settings for the mapping of the class Person and their fields. Therefore we do not have to make any specifications in the JDO file.
So the default value for the object identity of the Person - datastore - is used (see chapter "Object Identity"). I.e., Signsoft intelliBO manages the identity of the objects itself. It uses generic primary key fields to identify the Person objects. This fields are not connected to any attribute of the class Person (so called hidden identity ) and Signsoft intelliBO creates them with a SequenceTable-ObjectID-Generator.
All fields are mapped into the database using a direct field mapping (see section "Direct Field Mapping").
The name of the database table, in which the class objects are stored and the name of the table columns associated with the fields are defined by Signsoft intelliBO using so called naming rules. If the user has not specified anything, the default - the PrefixNamingRule- is used. This naming rule generates table names and column names by applying the prefixes "T" for a table and "F" for a field and converts the class names and field names to upper case.
Hence, the mapping of class Person to a database table TPERSON looks like this:
Figure: Mapping of class Person to a database table
We would like to create a mapping file for the class com.intellibo.sample.firststeps.Person . According to the JDO specification the Person.jdo file has to be located in com/intellibo/sample/firststeps .
If you work with the Eclipse development enviroment 3.2.2 or higher, you can use the Signsoft intelliBO Eclipse plugin to create and edit the JDO files. We recommend the use of this plugin at the beginning of the work with intelliBO to avoid incorrect JDO files. Of course you can also create and edit the JDO files manually (to do so, simply copy the source code at the end of this section in your Person.jdo file), but this approach is more fault-prone than using the plugin.
You can download the Signsoft intelliBO Eclipse Plugin from the Signsoft intelliBO update site http://update.intellibo.com/beta/eclipse3.3
resp. http://update.intellibo.com/beta/eclipse3.2.2. There you can also find the installation instructions and a short description of the plugin features.
After installation you must add the Signsoft intelliBO Eclipse plugin support to your Eclipse project. To do so click with a right mouse click on the project root. In the lower part of the appearing window you will find an entry "Signsoft intelliBO", where you can choose "Add Signsoft intelliBO support".
Then you can call the wizard to create JDO files. Therefore choose your Person file in the Package Explorer, select the entry "Signsoft intelliBO" using the right mouse click and choose now "Create JDO Files(s)". The JDO wizard appears:
Figure: JDO-Wizard - Start
Here you can specify, if the JDO file should be created for the package or for the class and where to place the file. We want to create the file only for the class and place it beside the Person.java file, thus we do not have to change any settings in this dialog and call the next one pressing the "Next" button:
Figure: JDO-Wizard - General Settings
These are general settings which apply for all selected classes. You could specify these default settings and for example select the identity type. But our sample class uses datastore identity and this is the default setting for the identity and so its not necessary to explicitly select it. So you can finish the wizard after this and you will get the minimal version of a valid JDO file using the default persistence definition rules.
The created Person.jdo file will be opened in the XML editor. You could now edit the file here.
Figure: XML editor with outline view
However, for our class Person we do not need more settings and so the Person.jdo file looks like this:
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<jdo xmlns="http://java.sun.com/xml/ns/jdo/jdo"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/jdo/jdo
http://java.sun.com/xml/ns/jdo/jdo_2_0.xsd">
<package name="com.intellibo.sample.firststeps">
<class name="Person" />
</package>
</jdo>