<!--
This is the DTD for the Service Builder parameters for Liferay Portal.
<!DOCTYPE service-builder PUBLIC
"-//Liferay//DTD Service Builder 4.4.0//EN"
"http://www.liferay.com/dtd/liferay-service-builder_4_4_0.dtd">
-->
<!--
The service-builder element is the root of the deployment descriptor for
a Service Builder descriptor that is used to generate services available to
portlets. The Service Builder saves the developer time by generating Spring
utilities, SOAP utilities, and Hibernate persistence classes to ease the
development of services.
-->
<!ELEMENT service-builder (namespace, entity+, exceptions?)>
<!--
package-path指定生成文件存放的位置。
-->
<!ATTLIST service-builder
package-path CDATA #REQUIRED
>
<!--
The namespace element must be a unique namespace for this component. Table names
will be prepended with this namespace. Generated JSON JavaScript will be scoped
to this namespace as well (i.e., Liferay.Service.Test.* if the namespace is
Test).
namespace 对于每一个实体来说必须是唯一的。
-->
<!ELEMENT namespace (#PCDATA)>
<!--
An entity usually represents a business facade and a table in the database. If
an entity does not have any columns, then it only represents a business facade.
The Service Builder will always generate an empty business facade POJO if it
does not exist. Upon subsequent generations, the Service Builder will check to
see if the business facade already exists. If it exists and has additional
methods, then the Service Builder will also update the SOAP wrappers.
If an entity does have columns, then the value object, the POJO class that
is mapped to the database, and other persistence utilities are also generated
based on the order and finder elements.
-->
<!ELEMENT entity (column*, order?, finder*, reference*, tx-required*)>
<!--
name指定了实体的名字
table指定了实体在数据库中对应的表的名字，如果没有设置侧表的名字和实体的名字是相同的。
如果uuid设置成true,将自动添加一列，实体将自动生成基于uuid的查询和删除方法.默认值false.
如果local-service设置成true,将自动生成本地接口，默认值false
如果remote-service设置成true,将自动生成远程接口。默认值false;
persistence-class设置自己的持久类的名字。这个类必须实现生成的持久类接口或继承生成的持久类。它允许你在不修改生成的持久类的情况下，覆盖默认的方法
你能用自己的数据源和session Factory生成自己的类。指明spring的配置文件，在portal配置文件中，载入自己的spring文件,文件中必须定义了数据源和sessionFactory.然后设置data-source和 session Factory的值。
data-source 指定持久类使用的数据源，默认的时候，数据源是portal的数据源，数据源被session-Factory使用。
在数据源到spring的文件中可以看到。
tx-manager 指定 spring 使用的transaction manager.默认的是Spring和hibernate transaction mannager是liferay自带的.
-->
<!ATTLIST entity
name CDATA #REQUIRED
table CDATA #IMPLIED
uuid CDATA #IMPLIED
local-service CDATA #IMPLIED
remote-service CDATA #IMPLIED
persistence-class CDATA #IMPLIED
data-source CDATA #IMPLIED
session-factory CDATA #IMPLIED
tx-manager CDATA #IMPLIED
>
<!--
column 对应数据库中的某个列。
-->
<!ELEMENT column (#PCDATA)>
<!--
name指定在实体中的getter和setter的方法。
type指定列的数据类型，字符串，逻辑值，或整型。
db-name指定对应的数据库中列的名字。
For example:
<column name="companyId" db-name="companyId" type="String" />
如何primary的值是true，则此列是关键字段的一部分，如果不止一个列被设置成true，则产生一个符合主键
如果entity和mapping-key属性被指定而没有mapping-table，那么将建立一个一对多的关系。
For example:
<column
name="shoppingItemPrices"
type="Collection"
entity="ShoppingItemPrice"
mapping-key="itemId"
/>
如果entity和mapping-table的值被指定而mapping-kay没有指定，将建立多对多的映射关系。
For example:
<column
name="roles"
type="Collection"
entity="Role"
mapping-table="Groups_Roles"
/>
id-type和id-param的用来创建一个自动生成，自动增加的关键字，当向数据库中插入一条记录时，关键字自动增加。
根据不同类型的数据库，可以用四种不同的方法来实现。所有的情况，模型实体的值应该是null，hibernate自动用自增的关键字代替null.如果id-type没有使用，关键字自动生成但不自动增加。
一、用一个类来生成关键字
For example:
<column
name="id"
type="Integer"
primary="true"
id-type="class"
id-param="com.liferay.counter.service.persistence.IDGenerator"
/>
二、当没有另外的进程插入数据到同一个数据库的时，自动生成唯一的标识符。这种方法不应该用到群集环境中，但是适用所有的数据库
For example:
<column
name="id"
type="Integer"
primary="true"
id-type="increment"
/>
三、使用一个列标识符生成一个关键字
For example:
<column
name="id"
type="Integer"
primary="true"
id-type="identity"
/>
.
无论什么时候插入，实体生成一个标识列（自动生成的关键字）
The fourth implementation uses a sequence to generate a primary key.
四、用一个序列产生一个关键字。
For example:
<column
name="id"
type="Integer"
primary="true"
id-type="sequence"
id-param="id_sequence"
/>
用这种实现方法，产生一个序列的SQL命令基于id-param的值（存储在/sql/sequences.sql).这个序列是自动生成唯一标别。仅DB2,ORACLE ,POSTGRESQL 和SAPDB能使用。
convert-null指定，如果数值为null是否自动转化成一个非空的值。当实体涉及到一个只读的表或视图的时候，特别有用，hibernate就不会进行没必要的更新。默认值是true.
-->
<!ATTLIST column
name CDATA #REQUIRED
db-name CDATA #IMPLIED
type CDATA #REQUIRED
primary CDATA #IMPLIED
entity CDATA #IMPLIED
mapping-key CDATA #IMPLIED
mapping-table CDATA #IMPLIED
id-type CDATA #IMPLIED
id-param CDATA #IMPLIED
convert-null CDATA #IMPLIED
>
<!--
order指定索引数据库时候的默认排列顺序。
-->
<!ELEMENT order (order-column+)>
<!--
by用来设定排列的顺序是asc(升序）或desc（降序）
-->
<!ATTLIST order
by CDATA #IMPLIED
>
<!--
order-column根据指定的列来进行排序。
-->
<!ELEMENT order-column (#PCDATA)>
<!--
For example:
<order by="asc">
<order-column name="parentLayoutId" />
<order-column name="priority" />
</order>
For example:
<order by="asc">
<order-column name="name" case-sensitive="false" />
</order>
The above settings will order by name and will not be case sensitive.
For example:
<order>
<order-column name="articleId" order-by="asc" />
<order-column name="version" order-by="desc" />
</order>
-->
<!ATTLIST order-column
name CDATA #REQUIRED
case-sensitive CDATA #IMPLIED
order-by CDATA #IMPLIED
>
<!--
finder 生成一个查找的方法。
-->
<!ELEMENT finder (finder-column+)>
<!--
-->
<!ATTLIST finder
name CDATA #REQUIRED
return-type CDATA #REQUIRED
where CDATA #IMPLIED
db-index CDATA #IMPLIED
>
<!--
finder-column指定按照那一列来查找。
-->
<!ELEMENT finder-column (#PCDATA)>
<!--
name指定查找的方法名。
For example:
<finder name="CompanyId" return-type="Collection">
<finder-column name="companyId" />
</finder>
The above settings will create a finder with the name findByCompanyId that will
return a Collection and require a given companyId. It will also generate
several more findByCompanyId methods that take in pagination fields (int begin,
int end) and more sorting options. The easiest way to understand this is to
look at a generated PersistenceImpl class. The Service Builder will also
generate removeByCompanyId and countByCompanyId.
See com.liferay.portal.service.persistence.LayoutPersistenceImpl for a good
example.
The attribute comparator takes in the values =, !=, <, <=, >, >=, or LIKE and is
used to compare this column.
The attribute case-sensitive is a boolean value and is only used if the column
is a String value.
-->
<!ATTLIST finder-column
name CDATA #REQUIRED
db-name CDATA #IMPLIED
case-sensitive CDATA #IMPLIED
comparator CDATA #IMPLIED
>
<!--
The reference element allows you to inject services from another service.xml
within the same class loader. For example, if you inject the Resource entity,
then you'll be able to reference the Resource services from your service
implementation via the methods getResourceLocalService and getResourceService.
You'll also be able to reference the Resource services via the variables
resourceLocalService and resourceService.
-->
<!ELEMENT reference (#PCDATA)>
<!--
See the comments in reference element.
-->
<!ATTLIST reference
package-path CDATA #IMPLIED
entity CDATA #IMPLIED
>
<!--
The tx-required element has a text value that will be used to match method names
that require transactions. By default, the methods: add*, check*, clear*,
delete*, set*, and update* require propagation of transactions. All other
methods support transactions but are assumed to be read only. If you want
additional methods to fall under transactions, add the method name to this
element.
-->
<!ELEMENT tx-required (#PCDATA)>
<!--
The exceptions element contain a list of generated exceptions. This doesn't save
a lot of typing, but can still be helpful.
-->
<!ELEMENT exceptions (exception*)>
<!--
See the comments in exceptions element.
-->
<!ELEMENT exception (#PCDATA)>
还没有翻译完,是service.xml使用的dtd文件
