From Eigenpedia

Jump to: navigation, search

Presently this page is relatively un-organized and was serving as a place holder for a better document containing a list of caveats that Farrago extension projects will need to look out for. See EnkiBestPractices.


Enki sessions

A consequence of using Hibernate as a storage layer for models is that more explicit repository session management is necessary. See the methods beginSession() and endSession() in org.eigenbase.enki.mdr.EnkiMDRepository. If multiple transactions intend to use the same repository object instances, they must be encapsulated within a single repository session. Model objects can be passed across sessions via MOF ID.

Beware performance implications of the getByMofId() query!

  • Session do not automatically span thread boundaries. Do not load a repository object in one thread and expect to use it in another thread. If multi-threaded access is required, use detachSession() and reattachSession() in org.eigenbase.enki.mdr.EnkiMDRepository to explicitly transfer the session from one thread to another.
  • Sessions should be as short-lived as possible. Once a session is used to manipulate a repository object, it should be assumed to represent an open connection to the repository database. Note, however, that beginning a session does not cause such a connection to be created or allocated. The Enki repository session maps directly to a Hibernate session.

Enki transactions

Enki/Hibernate does not support implicit MDR write transactions. The MDR API specifies these as being auto-commit. E.g, a transaction is create and commited for each write to an MDR model object. Enki/Hibernate will instead throw an exception. Wrap all writes in an explicit MDRepository.beginTrans(true)/endTrans() pair.

  • This is really a Farrago issue, but it's related. Farrago DdlStmt instance with runAsDml() were found to be executing without an MDR transaction. Execution will be modified to provide provide transaction semantics. Classes that derive from DdlAlterStmt (particularly through DdlAlterGenericStmt), DdlTruncationStmt, or DdlAnalyzeStmt will be affected. In particular, no long-running work should be performed in DdlStmt.preValidate()).

Catalog Manipulation

Catalog backup and restore should be performed using the farrago/buildMacros.xml targets backupCatalog and restoreCatalog. These targets automatically handle the distinction between HSQLDB storage (just copies files) and Hibernate/mysql storage (invokes mysqldump/mysql to create/restore backup files). It is not sufficient to simply copy the contents of a catalog backup into a catalog directory.

Metadata Object

Because of the way that Hibernate performs lazy loading, it is possible for the same metadata object to be represented as two different instances in the same transaction. This can occur if the object is loaded lazily via an association and then subsequently accessed directly by MOF ID. For a FemLocalTable, the lazily loaded instance will be an instance of a Hibernate-generated proxy class named something like FemLocalTable$Impl$$EnhancerByCGLIB$$546c468. It extends FemLocalTable$Impl and only loads the details of the table if they are actually accessed. The directly accessed version will simply be an instance of type FemLocalTable$Impl. The objects contain the same data and can be used interchangeably, but they are not identical references. This results in the following prohibition:

  • Do not use identity equality (e.g, the == or != operators) to compare metadata objects. Use Object.equals(Object) instead.

FindBugs Plugin

See EnkiFindBugsPlugin.


The iteration order of unordered associations varies between Netbeans and Enki/Hibernate. Do not depend on the iteration order of unordered associations even if it is stable across runs in Netbeans.

Personal tools