Unique Database Object Identifiers

In C and C++ applications, an oid can be declared for the database and used to quickly retrieve the object it identifies. The oid values are assigned by the applications but must be unique within all classes in the database and uniqueness is enforced during object creation by the eXtremeDB runtime. Alternatively, C/C++ and all other native language APIs, can use an autoid to uniquely identify objects. The autoid is a guaranteed unique value generated by the eXtremeDB runtime.

C API

If an oid is declared for the database, the schema compiler generates a C structure corresponding to the structure defining the oid. For instance, for a schema containing an oid declaration like the following:

 
    struct structname
    {
        uint4 num_in;
    };
    declare oid structname[10000];
     

the schema compiler will generate the following definitions and functions:

 
    typedef struct databasename_oid__ 
    {
        uint4           num_in;
    }
    databasename_oid;
 
    static const uint2 databasename_oid_size = sizeof(databasename_oid);
 
    MCO_RET  databasename_delete_object( /*IN*/ mco_trans_h t,
                        /*IN*/ const databasename_oid * oid );
 
    MCO_RET databasename_get_class_code( /*IN*/ mco_trans_h t,
                        /*IN*/ const databasename_oid * oid,
                        /*OUT*/ uint2 *classcode );
                         

Note the prepended databasename in these definitions. This evidences the fact that only one oid can be defined for a given database and uniqueness for all values of that oid will be enforced by the runtime. The databasename_delete_object() function deletes an object based on its oid. The databasename_get_class_code() function returns an integer that identifies the class of the object referenced by the specified oid value.

For classes containing an oid, the following two functions are generated to locate an object based on its oid and to extract the oid of an object;

 
    MCO_RET classname_oid_find( /*IN*/ mco_trans_h t,
                    /*IN*/ const databasename_oid *id,
                    /*OUT*/ classname *handle );
 
    MCO_RET  classname_oid_get( /*IN*/ classname *handle,
                    /*OUT*/ databasename_oid *id );
                     

(Note that the oid feature checks uniqueness of the key before creation of the class instance. Normally the uniqueness of a key is tested on the transaction commit.)

The oid feature is not supported in the C# and Java API. So C# and Java applications use other methods such as autoid and unique indexes for object identifiers.

Autoids

The autoid is a guaranteed unique value generated by the eXtremeDB runtime. For C and C++ applications, the autoid is declared within the DDL class definition with a specified number of estimated objects of that class. When a class is declared to have an autoid, the schema compiler will generate the following two functions for the class:

 
    MCO_RET classname_autoid_find( /*IN*/ mco_trans_h t,
                    /*IN*/ autoid_t id,
                    /*OUT*/ classname *handle );
 
    MCO_RET classname_autoid_get( /*IN*/ classname *handle,
                    /*OUT*/ autoid_t *id );
                     

Applications can retrieve the autoid value with the classname_autoid_get() function. An autoid value, whether stored in a program variable or a field of another database object as a reference, can be used in the classname_autoid_find() function to locate the referenced object.

The autoid is defined in Java and C# classes with the Persistent annotation or attribute, for example:

 
    Java:
                
     
    @Persistent(autoid=true)
    class Record
    {
        ...
    }
     
    C#:
     
    [Persistent(AutoID=true)]
    class Record
    {
        ...
    }
     

When an object of a class with an autoid is created, the runtime generates a unique autoid for the object. The autoid of an object can be retrieved with the Cursor method GetAutoid() and the object with a specified autoid can be searched in the database using the Cursor method Find().

Note that the addition of an oid or autoid causes the eXtremeDB runtime to maintain an internal hash index that grows with the addition of database objects. As this hash index grows it may affect overall database performance.