Helma Logo
main list history
previous version  overview  next version

Version 31 by Philipp on 27. October 2009, 09:54

To store your HopObjects into a relational database system you need to define a database mapping. This is done in the type.properties files located in the persistent  HopObject's prototype directory (e.g. apps/myApp/MyPrototype). The type.properties files contain no JDBC connection information, which is located in the db.properties file in the Helma installation directory or in the application directory.

=== Configuration Settings ===

==== Database related ====
_db = datasourceName

The _db entry describes the database source to use for managing objects of this type. datasourcename is the connection's name defined in the db.properties, which is located in Helma’s installation directory or the application directory. The db.properties file contains information about the JDBC connections, like the JDBC driver, the connection URL and the database username and password.

_table = TABLENAME

The _table entry tells Helma which table to use for objects of this type within the database. To avoid problems with reserved words of SQL or your database system you should prefix your table names. (e.g. T_Story for the Story prototype’s table)

_prototype = PROTOTYPE_COLUMN_NAME

Extended prototypes are usually stored in the same relational database table. Thus, Helma needs a way to tell which row in the table should be instantiated with which object prototype. This is done using the _prototype entry, specifying a column in the table containing the name of the prototype for each row.

<% this.image name="typeproperties_prototype.png" %>

This picture shows a database table where Animals and Dogs could be stored. A Dog is a sub-prototype of the Animal prototype. It inherits every property from the Animal and defines two new properties called "Breed" and "Color".

<% this.image name="typeproperties_prototype_helma.png" %>

Note: The Dog’s type.properties just defines the two new properties. All other stuff will be inherited from the Animal.

_extensionId = String or Integer

If you extend a prototype, Helma will use the name of the sub-prototype as value for the _prototype database column. This could slow down the performance. Better would be to choose a numeric value, which result faster index retrievals and queries. You can define this numeric value in the _extensionId property of the sub-prototype.

Example: If Helma needs all cats, the db-layer can filter all animals with the value '260486'. The value '260486' is defined in the cat’s type.properties as _extensionId! For dogs the _extensionId is set to a 'dogu dugu' string. Animals’ type.properties defines no _extensionId, so Helma uses the prototype’s name, which is 'Animal'!

<% this.image name="typeproperties_prototype_extensionid.png" %>

Download the animal demo application:
<% this.attachments %>

_name = NAME_COLUMN

The optional _name entry tells Helma which database column to use as object name. This is important for the user prototype, since it defines which column constitutes the user name. This field is only used by the session.login(name, pw)/app.registerUser(name, pw) functionality!


==== Inheritance ====

_extends = Prototype

The _extends entry engages Helma to inherit properties, functions and skins from another prototype. This can be compared to Java’s subclassing mechanism.

For example could be a Dog's _extends value the Animal, which inherits to the Dog prototype basic properties like father or mother, some skins and standard functions like getBiologicalClassification()

==== Object Management ====

_id = primaryKeyColumnName

The _id entry defines the column to use as primary key. Helma requires a single primary key with no other functionality. You can read this unique ID from the _id-property of the HopObject.

_parent = localPropertyName, localProperty.parentsCollectionName, root.collectionName

The _parent entry contains a comma-separated list of properties of objects of this type to be used as parent. Objects must know their parent in order to generate correct URLs in their href() function. If a property in the list is null, Helma will look on the following one to fetch a parent object.

If an entry in the _parent item does not contain a dot, it is interpreted as an object property of the current object that acts as the object's parent. If an entry contains a dot character, the part after the dot is interpreted as a collection in the parent object in which the current object is contained. Alternatively or additionally, a second or third dot separated part may indicate an object reference instead or in addition to a collection or mountpoint. If the _parent is specified as "root", it is not interpreted as a property of the current object. Instead, the application's root object is used as parent object.

The _parent entry solves a very specific problem: HopObjects do not know their canonical URLs if you call the href() function, since they can be members of more than one collection.

Example: James Nachtwey, Steve McCurry and Annie Leibovitz are well known photographers. A photographer might work for an agency, so the photographer’s prototype contains a property acency, but if they don’t, it’s null. Nachtwey and McCurry are war photographers, so a root.warphotographers collection cointains both. Leibovitz is neither taking pictures in war zones, nore working for an agency. All photographers are stored in the root’s photographers collection.

The Photographer's types.properties looks like that:
<tt>_parent = root.warphotographers, agency, root.photographers
agency = object(Agency)
</tt>

Helma’s <tt>href()</tt> will look first in the war photographers collection and return an URL like <tt>/warphotographers/nachtwey</tt>, if the person is member of this. Now you call <tt>href()</tt> on the object Annie Leibovitz. She isn’t member of warphotographers, her agency property is null, but she is member of root.photographers, so <tt>href()</tt> will return <tt>/photographers/leibovitz</tt>.

_children

It is used to define a HopObject itself as a collection. The keyword _children acts like a normal property, so you can use all of the collection specifications when defining the collection.

=== Simple Properties ===

simplePropertyName = DB_COLUMN_NAME

A simple property maps a property name of the object to a column of the database table. The type of the table's column need not be specified. Helma does all necessary conversion when reading or writing a property value.

simplePropertyName.readonly = true

Makes the property read only and initializes it with the value from the database.

simplePropertyName.private = true

The private flag forces Helma to update this column only in the database, but prevents any updates on collections and references containing the modified object.

=== Referenced Objects ===
obj = object(SomeHopObject)

obj.local
 
obj.foreign

obj.local.X

obj.foreign.X

obj.logicalOperator

=== Collections ===

coll = collection(SomeHopObject)

coll.local

coll.foreign

coll.loadmode

coll.cachemode

coll.order

coll.filter

coll.filter.additionalTables

coll.hints

coll.maxSize

coll.accessname

coll.group

coll.group.order

coll.group.prototype

=== Mountpoints ===

moutpointName = mountpoint(SomeTransientHopObject)

     removed
     added