Table of Contents
Table of Contents |
---|
Related Documents:
Entity Engine Configuration Guide
...
Introduction
...
The Open For Business Entity Engine is a set of tools and patterns used to model and manage entity specific data. In this context an entity is a piece of data defined by a set of fields and a set of relations to other entities. This definition comes from the standard Entity-Relation modeling concepts of Relational Database Management Systems. The goal of the entity engine is to simplify the enterprise wide use of entity data. This includes definition, maintenance, quality assurance, and development of entity related functionality.
...
<entity title="Sample Entity"
copyright="Copyright (c) 2001 John Doe Enterprises"
author="John Doe" version="1.0"
package-name="org.ofbiz.commonapp.sample"
entity-name="SampleEntity"
table-name="SAMPLE_ENTITY">
<field name="primaryKeyFieldOne" col-name="PRIMARY_KEY_FIELD_ONE" type="id-ne"></field>
<field name="primaryKeyFieldTwo" type="id-ne"></field>
<field name="fieldOne" type="long-varchar"></field>
<field name="fieldTwo" type="long-varchar"></field>
<field name="foreignKeyOne" type="id"></field>
<prim-key field="primaryKeyFieldOne" />
<prim-key field="primaryKeyFieldTwo" />
<relation type="one" rel-entity-name="OtherSampleEntity">
<key-map field-name="foreignKeyOne" rel-field-name="primaryKeyOne" />
</relation>
<relation type="one" title="Self" rel-entity-name="SampleEntity">
<key-map field-name="primaryKeyFieldOne" />
<key-map field-name="primaryKeyFieldTwo" />
</relation>
<relation type="many" title="AllOne" rel-entity-name="SampleEntity">
<key-map field-name="primaryKeyFieldOne" />
</relation>
</entity>
...
Field types are specified using a type string, which is defined in a fieldtypemodel XML file specified by the fieldtypemodel.dtd XML Data Type Definition. Each type maps to a Java type and an SQL type. Because of this separation different fieldtypemodel XML files can be specified for different databases allowing an entitymodel XML file to work with the various databases. In addition, validators can be specified for a field type or for any field. This denotes that the named validator should be called when data is input. These validators are defined in the class org.ofbiz.base.util.UtilValidate and follow the definition pattern: [boolean isValid(String in);
].
Entity Relationships (relations)
Multiple relationships can exist for each entity. Each relation is either of type 'one', 'one-nofk', or 'many' depending on the cardinality of the relation and whether a foreign key is desired or not. If the type is 'one' or 'one-nofk' then the key-map elements must fully specify the primary key of the related entity. If the type is 'many', the key-map elements are not restricted by the primary key of the related entity.
...
Key Maps are used to define how the related entity will be looked up. Each key map specified a field name (field-name) and a related field name (rel-field-name). If the two column names are the same, the rel-field-name does not have to be specified.
Entity Element Reference
entity
Attribute Name | Required? | Description |
---|---|---|
entity-name | Y | The name of the entity as it is referred to when using the Entity Engine Java API and various other places in the Entity Engine. |
table-name | N | The name of the database table that corresponds to this entity. This attribute is optional and if not specified the table name will be derived from the entity name. |
package-name | Y | The name of the package that this entity is contained in. With hundreds of entities in a large data model this is used to organize and structure the entities definitions. |
dependent-on | N | This can be used to specify a parent entity or an entity that this entity is dependent on. This is currently not used for anything automated in the Entity Engine, but can be used to specify an heirarchical entity structure. |
enable-lock | N | Specifies whether or not optimistic locking should be used for this entity. The lastUpdatedStamp field must exist on the entity and will be used to keep track of the last time the entity instance was updated. If the current instance to be updated does not have a matching lastUpdatedStamp an EntityLockedException will be thrown. Must be true or false. Defaults to false. |
never-cache | N | If this is set to true caching of this entity will not be allowed. Automatic cache clearing will not be done to improve efficiency and any attempt to use the cache methods on the entity will result in an exception so that it is easier to find and eliminate where this is being done. Must be true or false. Defaults to false. |
title | N | A title for the entity. If not specified defaults to the global setting for the file the entity is in. |
copyright | N | The copyright of the entity. If not specified defaults to the global setting for the file the entity is in. |
author | N | The author of the entity. If not specified defaults to the global setting for the file the entity is in. |
version | N | The version of the entity. If not specified defaults to the global setting for the file the entity is in. |
Sub-Element Name | How Many | Description |
---|---|---|
description | 0 or 1 | A description of the entity. If not specified defaults to the global setting for the file the entity is in. This element has no attributes and should contain only a simple string of characters. |
field | 1 to many | Used to declare fields that are part of the entity. |
prim-key | 0 to many | Used to declare which fields are primary keys |
relation | 0 to many | Used to declare relationships between entities. |
field
Attribute Name | Required? | Description |
---|---|---|
name | Y | The name of the field that is used to refer to it in Java code and other places. |
col-name | N | The name of the corresponding database column. This is not required and if not specified this will be derived from the field name. |
type | Y | The type of the field. This is looked up in the field types file for the current datasource at run-time to determine the Java and SQL types for the field and database column. |
Sub-Element Name | How Many | Description |
---|---|---|
validate | 0 to many | Each validate element has a single attribute called name which specifies the name of the validation method to call. These methods are not called in all Entity Engine operations and are only used for generic user interfaces like the Entity Data Maintenance pages in WebTools. |
prim-key
Attribute Name | Required? | Description |
---|---|---|
field | Y | The name of the field that will be part of the primary key. |
relation
Attribute Name | Required? | Description |
---|---|---|
type | Y | Specifies the type of the relationship including the cardinality of the relationship (in one direction) and if a foreign key should be created for cardinality one relationships. Must be "one", "one-nofk", or "many". |
title | N | Because you may want to have more than one relationship to a single entity this attribute allows you to specify a title that will be prepended to the rel-entity-name to make up the name of the relationship. If not specified the rel-entity-name alone will be used as the relationship name. |
rel-entity-name | Y | The name of the related entity. The relationship goes from this entity to the related entity. |
fk-name | N | The foreign key name can be created automatically from the relationship name, but this is not recommended for two reasons: many databases have a very small maximum size (like 18 characters) for foreign key and index names, and many databases require that the FK name be unique for the entire database and not just for the table the FK is coming from. |
Sub-Element Name | How Many | Description |
---|---|---|
key-map | 1 to many | The key-map is used to specify a field in this entity that corresponds to a field in the related entity. This element has two attributes: field-name and rel-field-name. These are used to specify the name of the field on this entity and the corresponding name of the field on the related entity. |
...
<view-entity title="Sample View Entity"
copyright="Copyright (c) 2001 John Doe Enterprises"
author="John Doe" version="1.0"
package-name="org.ofbiz.commonapp.sample"
entity-name="SampleViewEntity">
<member-entity entity-alias="SE" entity-name="SampleEntity" />
<member-entity entity-alias="OSE" entity-name="OtherSampleEntity" />
<alias entity-alias="SE" name="primaryKeyFieldOne" />
<alias entity-alias="SE" name="primaryKeyFieldTwo" />
<alias entity-alias="SE" name="fieldOne" />
<alias entity-alias="SE" name="fieldTwo" />
<alias entity-alias="OSE" name="primaryKeyOne" />
<alias entity-alias="OSE" name="otherFieldOne" field="fieldOne" />
<view-link entity-alias="SE" rel-entity-alias="OSE">
<key-map field-name="foreignKeyOne" rel-field-name="primaryKeyOne" />
</view-link>
<relation type="one" rel-entity-name="OtherSampleEntity">
<key-map field-name="primaryKeyOne" />
</relation>
<relation type="many" title="AllOne" rel-entity-name="SampleEntity">
<key-map field-name="primaryKeyFieldOne" />
</relation>
</view-entity>
Member Entities
Normal entities that will become part of the view entity are referred to as member entities. Each member entity is given an alias and is referred to by that alias for the rest of the definition. This allows a single entity to be linked in multiple times.
Field Aliases
Rather than specifying fields with a view entity you specify aliases. Each alias
is effectively a field in usage and is defined by being mapped to a field on an aliases member entity. If the field
name is the same as the alias name
, there is no need to specify it. In other words if no field name is specified the alias name will be used as the field name to map to on the member entity with the specified entity-alias
.
View Links
View links are used to specify the links between the member-entities of the view. They link one entity-alias to another and use key-maps just like relations. Here the field-name specifies the name of the field on the aliased entity and the rel-field-name the field on the related aliased entity. As with many other things, the rel-field-name is optional if it is the same as the field-name.
To represent an outer join you can specify in a view-link
element that the related entity is optional using the rel-optional
attribute, which can be either "true" or "false", and of course defaults to "false". The Entity Engine will generate ANSI, Oracle Theta, or MS SQL Server Theta style join code depending on the setting in the entityengine.xml file. See the Entity Engine Configuration Guide for more information.
Primary Keys
View Entities have primary keys just like normal entities. The Entity Engine automatically determines which aliases are primary keys by looking at the field that they alias.
The primary key for a view entity should include all primary key fields of each member entity of the view. This means that all of the primary key fields must be aliased, but fields that are used to link the entities need only be aliased once. For example, if an OrderHeader entity has an orderId primary key and an OrderLine entity has an orderId primary key and an orderLineSeqId primary key, and the orderId was the mapped key that links the two entities, then the view entity would have two primary keys: orderId and orderLineSeqId. In this case orderId would only be aliased once since by definition the orderIds from each entity will always be the same since that is how the entities are linked (or joined).
Relationships
Relationships are specified the same way with view entities as they are with normal entities. That key-map attributes are still called field-name and rel-field-name but in the case of view entities the field name is actually the alias name that will be looked up.
Grouping and Summary Data
Another useful feature available in a view-entity is the Grouping and Summary Data feature. This is accomplished with two attributes on the alias
element: group-by
and function
. These work the same way conceptually as grouping and functions in SQL.
...
Grouping and summarizing data can be very useful for certain types of custom coded reports or for data migration and cleansing.
Tips
Note that view-entities can get pretty complex in a hurry. Those familiar with SQL can look at the generated SQL code to make sure it is doing what they intended. For everyone there are a few tips that might be helpful.
First pay attention to ordering of view-links and in some cases field aliases. In view-links, except for the first one, make sure the member-entity referred to in the entity-alias attribute has been referred to in a previous view-link (this is how the link tree is kept clean).
View Entity Element Reference
view-entity
Attribute Name | Required? | Description |
---|---|---|
entity-name | Y | The name of the entity as it is referred to when using the Entity Engine Java API and various other places in the Entity Engine. |
package-name | Y | The name of the package that this entity is contained in. With hundreds of entities in a large data model this is used to organize and structure the entities definitions. |
dependent-on | N | This can be used to specify a parent entity or an entity that this entity is dependent on. This is currently not used for anything automated in the Entity Engine, but can be used to specify an heirarchical entity structure. |
never-cache | N | If this is set to true caching of this entity will not be allowed. Automatic cache clearing will not be done to improve efficiency and any attempt to use the cache methods on the entity will results in an exception so that it is easier to find and eliminate where this is being done. Must be true or false. Defaults to false. |
title | N | A title for the entity. If not specified defaults to the global setting for the file the entity is in. |
copyright | N | The copyright of the entity. If not specified defaults to the global setting for the file the entity is in. |
author | N | The author of the entity. If not specified defaults to the global setting for the file the entity is in. |
version | N | The version of the entity. If not specified defaults to the global setting for the file the entity is in. |
Sub-Element Name | How Many | Description |
---|---|---|
description | 0 or 1 | A description of the entity. If not specified defaults to the global setting for the file the entity is in. This element has no attributes and should contain only a simple string of characters. |
member-entity | 1 to many | Used to declare which entities will be part of this view-entity and what alias will be used to refer to them. |
alias | 1 to many | Used to declare the aliased fields from the member-entities that will be part of the view entity. |
view-link | 1 to many | Used to declare how the member-entities in the view will be linked together. |
relation | 0 to many | Used to declare relationships between entities. |
...
Attribute Name | Required? | Description |
entity-alias | Y | The alias to use for this member-entity. Must be unique among all member-entities. This will be used to refer to the member-entity in other places in the view-entity definition. |
entity-name | Y | The name of the entity definition that this member entity corresponds to. The same entity can be used multiple times in the same view-entity with different entity-aliases. |
alias
Attribute Name | Required? | Description |
---|---|---|
entity-alias | Y | The entity-alias of the member-entity that this aliased field corresponds to. |
name | Y | The name of the field alias. This is used when interacting with the view-entity the same way a field name is used when interacting with an entity. |
field | N | The name of the field from the member-entity with the given entity-alias that this field alias corresponds to. If not specified defaults to the alias name as specified in the name attribute. |
prim-key | N | Used to specify if this alias should be part of the view-entities primary key. If specified must be either true or false. If not specified the Entity Engine will look at the definition of the field it came from to see if it is part of the original entity's primary key. |
group-by | N | Used to specify that the aliased field should be used for grouping results and should be used in conjunction with the function attribute on other aliased fields. For a more complete discussion see the main text. Must be either true or false. Defaults to false. |
function | N | Used to specify a function to be used on this field to calculate summary information. Should be used in conjunction with the group-by attribute to specify how the summary results should be grouped. See the main text for a more complete discussion of how to use this. |
view-link
Attribute Name | Required? | Description |
---|---|---|
entity-alias | Y | The alias of the entity the link is coming from. |
rel-entity-alias | Y | The alias of the entity the link is going to. |
rel-optional | N | Used to specify whether or not the related entity is optional. If this is true it effects an outer join to the related entity. Must be either true or false. Defaults to false. |
Sub-Element Name | How Many | Description |
---|---|---|
key-map | 1 to many | The key-map is used to specify a field in this entity that corresponds to a field in the related entity. This element has two attributes: field-name and rel-field-name. These are used to specify the name of the field on this entity and the name of the field on the related entity. |
relation
Attribute Name | Required? | Description |
---|---|---|
type | Y | Specifies the type of the relationship including the cardinality of the relationship (in one direction) and if a foreign key should be created for cardinality one relationships. Must be "one", "one-nofk", or "many". |
title | N | Because you may want to have more than one relationship to a single entity this attribute allows you to specify a title that will be prepended to the rel-entity-name to make up the name of the relationship. If not specified the rel-entity-name alone will be used as the relationship name. |
rel-entity-name | Y | The name of the related entity. The relationship goes from this entity to the related entity. |
fk-name | N | The foreign key name can be created automatically from the relationship name, but this is not recommended for two reasons: many databases have a very small maximum size (like 18 characters) for foreign key and index names, and many databases require that the FK name be unique for the entire database and not just for the table the FK is coming from. |
Sub-Element Name | How Many | Description |
---|---|---|
key-map | 1 to many | The key-map is used to specify a field in this entity that corresponds to a field in the related entity. This element has two attributes: field-name and rel-field-name. These are used to specify the name of the field on this entity and the name of the field on the related entity. |
...
A few quick notes to help you get started might be in order.
Factory Methods
Rather than trying to construct a GenericValue or a GenericPK yourself, you should use the makeValue and makePK methods on the GenericDelegator. These create an object without persisting it and allow you to add to it and create or store it later using their own create or store method, or calling the create or store method on the delegator object.
Creating, Storing and Removing
To create (or insert) values into the database, use the create method on the GenericValue or GenericDelegator objects. To store (or update) existing values, use the store method on the GenericValue or GenericDelegator objects.
...
Removal of entities is done through the remove method on either the delegator, or the GenericValue.
Finding
Value instances can be retrieved from the database with the findByPrimaryKey methods, or a collection can be retrieved using the findAll or findByAnd methods.
There are two main types of findByAnd methods. Each type has a number of variations that may include the use of a cache, and may accept an orderBy field list. The two main types accept different field lists. One accepts a Map of fields and finds entities by anding together expressions where each named field must equal the corresponding value in the map. The other type of findByAnd accepts a list of EntityExpr objects that are used to specify small expressions that will be anded together. Each EntityExpr specifies a field name, an operation, and a value for the field.
The EntityCondition Object
Originally the EntityExpr object was meant to be nestable to allow for more flexible queries, but was never completed. Also, even if you could nest it the types of queries you could run would be limited because you couldn't have two ANDs (for instance) inside a set of parentheses. To address these issues, and complete the EntityExpr implementation, the EntityCondition abstract object has been introduced along with the EntityConditionList and EntityFieldMap objects which both extend EntityCondition. The EntityExpr object has also been changed to extend EntityCondition.
...
On that note a "short cut" implementation of the EntityCondition abstract class has been created to incorporate SQL WHERE clause snippets or full clauses into the EntityCondition querying framework. The class is named EntityWhereString and is constructed with a simple String argument that represents the SQL that will be inserted into the final generated SQL. This is not recommended when other options are available, but it necessary for certain functionality that the Entity Engine does not otherwise support.
The EntityListIterator Object
The EntityListIterator class implements the ListIterator interface for convenience, but also has other methods that are necessary for its operation, like a close() method for when you are finished.
...
The EntityListIterator also has helpful methods to get a subset of the result set with a start index value and a number of results desired and to get all of the results at once rather than having to create a custom loop to do so.
The Entity Engine Cache
Because the performance cost of retrieving data from a database can be very high and can have a serious impact on the overall performance of an application or component of an application, the ability to cache data from the database is often very important. Many of the find methods on the GenericDelegator have corresponding cache methods with the "Cache" suffix on the function name. This makes it very easy to cache individual values found by primary key as well as value lists found by and, or by all.
...