Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Teneo/Hibernate/Configuration Options
Contents
The options described here are all present in the org.eclipse.emf.teneo.PersistenceOptions class.
For controlling the naming of tables/columns/foreign keys in more detail use the SqlNameStrategy extension point.
For detailed control of entity naming use the EntityNameStrategy extension point.
For a description of auditing options see the auditing page.
Passing/Setting Configuration Options
Options are passed to the HbDataStore using a Properties object which is set using the HbDataStore.setProperties method.
For programmatic setting of properties:
- Use the static members in the org.eclipse.emf.teneo.PersistenceOptions class.
- All properties are considered to be passed as a String, Boolean options should be set to the lower case String values: "false" or "true".
In the CDO Hibernate Store the configuration options are set in the cdo-server.xml.
SQL Naming Related Options
The tables shown below gives the following information:
- Property: the name of the property as it can be set in a properties file or configuration file.
- Default: all properties should be passed in as expect string values, so the default value should be read/considered as a String.
- Description: describes the option.
(*) because of backward compatibility some properties do not have a teneo.* prefix.
| Property | Default | Description |
|---|---|---|
| teneo.naming.discriminator_column_name | DTYPE | the column name used for the discriminator column |
| econtainer_class_column (*) | econtainer_class | the column used to store the class of the id of the econtainer |
| e_container_column (*) | e_container | the column used to store the id of the econtainer |
| e_container_feature_name_column (*) | e_container_feature_name | the column used to store the feature name of the containment feature |
| teneo.naming.auto_adapt_manual_set_sql_names | true | should manual set names be truncated or upper-lower cased, the default is true because of backward compatibility. |
| teneo.naming.idbag_id_column_name | ID | is used to set the id column name in the join table containing the idbag elements |
| teneo.naming.default_id_column | e_id | can be used to set the id column name which is used to store the id of an object. The id column is only added automatically if the model does not define a primary key for the type. Default the id column name is e_id, however not all databases support _ in the name. |
| teneo.naming.max_sql_name_length | -1, no maximum | 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. |
| teneo.naming.set_foreign_key_name | true | if this option is true then Teneo will also generate descriptive names of the foreign key relations. If this option is false then Hibernate will take care of foreign key naming. However these names can be too long or are less meaningfull. Note when setting this property to true it is possible that foreign key names will be the same as table names, this can give issues in Postgresql (and maybe other database also). To prevent this, set the sql_fk_name_prefix option also. |
| teneo.naming.strategy | lowercase | 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. |
| teneo.naming.sql_name_escape_character | ` (the backquote character) |
Teneo will escape table and column names (see here). As a default the ` backtick character is used. This option allows you to change the escape character or disable it by setting it to an empty string. |
| teneo.naming.sql_column_name_prefix | Sets the prefix of all column names (including join column names). | |
| teneo.naming.sql_fk_name_prefix | Sets the prefix of all foreign key names, only relevant if foreign key names are generated by Teneo (see the set_foreign_key_name option). | |
| teneo.naming.sql_index_name_prefix | Sets the prefix of all generated index names, only relevant if indexes are generated by Teneo for foreign key references (see the add_index_for_fk option). | |
| teneo.naming.sql_table_name_prefix | Sets the prefix of all table names (including join table names). | |
| teneo.naming.version_column | e_version | 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
| Property | Default | Description |
|---|---|---|
| teneo.mapping.add_index_for_fk | false | there are databases which do not automatically create an index for a foreign key relation. This option (default is false) forces Teneo to explicitly set an index for each foreign key relation. The index name will be generated by Teneo.
Note that generated index names can be the same as table names, this can give issues in Postgresql (and maybe other database also). To prevent this, set the sql_index_name_prefix option also. |
| teneo.mapping.always_map_list_as_bag | false | often modeling the index of a list in a relational database is not usefull. This option controls if al lists are mapped as a Hibernate bag. This is more efficient as Hibernate does not need to maintain an ordering in the database. Note that if you specified a manual OneToMany annotation on an EReference then for that EReference the settings on the onetomany are followed. |
| teneo.mapping.always_version | true | this option (boolean) 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. |
| teneo.mapping.also_map_as_class | true | this option will add a name attribute to each class mapping. This makes it possible to query using actual class and interface names (next to the entityname). |
| teneo.mapping.auto_add_referenced_epackages | false | if set to true then Teneo will automatically add EPackages, which are referenced from the EPackages registered for a data store, to that datastore. |
| teneo.mapping.cascade_policy_on_containment | ALL | Can be used to set custom cascade policy for containment : ALL or a combination of REMOVE, REFRESH, PERSIST, MERGE. For example: REMOVE,PERSIST,MERGE. Note: ALL != REMOVE,REFRESH,PERSIST,MERGE. However, ALL == REMOVE with delete Orphan, REFRESH,PERSIST,MERGE |
| teneo.mapping.cascade_policy_on_non_containment | this option allows you to set the default cascade policy for non containment relations. It can be set to a comma delimited set of cascade values, for example MERGE, PERSIST, REFRESH. If this option is not set then then the system will use the following set: MERGE, PERSIST, REFRESH. | |
| teneo.runtime.convert_unset_to_null | false | if true then an unset eAttribute is stored as null in the database, when reading the null is again used as the EAttribute value of the object (unless the handle_unset_as_null option is set, see below).
NOTE: DEPRECATED has the same behavior as the handle_unset_as_null option, use that option. |
| teneo.mapping.default_cache_strategy | NONE | this option allows you to set second level caching at a global level. If set to a value other than NONE then all EClasses and collection EFeatures will have caching set. The value is one of NONE, READ_ONLY, NONSTRICT_READ_WRITE, READ_WRITE, TRANSACTIONAL. |
| teneo.mapping.default_id_feature | e_id | 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. |
| teneo.mapping.default_temporal | TIMESTAMP | 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. |
| teneo.mapping.default_varchar_length | 255 (default by Hibernate) | as a default Hibernate will use a length of 255 for varchar columns. This option makes it possible to choose another default length. Note that it is also possible to set the length for each individual Column/EFeature using the @Column annotation. |
| teneo.mapping.disable_econtainer | false | this option (boolean) controls if the container relations are mapped explicitly in the database, see also here. |
| teneo.mapping.eav_mapping | false | If set to true then the system will map all eclasses as an EAV mapping. See Entity Attribute Value mapping. |
| teneo.mapping.eav_location | this option (string) controls which mapping file is used to create the EAV database schema. If not set then the org.eclipse.emf.teneo.hibernate.mapping.eav.eav.hbm.xml is used. The value is resolved as a class path against the PersistenceFileProvider class. | |
| teneo.runtime.elist_efficient_size_operation | false | this option (boolean) controls if the size operation on an elist will load the elist (if option is false) or perform a separate query for computing the size (if the option is true). The option is set to false for backward compatibility. |
| teneo.mapping.emap_as_true_map | true | this option controls how an EMF EMap is mapped to the db. An EMF EMap is not a real map but a list of map entries (subtle but important difference). It can be mapped to the database as a list or as a map. In previous releases of Teneo the EMap was mapped as a list. However, this is less efficient and does not work in cases that the data needs to be serialized (because the list content was stored with a synthetic id which is not supported in case of serialization). Therefor now the default approach is to map an EMap as a true Hibernate map. To support backward compatibility this option is introduced. Its default is true (use the new approach), by setting it to "false" the old approach is followed. |
| teneo.mapping.extra_annotation_sources | as a default Teneo will only use model annotations with a source equal to teneo.jpa (see here). This option allows you to specify extra annotation sources which are considered. This makes it possible to work with different annotation sets in your model and disable or enable them (using this option) when required. | |
| teneo.mapping.extra_annotations_overrides_default | Default is false, if true will consider the extra annotation source(s) as overriding the default annotations, so if a model element has an annotation with a source specified in the extra_annotation_sources then the eannotations with the default sources is not used. | |
| teneo.mapping.featuremap_as_component | false | if set to "true" will map a feature map entry as a Hibernate component without its own id. If set to false then a feature map entry will be mapped as a separate entity. |
| teneo.mapping.fetch_containment_eagerly | false | 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". |
| teneo.mapping.fetch_one_to_many_extra_lazy | false | if set to "true" will set all associations to be extra-lazy, this means that for common collection operations the list is not loaded completely in memory but separate calls to the database are done. For more information see this wiki page. |
| teneo.runtime.handle_unset_as_null | false in Teneo, true in the CDO Hibernate Store | if false then always the value of the EAttribute is stored eventhough the EAttribute is not set (unset==true), reading an object from the database will always set the value if it has a default. If true then if the EAttribute value is not set on an EObject then null is set in the database and when reading the object from the database the EAttribute remains not-set. |
| teneo.naming.id_feature_as_primary_key | true | 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. |
| teneo.mapping.ignore_eannotations | false | Ignore mapping EAnnotations. Primarily meant for test cases that use Persistence XML mapping, so that they can reuse the same sample models. |
| teneo.mapping.inheritance | SINGLE_TABLE | the default inheritance mapping strategy to use, this can be JOINED or SINGLE_TABLE, see here for more information. |
| teneo.mapping.join_table_for_non_contained_associations | true | boolean, if set to true then always a join table is created for one-to-many non-contained associations. |
| teneo.mapping.map_all_lists_as_idbag | false | the Hibernate idbag maps a list as a very efficient bag in which each list entry gets an id. This makes it possible to update the list very efficiently. This option allows you to force Teneo to use the idbag for all lists. Note that if you specified a manual OneToMany annotation on an EReference then for that EReference no IdBag annotation is added. Also it makes sense to combine this option with setting the option JOIN_TABLE_FOR_NON_CONTAINED_ASSOCIATIONS to true also. Note, there is an issue with Derby and IDBAG, see here. |
| teneo.mapping.map_document_root | false | the option controls if Teneo should support persisting the very generic DocumentRoot EClass which is generated when EMF encounters global elements which are not complex types. |
| teneo.mapping.map_embeddable_as_embedded | false | if set to true then an EReference to an EClass which is annotated with @Embeddable will automatically be annotated with @Embedded. If false (the default) then an EReference to an embeddable EClass needs to be manually annotated with @Embedded. |
| teneo.mapping.mapping_file_name | with this option you can specify one or more comma-delimited resource paths (incl. filename) to a mapping file. Instead of generating a mapping Teneo will then use the mapping file found through this path. | |
| teneo.mapping.force_lazy | false | will set lazy="true" on an entity without setting the proxy attribute, hibernate will use the implementation class itself as the proxy class. When setting this option then the set_proxy option should not be used. |
| teneo.mapping.max_comment_length | 0 | comments in the model can be copied to the mapping file. This option sets the maximum length of these comments, the default specifies the maximum length with this option you can specify a resource path (incl. filename) to a mapping file. Instead of generating a mapping Teneo will then use the mapping file found through this path. |
| teneo.mapping.optimistic_locking | true | if this property is "false" then no version properties are added to the mapping of EClasses. |
| teneo.mapping.persistence_xml | the location of the xml annotations file. The location should be a resource path. | |
| teneo.mapping.set_entity_automatically | true | 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. |
| teneo.mapping.set_generated_value_on_id_feature | true | 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. |
| teneo.mapping.set_proxy | false | this option controls if Hibernate will use a cglib/javaassist proxy when loading objects for many-to-one/one-to-one relations. If set to true then Teneo will automatically add a @Proxy annotation to each type. In addition the fetch of the many-to-one and one-to-one is set to LAZY (if not set by the user). If this option is false then for individual types the @Proxy annotation can also be used (see the Hibernate annotation extensions).
See also the force_lazy option above, when using the force_lazy option, the set_proxy option should not be set (it should be false). |
| teneo.mapping.hibernate_mapping_file | false | if set to "true" then Teneo will not do an automatic mapping of the ecore model to Hibernate but instead search for a hibernate.hbm.xml in the classpath of the EMF generated java classes. |
System property: Identifier Cache Handling/Purging
Teneo keeps an internal weak-reference map for caching id's and versions of objects. The map is purged for stale references every 60 seconds. You can control the interval by passing the following system property: org.eclipse.teneo.hibernate.identifierPurgingLogTimeThreshold: interval in seconds by which purging should happen.
A number of options are related to handling a specific issue with the XMLGregorianCalendar implementation in different java-providers. See bugzilla 227673.
The options are teneo.mapping.UserDateType, teneo.mapping.UserDateTimeType and teneo.mapping.XSDDateClass.
The first two options define which usertype is used when generating the hibernate mapping for xsddate/xsddatetime types. The last option defines the actual class used for the date instance, the default is javax.xml.datatype.XMLGregorianCalendar.