HomeEMF HibernateEMF JDO/JPOXWeb App GenerationServices
 

JpoxDataStore, JpoxHelper, Runtime options

The JpoxDataStore

The JpoxDataStore object controls the persistence of a set of EPackage in a specific relational database. The JpoxDataStore contains a PersistenceManagerFactory and is responsible for creating and updating the database schema.

A JpoxDataStore is created through the JpoxHelper.INSTANCE.createRegisterDataStore method. After creating a JpoxDataStore two methods should be called: setEPackages which set the EPackages handled by this JpoxDataStore and setProperties which sets the JPOX database connection information.

The next important method is the initialize method which configures JPOX, creates the database schema and a PersistenceManagerFactory.

After the JpoxDataStore is created it can be used to retrieve JDO PersistenceManagers using the getPersistenceManager method.

The JpoxDataStore can also be used to import and export xml and xmi through the importDataStore and exportDataStore methods.

The JpoxDataStore has a specific method to retrieve all referers to a passed EObject: getCrossReferencers. The getContainer method will return the container of a specific EObject.

The JpoxHelper

The JpoxHelper is responsible for creating and registering a JpoxDataStore and offers a number of convenience methods. To get access to the JpoxHelper functionality you need to use the JpoxHelper.INSTANCE object. In addition the JpoxHelper allows you to register a PMFCreator.

The PMFCreator is called by Teneo to create a PersistenceManagerFactory. By registering your own PersistenceManagerFactoryCreator, you can override the creation of persistence managers etc.

The persistence manager factory creator should implement the interface: org.eclipse.emf.teneo.jpox.PMFCreator. The creator can be registered using the method JpoxHelper.INSTANCE.setPMFCreator(....).

Programmatic generation of package.jdo

The JpoxHelper.INSTANCE also offers a method (generateMapping(...)) to programmatically generate a package.jdo file for one or more epackages. This can be usefull in case you encounter issues or need to map multiple epackages. This method allows you also to specify the options which can not be set when using the standard menu option:

  • PersistenceOptions.SET_ENTITY_AUTOMATICALLY : if set to "false" then only EClasses which have an Entity annotation will be mapped. Default is "true", this means that all EClasses are mapped to the persistent store.
  • PersistenceOptions.SQL_CASE_STRATEGY : controls if the table and column names are uppercased, lowercased or no specific casing is done. The value lowercase will force lower case for all table/column name, the value uppercase will force uppercase for all table/column names, none wil do not casing. It is also possible to set this option to the classname of a class implementing the org.eclipse.emf.teneo.util.SQLCaseStrategy interface. Note this option can only be used when generating the package.jdo programmatically.

The available options are all present in the org.eclipse.emf.teneo.PersistenceOptions class.

Runtime Options

Runtime options are passed to the JpoxDataStore using a Properties object which is set using the JpoxDataStore.setProperties method.

The options described here are all present in the org.eclipse.emf.teneo.PersistenceOptions class. The constant names used in this page all refer to this class.

Boolean options can have the lower case String values: "false" or "true".

  • PersistenceOptions.UPDATE_SCHEMA : if set to "false" then the database schema is not updated when initializing a JpoxDataStore. This improves startup times. Default is "true".

Mapping Options

Mapping options only apply if you programmatically generate a jdo file. This can be done through the JpoxHelper.generateMapping method.

The options described here are all present in the org.eclipse.emf.teneo.PersistenceOptions class. The constant names used in this page all refer to this class.

Boolean options can have the lower case String values: "false" or "true".

SQL Naming Related Options

