ofbiz之旅-实体简介(中英译)

OFBIZ ENTITY ENGINE COOKBOOK

============================

OFBIZ ENTITY ENGINE 菜谱

 

* Keep your entity names less than 25 characters

  Oracle, for example, does not like tables with names longer than 30 characters, and OFBIZ

will add a "_" between words, so it's best to keep them short.

* 保证让你的entity names在25个字符以内

  因为有些数据库不允许表名超过30个字符，例如Oracle.而且ofbiz还要在单词之间加入"_"，所以尽可能的让实体名称短。

* How relationships work

  如何建立关系

  They are defined in entitymodel.xml files for an <entity> like this:

  关系是在entitymodel.xml文件当中<entity>标签定义的,例如:

      <relation type="one" fk-name="PROD_CTGRY_PARENT" title="PrimaryParent" rel-entity-name="ProductCategory">

      <key-map field-name="primaryParentCategoryId" rel-field-name="productCategoryId"/>

      </relation>

      <relation type="many" title="PrimaryChild" rel-entity-name="ProductCategory">

        <key-map field-name="productCategoryId" rel-field-name="primaryParentCategoryId"/>

      </relation>

 

  type= defines the type of the relationship: "one" for one-to-one or "many" for

one-to-many from this entity

  type=定义了一个关系类型,从这个实体看来"one" 是one-to-one 或者"many"是one-to-many

  fk-name= is a foreign key name.  It is usually good practice to set your own foreign key name, although OFBIZ will auto-generate if it's not there.

  fk-name是一个外键名称,最佳实践策略是自己在这里定义外键名称,虽然如果这里不写OFBIZ会自动生成一个

  rel-entity-name= is the name of the related entity.

  rel-entity-name是被关联实体名称

  title= is used to distinguish different relationships when there are many relationships between the same two entities.

  title是用来在两个实体之间存在多种关系的时候用来区分不同关系的名称

  <key-map> defines the fields for the relationship. field-name= is for the field of this entity to use.  If the field on the related entity

  has a different field name, then rel-field-name= defines the field name in the related entity.  You can have many fields serve as part of a key-map.

  <key-map> 为关系定义了字段

  field-name是本实体用到的字段,如果在被关联实体当中使用不同的字段名,那么用rel-field-name定义被关联实体当中的字段名,一个key-map元素可以有多个字段名.

 

When you access a relationship, you would use .getRelated("") or .getRelatedOne("") with the title+entityName as parameter.  getRelated returns a List and is appropriate when it is a "many" relation.  .getRelatedOne returns a single GenericVaue and is appropriate for "one" relations.

当访问关系的时候可以用 .getRelated("") 或者 .getRelatedOne("") 用 title+entityName 作为参数。

当实体一个"many"关系的时候使用getRelated 返回一个列表，当实体一个"one"关系的时候使用getRelatedOne 返回一个GenericVaue .

* A few things about view-entities

关于view-entities的一些说明

View-entities are very powerful and allow you to create join-like queries, even when your database doesn't support joins.

view-entities是非常有用的并且允许你创建join-like查询，甚至你的数据库不支持joins都可以

The configuration of your database's join syntax is in entityengine.xml under the join-style attribute of <datasource ..>

在entityengine.xml中<datasource ..>元素当中的join-style属性当中设置你的数据库join语法

When you link two entities together using the <view-link ..> tag, remember

1.  The order of the entities you name is important.

2.  The default is an inner join (values must be present on both sides.)  To do an outer join, use rel-optional="true"

当你将两个实体连接在一起的时候使用 <view-link ..>标签，记住

1. 实体名称的顺序很重要

