Page History

Table of Contents

Related Documents:

Entity Engine Configuration Guide 

• Core Configuration Guide
• JavaDoc List (Documents Page)
• XML File Definitions (Documents Page)

...

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

field

prim-key

relation

...

    <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

...

alias

view-link

relation

...

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.

...