Difference between revisions of "Teneo/Hibernate/Configuration Options"

Revision as of 19:29, 22 January 2010

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.

Options are passed to the HbDataStore using a Properties object which is set using the HbDataStore.setProperties method.

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

The option QUALIFY_ENTITY_NAME has been removed and is now handled through setting the EntityNameStrategy extension, see here .

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).

(*) because of backward compatibility some properties do not have a prefix.

• PersistenceOptions.JOIN_COLUMN_NAMING_STRATEGY (default: unique): 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 (default: unique): 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 (default: -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.

• PersistenceOptions.MAP_EMBEDDABLE_AS_EMBEDDED (default: 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.

• PersistenceOptions.SET_FOREIGN_KEY_NAME (default: true): if this option is 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 (default: 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.

• PersistenceOptions.SQL_NAME_ESCAPE_CHARACTER (default: `): 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.

• PersistenceOptions.SQL_COLUMN_NAME_PREFIX (default: ""): Sets the prefix of all column names (including join column names).

• PersistenceOptions.SQL_FOREIGN_KEY_NAME_PREFIX (default: ""): Sets the prefix of all foreign key names.

• PersistenceOptions.SQL_TABLE_NAME_PREFIX (default: ""): Sets the prefix of all table names (including join table names).

• PersistenceOptions.VERSION_COLUMN_NAME (default: 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

• PersistenceOptions.ADD_INDEX_FOR_FOREIGN_KEY (default: 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.

• PersistenceOptions.ALWAYS_MAP_LIST_AS_BAG (default: 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.

• PersistenceOptions.ALWAYS_VERSION (default: 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.

• PersistenceOptions.ALSO_MAP_AS_CLASS (default: 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).

• PersistenceOptions.AUTO_ADD_REFERENCED_EPACKAGES (default: 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.

• PersistenceOptions.CASCADE_POLICY_ON_NON_CONTAINMENT (default: not set): 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.

• PersistenceOptions.DEFAULT_CACHE_STRATEGY (default: 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.

• PersistenceOptions.DEFAULT_ID_FEATURE_NAME (default: 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.

• PersistenceOptions.DEFAULT_TEMPORAL_VALUE (default: 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.

• PersistenceOptions.DEFAULT_VARCHAR_LENGTH (default: 255 set 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.

• PersistenceOptions.DISABLE_ECONTAINER_MAPPING (default: false): this option (boolean) controls if the container relations are mapped explicitly in the database, see also here.

• PersistenceOptions.EAV_MAPPING (default: false): this option (boolean) controls if all types are mapped using an EAV schema. See the description here.

• PersistenceOptions.EAV_MAPPING_FILE (default: null): 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.

• PersistenceOptions.ECONTAINER_FEATURE_PERSISTENCE_STRATEGY (default: featurename): this option determines how the eContainerFeatureID member of an EObject is persisted. There are three possible values:

• • featurename: the feature name of the containment feature is stored. This is the preferred value.

• • featureid: this value is there for backward compatibility, the id of the containment feature is stored, however this value is not stable when the model changes. This value is not recommended.

• • both: both the featurename and featureid are stored. This is for cases in which both the old and the new situation need to be supported. This is recommended when converting from an old (featureid) to a new approach (using featurenames). For a possible conversion approach see here.

• PersistenceOptions.EMAP_AS_TRUE_MAP (default: 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.

• PersistenceOptions.EXTRA_ANNOTATION_SOURCES (default: empty string): 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.

• PersistenceOptions.FEATUREMAP_AS_COMPONENT (default: 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.

• PersistenceOptions.FETCH_CONTAINMENT_EAGERLY (default: 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".

• PersistenceOptions.HANDLE_UNSET_AS_NULL (default: false): 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.

• PersistenceOptions.ID_FEATURE_AS_PRIMARY_KEY (default: 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.

• PersistenceOptions.INHERITANCE_MAPPING (default: SINGLE_TABLE): the default inheritance mapping strategy to use, this can be JOINED or SINGLE_TABLE, see here for more information.

• 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.MAP_DOCUMENT_ROOT (default: 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.

• PersistenceOptions.MAP_ALL_LISTS_AS_IDBAG (default: 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.

• PersistenceOptions.MAPPING_FILE_PATH (default: null): 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.

• PersistenceOptions.MAX_COMMENT_LENGTH (default: 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.

• PersistenceOptions.OPTIMISTIC (default: true): if this property is "false" then no version properties are added to the mapping of EClasses.

• PersistenceOptions.PERSISTENCE_XML (default: ""): the location of the xml annotations file. The location should be a resource path.

• PersistenceOptions.SET_CASCADE_ALL_ON_CONTAINMENT (default: false): this option is deprecated use CASCADE_POLICY_ON_CONTAINMENT instead. as a default Teneo will set a cascade style ALL on a containment relation. This also enables dependent or orphan delete behavior. However it makes more difficult to support cut/paste operations using resources (see here). 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.CASCADE_POLICY_ON_CONTAINMENT (default: ALL): this option allows you to set the default cascade policy for containment relations. It can be set to a comma delimited set of cascade values, for example MERGE, PERSIST, REFRESH, REMOVE.

• PersistenceOptions.SET_DEFAULT_CASCADE_ON_NON_CONTAINMENT (default: false): this option is deprecated use CASCADE_POLICY_ON_NON_CONTAINMENT instead. 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 (default: 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.

• PersistenceOptions.SET_GENERATED_VALUE_ON_ID_FEATURE (default: 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.

• PersistenceOptions.SET_PROXY (default: false): this option controls if Hibernate will use a cglib 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).

• PersistenceOptions.SQL_DISCRIMINATOR_VERSION_IMMUTABLE_ECLASS (default: true): this option controls if a non-mutable class should also have a discriminator and version column. This is not strictly required as instances of non-mutable eclasses are not persisted. From a database schema perspective it can however be nicer to have these columns (as all mutable tables have them).

• PersistenceOptions.UPDATE_SCHEMA: REMOVED : this option is not available anymore, the hibernate option hibernate.hbm2ddl.auto can be used. The default value of the hibernate.hbm2dll_auto option is set to update, if not set by the user.

• PersistenceOptions.USE_MAPPING_FILE (default: 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.

XSDDate implementation class, options: 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 PersistenceOptions.USER_XSDDATE_TYPE, PersistenceOptions.USER_XSDDATETIME_TYPE and PersistenceOptions.XSDDATE_CLASS. 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.