2. 缺省情况时内连接(值必须在两边都出现）如果要作一个外连接用rel-optional="true"

If several entities have the same field name, such as statusId, the one from the first entity will be used and the rest tossed out.  So if you need the field from one, put its <alias-all> before the others.  Alternatively, use <alias ..> tag

to give the same field from different entities names, such as:

如果几个实体拥有相同名称的字段，例如statusId,那么第一个实体的statusId被使用其它的都会抛弃掉，因此如果需要使用其它实体当中相同名字字段的时候，把它们放入<alias-all>，作为一个选择用 <alias ..> 标签

 

可以区分不同实体当中相同的名字字段，例如：

 

<alias entity="EntityOne" field="statusId"/>

<alias entity="EntityTwo" field="statusId"/>

 

Another alternative is to use <exclude field=""> inside an <alias-all> as follows:

另一个选择就是在 <alias-all>内使用<exclude field="">例如

 

<alias-all entity-alias="EN">

  <exclude field="fieldNameToExclude1"/>

  <exclude field="fieldNameToExclude2"/>

</alias-all>

 

This top-down approach is more compact, which comes in handy for large tables.

这种严密的写法更加紧凑，对于字段多的大表用的上。

Alternatively, you can specify one or more <exclude field="fieldName"> inside an  <alias-all>.

更加简洁的一种写法是在<alias-all>当中使用<exclude field="fieldName">

 This top-down approach is more compact than specifying the alias for every field in a big

table.

 这样比一个一个的指定字段的别名方法更加紧凑简洁。

If you need to do a query like this

如果你需要做一个如下查询

SELECT count(visitId) FROM ... GROUP BY trackingCodeId WHERE fromDate > ' 2005-01-01'

 

include field visitId with function="count", trackingCodeId with group-by="true", and

 

fromDate with group-by="false"

用function="count"包含字段visitId

，用group-by="true"给trackingCodeId，用fromDate给group-by="false"

Then **VERY IMPORTANT** when you do your query, such as delegator.findByCondition, you must specify the fields to select,and you must not specify the field fromDate, or you will get an error.  This is why these view-entities can't be viewed from webtools.

非常非常重要的是当你查询的时候，例如使用delegator.findByCondition，你必须指定选择的字段，在上例中

 

不指定fromDate，你会得到一个错误，这也是为什么view-entities为什么不能在webtools里面被看到的一个原因。

 

For an example, look at the view entities at the bottom of

更多的例子可以参考以下实体

applications/marketing/entitydef/entitymodel.xml and

the BSH scripts in applications/marketing/webapp/marketing/WEB-INF/actions/reports.

 

* How to build conditions for expiration dates

怎样建立一个根据有效日期的查询条件

There is a series of very helpful methods called EntityUtil.getFilterByDateExpr which return an EntityConditionList to filter out search results by date.

有一系列非常有用的方法叫 EntityUtil.getFilterByDateExpr 能够返回EntityConditionList用于通过日期实体条件。

 

* How to work with large sets of data

怎样使用大量的数据

If you need to select large sets of data, you should use the EntityListIterator instead of the List.  For example, if you did

如果你需要选择大量的数据集合，你可以用EntityListIterator替代List.例如如果你做了

 

List products = delegator.findAll("Product");

 

You may get yourself a "java.lang.OutOfMemoryError".  This is because findAll, findByAnd, findByCondition will try to retrieve all the records into memory as a List.  In that case, re-write your query to do return an EntityListIterator  then loop through it.  For example, this query can

be re-written as:

你可能得到一个"java.lang.OutOfMemoryError"异常。这是因为findAll, findByAnd, findByCondition尝试把所有的符合标准的纪录加载到内存当中，一个解决方案是重新写你的查询作为一个EntityListIterator并且遍历它，例如上面的查询可以写为

 

 

productsELI = delegator.findListIteratorByCondition("Product", new EntityExpr("productId",

 

EntityOperator.NOT_EQUAL, null), UtilMisc.toList("productId"), null);

 

Note that the only method for finding an EntityListIterator is a by condition, so you would have to re-write your conditions as EntityExpr (in this case, a dummy one which just says that productId is not null, which should apply to all Product entities,

 

since productId is a not-null primary key field) or EntityConditionList. This method also asks you to fill in the fields to select (in this case just productId) and order by (which I didn't specify with the last null.)

 

注意这是唯一的一个通过条件得到一个EntityListIterator的方法，你必须用EntityExpr（这个例子当中表示为productId 不能为 null，其实是一句废话，就是说明所有纪录）或EntityConditionList者重写你的条件 。这个方法也要求指定所有要选择的字段（这个例子里面只有productId) 并且order by（在给出的例子当中没有指定，位置位于最有一个null参数）

 

You can pass a null EntityCondition to grab all records.  However, this does not work across all databases!  Beware the use of avanced functionality such as the EntityListIterator with maxdb and other odd databases.

 

你可以通过一个空的EntityCondition 抓取所有纪录，然而这种做法并不支持所有的数据库，对于大型数据库或者奇怪的数据库，谨慎的使用高级的函数例如EntityListIterator当中的函数。

 

* How to use an EntityListIterator

如何使用一个EntityListIterator

 

When iterating through the EntityListIterator, this is the preferred form:

当遍历EntityListIterator的时候如下的做法是首选的

 

while ((nextProduct = productsELI.next()) != null) {

....

    // operations on nextProduct

}

 

Using the .hasNext() method on EntityListIterator is considered wasteful.

在EntityListIterator 当中使用.hasNext()被认为是浪费资源的

 

When you are done, don't forget to close it:

当你使用EntityListIterator ，不要忘记关闭它

 

productsELI.close();

 

* How to do a select distinct

如何得到不重复的纪录

 

The only way we know of to do it with the entity engine is to find a list iterator and use

 

EntityFindOptions to specify it, like this:

据我们所知在 entity engine只能通过指定EntityFindOptions 得到一个list iterator例如：

    listIt = delegator.findListIteratorByCondition(entityName, findConditions,

            null, // havingEntityConditions

            fieldsToSelectList,

            fieldsToOrderByList, 

           

            // This is the key part.  The first true here is for "specifyTypeAndConcur"

            // the second true is for a distinct select.  Apparently this is the only way

 

the entity engine can do a distinct query

            new EntityFindOptions(true, EntityFindOptions.TYPE_SCROLL_INSENSITIVE,

 

EntityFindOptions.CONCUR_READ_ONLY, true));

 

In minilang, curiously, it is much easier:

奇怪的是在minilang他非常简单。

  <entity-condition entity-name="${entityName}" list-name="${resultList}" distinct="true">

     <select field="${fieldName}"/>

     ....

 

* How to go from EntityListIterator to just List

怎样从EntityListIterator变为一个纯粹的List

 

  Use the EntityListIterator.getCompleteList() and getPartialList methods

 

使用EntityListIterator.getCompleteList()和getPartialList方法

* How to get the next ID value automatically

怎样通过自动增长得到下一个ID

  Use either <sequence-id-to-env ...> in minilang or delegator.getNextSeqId(...) in Java.  The id sequence numbers are stored in an entity SequenceValueItem.

使用在minilang中的<sequence-id-to-env ...> 或者 Java 中的delegator.getNextSeqId(...)这个id序列的数字被存储在一个SequenceValueItem当中。

* A word of warning about ID values

关于ID值被警告的说明

  DO NOT CREATE SEED OR DEMO DATA WITH ID 10000!  When the system tries to create more values automatically, it will also try to use 10000,

  resulting in a key clash.

  不要用ID 10000创建种子或者例子数据!当系统尝试穿件自动增长的值时候他会尝试10000

* How to set up an alias that does the equivalent of SELECT SUM(QUANTITY - CANCEL_QUANTITY) AS QUANTITY

  怎样设置一个别名类似于SELECT SUM(QUANTITY - CANCEL_QUANTITY) AS QUANTITY这用SQL语句

 

  <alias entity-alias="OI" function="sum">

      <complex-alias operator="-">

          <complex-alias-field entity-alias="OI" field="quantity" default-value="0"/>

          <complex-alias-field entity-alias="OI" field="cancelQuantity" default-value="0"/>

      </complex-alias>

  </alias>

 

  This results in SELECT SUM(COALESCE(OI.QUANTITY,'0') - COALESCE(0I.CANCEL_QUANTITY)) AS QUANTITY  Including a default-value is a good habit, otherwise the result of the subtraction will be null if any of its fields are null.

  The operator can be any of the supported SQL operations of your database, such as

arithmetic with  +, -, * and / or concatenation of strings with ||.

给这个SELECT SUM(COALESCE(OI.QUANTITY,'0') - COALESCE(0I.CANCEL_QUANTITY)) AS QUANTITY的结果一个缺省值是一个良好的习惯，否则当他们之中有一个为空就会导致结果为空

  这个操作可以支持你使用数据库的所有函数例如  +, -, * 和 /，字符串连接符||。

  You can add a function="" to perform min, max, sum, avg, count, count-distinct, upper and lower

你也可以添加一个 function="" 实现min, max, sum, avg, count, count-distinct, upper 和 lower on the complex-alias-field.  For example, an alternative way to express the query above

is to do:

  对于复杂的别名字段，例如在查询中的二选一的表达式采用如下做法

 

  <alias entity-alias="OI" >

      <complex-alias operator="-">

          <complex-alias-field entity-alias="OI" field="quantity" default-value="0"

 

function="sum"/>

          <complex-alias-field entity-alias="OI" field="cancelQuantity" default-value="0"

 

function="sum"/>

      </complex-alias>

  </alias>

 

  Which results in SELECT (SUM(COALESCE(OI.QUANTITY,'0')) - SUM(COALESCE(OI.CANCEL_QUANTITY,'0'))) AS QUANTITY

结果是类似 SELECT (SUM(COALESCE(OI.QUANTITY,'0')) - SUM(COALESCE(OI.CANCEL_QUANTITY,'0'))) AS QUANTITY的查询结果