A number of options are related to the naming logic for table and columns names. The logic can be controlled by setting the following options or by registering your own extension (see here).

  • PersistenceOptions.JOIN_COLUMN_NAMING_STRATEGY : Join column naming strategy, two values: unique and simple. unique is the default and results in guaranteed unique naming for the join columns simple will always try to use minimal name lengths and will most of the time just use the efeaturename.
  • PersistenceOptions.JOIN_TABLE_NAMING_STRATEGY : string option which can have two values: ejb3 or unique (=default). In ejb3 a join table name is the concatenation of the two entity names with an underscore (_) separator. The unique value will create a join table with the name of the refering entity name and estructural feature name, e.g. Writer_books in the Library example.
  • PersistenceOptions.MAXIMUM_SQL_NAME_LENGTH : can be used to control the column and table name length. This is especially relevant in case the default annotation process creates foreign key columns or your property names are too long. Foreign key column names are created by concatenating the name of the (e)class and the propertyname. The resulting name can be to long for certain databases. By setting this option the system will truncate column names to this length. If the column/table name has a suffix (separated by a _) then the system will truncate the part before the suffix.
  • PersistenceOptions.SET_FOREIGN_KEY_NAME : the default is false, if this option is set to true then Teneo will also generate descriptive names of the foreign key relations. If this option is false (the default) then Hibernate will take care of foreign key naming. However these names can be too long or are less meaningfull.
  • PersistenceOptions.SQL_CASE_STRATEGY : controls if the table and column names are uppercased, lowercased or no specific casing is done. The value lowercase will force lower case for all table/column name, the value uppercase will force uppercase for all table/column names, none wil do not casing. It is also possible to set this option to the classname of a class implementing the org.eclipse.emf.teneo.util.SQLCaseStrategy interface.
  • PersistenceOptions.VERSION_COLUMN_NAME : can be used to set the version column name which is used to store the version of an object in case of optimistic locking. Default the version column name is e_version, however not all databases support _ in the name.

General Options

  • PersistenceOptions.ALWAYS_VERSION : this option (boolean, default: true) determines if the system should automatically add a version attribute to each class mapping. If set to true (the default) then the system will add a version property to the mapping if no other eattribute has a version annotation. If set to false then the version property is not added automatically.
  • PersistenceOptions.DEFAULT_ID_FEATURE_NAME : with this option it is possible to let Teneo automatically identify the id-property. All efeatures with this name are used as persistence id. The default value is e_id (same as for the default id column name). To ensure that no efeature is by accident considered as the id-feature this should be set to an empty string.
  • PersistenceOptions.DEFAULT_TEMPORAL_VALUE : this option controls the default mapping to use for temporal (e.g. java.util.Date) properties. The default is TIMESTAMP, other allowed values are DATE, TIME.
  • PersistenceOptions.FETCH_CONTAINMENT_EAGERLY : if set to "true" will set the fetch strategy of all containment references to EAGER. This means that containment relations are completely read in memory. Default is "false".
  • PersistenceOptions.ID_FEATURE_AS_PRIMARY_KEY : as a default eattributes with ID=true will be denoted as the primary key of the eclass. If this feature (default is true) is set to false then this default behavior is disabled.
  • PersistenceOptions.INHERITANCE_MAPPING : the default inheritance mapping strategy to use, this can be JOINED or SINGLE_TABLE, see here for more information. Default is SINGLE_TABLE.
  • PersistenceOptions.JOIN_TABLE_FOR_NON_CONTAINED_ASSOCIATIONS (default: true) : boolean, if set to true then always a join table is created for one-to-many non-contained associations.
  • PersistenceOptions.PERSISTENCE_XML : the location of the xml annotations file. The location should be a resource path.
  • PersistenceOptions.SET_CASCADE_ALL_ON_CONTAINMENT : as a default Teneo will set a cascade style ALL on a containment relation. This also enables dependent or orphan delete behavior. This option can be used to control the dependent or orphan delete behavior on a containment relation. If set to false then all cascade styles are set with dependent/orphan-delete disabled. If set to true (the default) then all cascade styles are set including orphan-delete/dependent.
  • PersistenceOptions.SET_DEFAULT_CASCADE_ON_NON_CONTAINMENT : this option controls if Teneo will set the cascade attribute on a non-containment relation. The default value is false, as normally non-contained objects are persisted independently. Cascading on an association has a performance penaly and therefore as a generatl statement this should only be done if really required.
  • PersistenceOptions.SET_ENTITY_AUTOMATICALLY : if set to "false" then only EClasses which have an Entity annotation will be mapped. Default is "true", this means that all EClasses are mapped to the persistent store.
  • PersistenceOptions.SET_GENERATED_VALUE_ON_ID_FEATURE : only applies if ID_FEATURE_AS_PRIMARY_KEY is true (which is the default). This option forces Teneo to also add a generator tag (with class="native") to the id tag. This is only done for EAttributes which have ID="true" and only if ID_FEATURE_AS_PRIMARY_KEY is true and no manual @Id annotation was set on the EAttribute.