Speedo user manual: Edition of .jdo file(Mapping)

 FinalLogo.jpg
 FinalLogo.jpg
  1. Class inheritance mapping
  2. Class Mapping (Table)
  3. Class identifier
  4. Primitive fields mapping (Column, SQL type, converter)
  5. Reference fields mapping (foreign key)
  6. Collection fields mapping (join table, foreign key)
  7. Map fields mapping (join table, foreign key, key)
  8. Bidirectional relationship (reverse field)
  9. The foreign key declaraction
  10. Sequence
  11. All extensions

Back to the Speedo documentation




The .jdo files describe which classes are the persistent. In the current version of Speedo,the user is required to specify which are the persistent fields for each class. For each class and each field, the user can specify (optionally) extensions for Speedo. Extensions allow the user to choose a mapping of the persistent object into a relational database.

  1. Class Mapping (Table, identifier)
  2. An extension named 'sql-name' permits the user to specify the table name where the persistent class is stored.

    <class name="A">
    <extension vendor-name="speedo" key="sql-name" value="TABLE_A"/>
    </class>

    If this extension is not specified, by default the table name is equal to the name of the class (whithout the package name).

  3. The identifier of the persistent objects
  4. Speedo supports 4 types of identifiers:

    All the extension concerning the identifier must be done on the class tag in the .jdo files.

  5. Primitive fields mapping (Column, SQL type, converter)


  6. Reference fields mapping (foreign key)
  7. class A {
    private B myB;
    ...
    }
    class B {
    ...
    }

    A reference field is a field which references a Persistent class and not a multivalued reference (Collection/Set/...). Speedo allows the user to specify which primary key is referenced and therefore where is the foreign key. For a simple reference there are two solutions:

    For more information about the values corresponding to the key "source-foreign-keys" and "target-foreign-keys", see the section foreign keys declaraction

  8. Collection fields mapping (join table, foreign key)
  9. A "collection" field is a field which references several Persistent classes. Speedo supports several types of structure (java.util.Collection, java.util.Set, java.util.List, []...). Depending of the type of relation (One-Many, Many-Many), a join table can be specified. The join table is optional for a One-Many relation; a foreign key can indeed be defined in the table of the referenced persistent class. On the opposite, a join table is required for a Many-Many relation. The following examples go through the supported cases:

    Example 1:
    class A {
    private Collection myBs;
    }
    class B {
    }

    The user does not specify any information about the mapping. By default the relation is stored into a join table. The table and the columns names are chosen by Speedo.


    <field name="collectionOfB" persistence-modifier="persistent">
    <collection element-type="B"/>
    </field>

    Example 2:
    class A {
    private Collection myBs;
    }
    class B {
    private A myA;
    }

    The relation is One-Many and there is no join table. The "source-foreign-keys" extension defines the name of the foreign key column in the table of the referenced persistent class.


    <class name="A">
    <field name="collectionOfB" persistence-modifier="persistent">
    <collection element-type="B"/>
    <extension vendor-name="speedo" key="source-foreign-keys" value="PKA=FKA"/>
    <extension vendor-name="speedo" key="reverse-field" value="thefA"/>
    </field>
    </class>
    ...
    <class name="B">
    <field name="thefA" persistence-modifier="persistent">
    <collection element-type="B"/>
    </field>
    </class>

    Example 3:
    class A {
    private Collection myBs;
    }
    class B {
    }

    The relation is Many (no reverse field exists) and there is a join table. The key "join-table" defines the name of the join table. If it is not specified, the default table name is defined as the concatenation of the short class name (without the package name) of the source class with the name of the collection field. The "source-foreign-keys" and "target-foreign-keys" extensions define the column names of the join table.


    <field name="collectionOfB" persistence-modifier="persistent">
    <collection element-type="B"/>
    <extension vendor-name="speedo" key="join-table" value="A_TO_B"/>
    <extension vendor-name="speedo" key="source-foreign-keys" value="PKA=FKA"/>
    <extension vendor-name="speedo" key="target-foreign-keys" value="PKB=FKB"/>
    </field>

    Example 4:
    class A {
    private Collection myBs;
    }
    class B {
    private Collection myAs;
    }

    The relation is Many-Many. The key "join-table" defines the name of the join table. If it is not specified the default table name is defined as the concatenation of the short class name (without the package name) of the source class, with the name of the collection field. The "source-foreign-keys" and "target-foreign-keys" extensions define the columns name of the join table.



    <class name="A">
    <field name="collectionOfB" persistence-modifier="persistent">
    <collection element-type="B"/>
    <extension vendor-name="speedo" key="join-table" value="A_TO_B"/>
    <extension vendor-name="speedo" key="source-foreign-keys" value="PKA=FKA"/>
    <extension vendor-name="speedo" key="target-foreign-keys" value="PKB=FKB"/>
    <extension vendor-name="speedo" key="reverse-field" value="collectionOfA"/>
    </field>
    </class>
    ...
    <class name="B">
    <field name="collectionOfA" persistence-modifier="persistent">
    <collection element-type="A"/>
    </field>
    </class>
    Example 5:
    class A {
    private Set strings;
    }

    The persistent class 'A' references a set of String. The sets of String are stored into the table 'T_SET'.

    <class name="A" identity-type="datastore">
    <field name="id" primary-key="true">
    <extension vendor-name="speedo" key="sql-name" value="IDA"/>
    </field<>

    <field name="strings" persistence-modifier="persistent">
    <collection element-type="String"/>
    <extension vendor-name="speedo" key="join-table" value="T_SET"/>
    <extension vendor-name="speedo" key="source-foreign-keys" value="IDA=IDA"/>
    <extension vendor-name="speedo" key="element-sql-name" value="STR_ELEM"/>
    </field>
    </class>

  10. Map fields mapping (join table, foreign key, key)
  11. there are two cases of mapping for a Map field.

    1. Firstly the "map" field is stored into an intermediate table, which the name can be defined by the 'join-table' extension. In this case no relationship is possible.
      • The example shows a map referenced by the A class ('mapOfBIndexedByString' field). The key of the map is a String value for which the column name can be specified by the 'index-sql-name' extension. The value type of the map is the persistent class B for which the mapping (column name) of the reference can be specified by the 'target-foreign-keys' extension. Finally the map identifier is always the identifier of the reference holder (the 'A' class). The column name of the map identifier can be specified by the extension 'source-foreign-keys'.

        <class name="A">
        <field name="mapOfBIndexedByString" persistence-modifier="persistent">
        <map key-type="java.lang.String" value-type="B"/>
        <extension vendor-name="speedo" key="join-table" value="MAP_TABLE_NAME"/>
        <extension vendor-name="speedo" key="source-foreign-keys" value="PKA=FKA"/>
        <extension vendor-name="speedo" key="target-foreign-keys" value="PKB=FKB"/>
        <extension vendor-name="speedo" key="index-sql-name" value="KEY_COL_NAME"/>
        <extension vendor-name="speedo" key="index-sql-type" value="VARCHAR(40)"/>
        </field>
        </class>
      • The example shows a map referenced by the 'A' class ('mapOfStringIndexedByLong' field). The key of the map is a Long value for which the column name can be specified by the 'index-sql_name' extension'. The value type of the map is a String for which the column name can be specified by the 'element-sql-name' extension. Finally the map identifier is always the identifier of the reference holder (the 'A' class). The column name of the map identifier can be specified by the extension 'source-foreign-keys'.

        <class name="A">
        <field name="mapOfStringIndexedByLong" persistence-modifier="persistent">
        <map key-type="java.lang.Long" value-type="java.lang.String"/>
        <extension vendor-name="speedo" key="join-table" value="MAP_TABLE_NAME"/>
        <extension vendor-name="speedo" key="source-foreign-keys" value="PKA=FKA"/>
        <extension vendor-name="speedo" key="element-sql-name" value="VALUE_COL_NAME"/>
        <extension vendor-name="speedo" key="element-sql-type" value="VARCHAR(34)"/>
        <extension vendor-name="speedo" key="index-sql-name" value="KEY_COL_NAME"/>
        <extension vendor-name="speedo" key="index-sql-type" value="INT8"/>
        </field>
        </class>



    2. Secondly the map field is stored into the table of the persistent class stored in value. In this case the key of the map is a field of the class, and it is possible to have a relationship (reverse field).
      • The example shows a map referenced by the A class ('bf1_2_B' field). The key of the map is the 'f1' field of the B class. The value type of the map is the persistent class B.

        <class name="A">
        <field name="bf1_2_B" persistence-modifier="persistent">
        <map key-type="java.lang.String" value-type="B"/>
        <extension vendor-name="speedo" key="source-foreign-keys" value="PKA=FKA"/>
        <extension vendor-name="speedo" key="key-field" value="f1"/>
        </field>
        </class>
        <class name="B">
        <field name="f1"/>
        </class>
      • The second example is the same than the last with a bidirectional relation.

        <class name="A">
        <field name="bf1_2_B" persistence-modifier="persistent">
        <map key-type="java.lang.String" value-type="B"/>
        <extension vendor-name="speedo" key="source-foreign-keys" value="PKA=FKA"/>
        <extension vendor-name="speedo" key="key-field" value="f1"/>
        <extension vendor-name="speedo" key="reverse-field" value="myA"/>
        </field>
        </class>
        <class name="B">
        <field name="f1"/>
        <field name="myA"/>
        </class>


    Bidirectional relationship (reverse field)

    For each field referencing one or several persistent classes, it is possible to specify the reverse field of the relation if it exists. This information is very important: useless I/O are avoided based on the reverse field declaration. The fact that two fields are opposite depends on the semantics of the fields.

    <class name="A">
    <field name="refToB">
    <extension vendor-name="speedo" key="reverse-field" value="refToA"/>
    ...
    </field>
    ...
    </class>
    <class name="B">
    <field name="refToA"/>
    ...
    </class>


  12. The foreign keys declaraction
  13. A foreign key declaraction (source or target) defines the column names of the foreign key according to the primary key structure. A foreign key declaraction is comma-separated list of equalities between the name of a primary key column and the name of a foreign key column.

    Example 1:

    The identifier of the referenced object (A) consists of a single column named "pka" and the column name of the foreign key column is named "fka".
    <class name="A">
    <field name="refToB">
    <extension vendor-name="speedo"
    key="target-foreign-keys"
    value="pka=fka"/>
    </field>
    </class>

    Example 2:

    The identifier of the referenced object (A) consists of two fields (FIRST_NAME, LAST_NAME). The corresponding names of the composite foreign key are (A_FN, A_LN).
    <class name="A">
    <field name="refToB">
    <extension vendor-name="speedo"
    key="source-foreign-keys"
    value="FIRST_NAME=A_FN,LAST_NAME=A_LN"/>
    </field>
    </class>


  14. Sequence
  15. The sequence element identifies a sequence number generator that can be used for several purposes:

    A sequence is defined at the package level. The list of attributes to define your sequence is as follows:

    <package ...>
    <sequence name="my_seq" strategy="transactional" datastore-sequence="name_of_datastore_seq"/>
    ...
    </package>

    You can retrieve the sequences using the getSequence(String name) method on the persistent manager:

    Sequence s = pm.getSequence(SEQ_NAME); //SEQ_NAME is the fully qualified name of the sequence : package + seq_name
      The actions you can perform on a sequence are:


      Note: be sure that one of the class of the package the sequence belongs to has been loaded before using the sequence.

    PersistenceManager pm = pmf.getPersistenceManager();
    //first, load the class
    pm.getObjectIdClass(Article.class);
    //then get the sequence
    Sequence s = pm.getSequence(ARTICLE_SEQ);

  16. All extensions
  17. This section is a summary of the previous ones. It enumerates (alphabetic order) all extensions available in Speedo.

    Extension name node level
    element-sql-name Map orCollection fields mapping
    element-sql-type Map or Collection fields mapping
    field-converter Primitive fields mapping
    id Class Mapping
    index-sql-name Map or List fields mapping
    index-sql-type Map or List fields mapping
    inheritance-filter Class Mapping
    inheritance-key Class Mapping
    inheritance-mapping Class Mapping
    join-table Map or Collection fields mapping
    key-field Map fields mapping
    scale Primitive fields mapping
    size Primitive fields mapping
    source-foreign-keys Reference, Collection or Map fields mapping, the foreign key declaraction
    sql-name Class Mapping or Primitive fields mapping
    sql-seq-name Class Mapping
    sql-seq-start Class Mapping
    sql-seq-increment Class Mapping
    sql-seq-cache Class Mapping
    sql-type Primitive fields mapping
    reverse-field Reference, Collection, or Map fields mapping, the foreign key declaraction
    target-foreign-keys Reference, Collection or Map fields mapping, the foreign key declaraction