Apache OFBiz 学习笔记 之 服务引擎 二

加载服务定义文件

ofbiz-component.xml：所有的服务定义文件在每个组件的ofbi-component.xml文件中

加载服务定义
例:framework/common/ofbiz-component.xml

<entity-resource type="model" reader-name="main" loader="main" location="entitydef/entitymodel.xml"/>
<entity-resource type="model" reader-name="main" loader="main" location="entitydef/entitymodel_olap.xml"/>
<entity-resource type="group" reader-name="main" loader="main" location="entitydef/entitygroup_olap.xml"/>
<entity-resource type="data" reader-name="seed" loader="main" location="data/CommonSecurityData.xml"/>
<entity-resource type="data" reader-name="seed" loader="main" location="data/CommonSystemPropertyData.xml"/>
<entity-resource type="data" reader-name="seed" loader="main" location="data/CommonTypeData.xml"/>
<entity-resource type="data" reader-name="seed" loader="main" location="data/CountryCodeData.xml"/>
<entity-resource type="data" reader-name="seed" loader="main" location="data/CurrencyData.xml"/>

服务参数

IN：输入参数，类似于java方法中的入参一样，一个ofibiz服务同样需要声明入参，声明方式为在attribute中添加属性mode="IN"
例：

<attribute name="partyId" type="String" mode="IN" optional="true"/>

OUT：输出参数，类似于java方法中会有返回值一样，一个ofbiz服务也需要声明输出参数，声明方式为在attribute中添加属性mode="OUT"
例：

<attribute name="noteId" type="String" mode="OUT"/>

INOUT：输入输出参数,为了方便起见，可以将一个参数既作为输入参数，又作为输出参数，声明方式为在attribute中添加属性mode="INOUT"
例：

<attribute name="nodeId" type="String" mode="INOUT"/>

隐含参数：如同servlet内置对象，在ofbiz服务中有少数参数已经在框架中定义了，无需声明就可以在服务中使用

name	type	mode	optional	说明
responseMessage	String	OUT	true	返回信息（success/error/fail)
errorMessage	String	OUT	true	错误信息
errorMessageList	java.util.List	OUT	true	错误信息列表
successMessage	String	OUT	true	成功信息
successMessageList	java.util.List	OUT	true	成功信息列表
userLogin	org.ofbiz.entity.GenericValue	INOUT	true	登陆用户对象，用于权限验证
locale	java.util.Locale	INOUT	true	国际化本地对象

可选/必选参数：服务的参数可以是可选，也可以是必须。必须输入的参数在服务调用之前会做检验，如果输入参数的名字及对象类型与声明不符，服务就不会被调用（报错）。必须的输出参数在服务调用之后会被检验，如果输出参数的名字及对象类型与声明不符，会导致服务失败（报错）。只有声明为必须的参数才被检验，同样如果你传入了一个没有意义的参数，也将导致服务调用失败。声明方式为在attribute中添加属性optional="true"/optional="false"（缺省）
例：

<attribute name="partyId" type="String" mode="IN" optional="true"/>
<attribute name="partyId" type="String" mode="IN" optional="false"/>

Interface服务引擎
interface服务引擎实现了在定义服务时可以共享同样的参数。interface服务是不可以被调用的，它仅作为其他服务继承而定义。每个接口服务都需要用interface服务引擎来定义
例：applications/order/servicedef/services.xml

<!-- mass order changes -->
<service name="massOrderChangeInterface" engine="interface" location="" invoke="">
<description>Interface for Mass Order Change Services</description>
<attribute name="orderIdList" type="List" mode="IN" optional="false"/>
</service>

继承上述的接口来实现新的服务
例：applications/order/servicedef/services.xml

<service name="massPickOrders" engine="java" transaction-timeout="300"
location="org.ofbiz.order.order.OrderServices" invoke="massPickOrders" auth="true">
<implements service="massOrderChangeInterface"/>
</service>
<service name="massChangeOrderApproved" engine="java" transaction-timeout="300"
location="org.ofbiz.order.order.OrderServices" invoke="massChangeApproved" auth="true">
<implements service="massOrderChangeInterface"/>
</service>
<service name="massProcessOrders" engine="java" transaction-timeout="300"
location="org.ofbiz.order.order.OrderServices" invoke="massProcessOrders" auth="true">
<implements service="massOrderChangeInterface"/>
</service>

然后我们分别查看java类org.ofbiz.order.order.OrderServices中的方法massPickOrders、massChangeApproved、massProcessOrders
代码片中都存在如下代码，可以获取参数接口定义的变量orderIdList

// make the list per facility
List<String> orderIds = UtilGenerics.checkList(context.get("orderIdList"));

覆盖接口，覆盖接口中的属性或新增属性
例：applications/order/servicedef/services.xml

<service name="massPrintOrders" engine="java" transaction-timeout="300"
location="org.ofbiz.order.order.OrderServices" invoke="massPrintOrders" auth="true">
<implements service="massOrderChangeInterface"/>
<attribute name="screenLocation" type="String" mode="IN" optional="false"/>
<attribute name="printerName" type="String" mode="IN" optional="true"/>
</service>

查看代码java类org.ofbiz.order.order.OrderServices中的方法massPrintOrders

String screenLocation = (String) context.get("screenLocation");
String printerName = (String) context.get("printerName");

// make the list per facility
List<String> orderIds = UtilGenerics.checkList(context.get("orderIdList"));

实现服务
实现一个服务可以用一个或多个服务引擎来实现，这里描述下常用的实现方法
java：用java代码实习服务
首先定义java类型的服务
服务定义：applications/party/servicedef/services_view.xml

<service name="getPerson" engine="java"
location="org.ofbiz.party.party.PartyServices" invoke="getPerson">
<description>Gets a person entity from the cache/database</description>
<attribute name="partyId" type="String" mode="IN"/>
<attribute name="lookupPerson" type="org.ofbiz.entity.GenericValue" mode="OUT"/>
</service>

engine： java
location：指向带包路径的类名
invoke：静态的方法名称
代码
1、参数通过Map方式传递给java方法
2、在java事件中GenericValue类型的userLogin、Locale类型的locale作为属性加入到request中
3、第一个参数DispatchContext包含访问数据库、调用其他服务的工具
4、从java代码中如下访问便利的对象
GenericValue userLogin = (GenericValue)context.get("userLogin");
Locale locale = (Locale)context.get("locale");
Delegator delegator = dctx.getDelegator();

安全和访问控制
例：详细参考/applications/order/src/org/ofbiz/order/order/OrderLookupServices.java

public static Map<String, Object> findOrders(DispatchContext dctx, Map<String, ? extends Object> context) {
Security security = dctx.getSecurity();
// check security flag for purchase orders
boolean canViewPo = security.hasEntityPermission("ORDERMGR", "_PURCHASE_VIEW", userLogin);
if (!canViewPo) {
conditions.add(EntityCondition.makeCondition("orderTypeId", EntityOperator.NOT_EQUAL, "PURCHASE_ORDER"));
}
}

服务返回
服务必须返回一个map，这个map至少包含一个responseMessage
ModelService.RESPOND_SUCCESS
ModelService.RESPOND_ERROR
ModelService.RESPOND_FAIL

simple:使用minilang开发的服务详细使用方法参考后续的《minilang开发 学习笔记 》系列
脚本：applications/party/servicedef/services.xml

<!-- Party Relationship services -->
<service name="createPartyRelationship" default-entity-name="PartyRelationship" engine="simple"
location="component://party/script/org/ofbiz/party/party/PartyServices.xml" invoke="createPartyRelationship" auth="true">
<description>
Create a Relationship between two Parties;
if partyIdFrom is not specified the partyId of the current userLogin will be used;
if roleTypeIds are not specified they will default to "_NA_".
If a partyIdFrom is passed in, it will be used if the userLogin has PARTYMGR_REL_CREATE permission.
</description>
<permission-service service-name="partyRelationshipPermissionCheck" main-action="CREATE"/>
<auto-attributes include="pk" mode="IN" optional="true"/>
<auto-attributes include="nonpk" mode="IN" optional="true"/>
<override name="partyIdTo" optional="false"/>
</service>

engine： simple
location：实现文件的全路径
invoke：simple-method

<!-- PartyRelationship services -->
<simple-method method-name="createPartyRelationship" short-description="createPartyRelationship">
<if-empty field="parameters.roleTypeIdFrom"><set field="parameters.roleTypeIdFrom" value="_NA_"/></if-empty>
<if-empty field="parameters.roleTypeIdTo"><set field="parameters.roleTypeIdTo" value="_NA_"/></if-empty>
<if-empty field="parameters.partyIdFrom"><set field="parameters.partyIdFrom" from-field="userLogin.partyId"/></if-empty>

<if-empty field="parameters.fromDate"><now-timestamp field="parameters.fromDate"/></if-empty>

<!-- check if not already exist -->
<entity-and entity-name="PartyRelationship" list="partyRels" filter-by-date="true">
<field-map field-name="partyIdFrom" from-field="parameters.partyIdFrom"/>
<field-map field-name="roleTypeIdFrom" from-field="parameters.roleTypeIdFrom"/>
<field-map field-name="partyIdTo" from-field="parameters.partyIdTo"/>
<field-map field-name="roleTypeIdTo" from-field="parameters.roleTypeIdTo"/>
</entity-and>

<if-empty field="partyRels">
<make-value value-field="newEntity" entity-name="PartyRelationship"/>
<set-pk-fields map="parameters" value-field="newEntity"/>
<set-nonpk-fields map="parameters" value-field="newEntity"/>
<create-value value-field="newEntity"/>
</if-empty>
</simple-method>

entity-auto服务
例：specialpurpose/example/servicedef/services.xml

<!-- Example & Related Services -->
<service name="createExample" default-entity-name="Example" engine="entity-auto" invoke="create" auth="true">
<description>Create a Example</description>
<permission-service service-name="exampleGenericPermission" main-action="CREATE"/>
<auto-attributes include="pk" mode="OUT" optional="false"/>
<auto-attributes include="nonpk" mode="IN" optional="true"/>
<override name="exampleTypeId" optional="false"/>
<override name="statusId" optional="false"/>
<override name="exampleName" optional="false"/>
</service>

RMI服务
例：applications/accounting/servicedef/services_rita.xml

<!-- RiTA (Remote) Implementations -->
<service name="ritaCCAuthRemote" engine="rmi"
location="rita-rmi" invoke="ritaCCAuth">
<description>RiTA Credit Card Pre-Authorization/Sale</description>
<implements service="ccAuthInterface"/>
</service>

engine：rmi
location：rita-rmi这个是是在serviceengine.xml中配置的

<service-location name="rita-rmi" location="rmi://localhost:1099/RMIDispatcher"/>

invoke：ritaCCAuth 服务名，该服务如下，也在applications/accounting/servicedef/services_rita.xml中

<!-- RiTA (Local) Implementations -->
<service name="ritaCCAuth" engine="java" export="true"
location="org.ofbiz.accounting.thirdparty.gosoftware.RitaServices" invoke="ccAuth">
<description>RiTA Credit Card Pre-Authorization/Sale</description>
<implements service="ccAuthInterface"/>
</service>

设置为可被远程调用 export=“true”

route 服务
这类类型不常用，路由服务使用路由引擎定义，当一个路由服务被调用时，不会执行调用，但是所有定义的ECA会在适当事件中运行。通过利用ECA服务选项可以路由（‘route‘）到其他服务

http服务
使用http服务是调用定义在其他系统上远程服务的一种方法。本地定义应该和远程定义一致，但是引擎应该是http，location应该是httpService事件在远程系统上运行的完全URL，方法应该是远程系统上被调用运行的服务名。远程系统必须有挂在HTTP服务上公允的httpService事件。默认情况下，commonapp web应用程序有用来接收服务请求的这样的事件。在远程系统上的服务必须将export属性设为true允许远程调用。HTTP服务本质就是同步的。

JMS服务
JMS服务和HTTP服务很相似，除了服务请求被发送到JMS topic/queue。engine属性应该设置为jms，location属性应该设置为在serviceengine.xml文件中定义的JMS服务名。方法应该是你请求要执行的远程系统上的JMS服务名。本质就是异步

服务组
服务组由多个服务组成的集合。
组的定义：包含一个拥有多个service元素的group元素。group元素包含name属性和mode属性
mode用来定义服务怎么执行
service：类似于ECA中的action元素，不同之处在于resutl-to-context属性的默认值不同。
例：applications/workeffort/servicedef/service_groups.xml

<service-group xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://ofbiz.apache.org/dtds/service-group.xsd">

<group name="updateWorkEffortAndAssoc" send-mode="all"  >
<invoke name="updateWorkEffort" mode="sync"/>
<invoke name="updateWorkEffortAssoc" mode="sync"/>
</group>
<group name="createWorkEffortRequestItemAndRequestItem" send-mode="all"  >
<invoke name="checkCustRequestItemExists" mode="sync"  result-to-context="true"/>
<invoke name="createWorkEffortRequestItem" mode="sync"/>
</group>
</service-group>

调用服务
调用一个存在的服务是非常简单的，可以通过webtools的Service Engine Tools查看具体的服务信息
1、java：使用java方式调用服务
例：applications/content/src/org/ofbiz/content/search/SearchEvents.java

public static String indexTree(HttpServletRequest request, HttpServletResponse response) {

Map<String, Object> result;
Map<String, Object> serviceInMap = FastMap.newInstance();
HttpSession session = request.getSession();
GenericValue userLogin = (GenericValue)session.getAttribute("userLogin");
serviceInMap.put("userLogin", userLogin);
LocalDispatcher dispatcher = (LocalDispatcher) request.getAttribute("dispatcher");
Map<String, Object> paramMap = UtilHttp.getParameterMap(request);
String siteId = (String)paramMap.get("contentId");
serviceInMap.put("contentId", siteId);
try {
result = dispatcher.runSync("indexTree", serviceInMap);
} catch (GenericServiceException e) {
String errorMsg = "Error calling the indexTree service." + e.toString();
Debug.logError(e, errorMsg, module);
request.setAttribute("_ERROR_MESSAGE_", errorMsg + e.toString());
return "error";
}
String errMsg = ServiceUtil.getErrorMessage(result);
if (Debug.infoOn()) Debug.logInfo("errMsg:" + errMsg, module);
if (Debug.infoOn()) Debug.logInfo("result:" + result, module);
if (UtilValidate.isEmpty(errMsg)) {
List<String> badIndexList = UtilGenerics.checkList(result.get("badIndexList"));
if (Debug.infoOn()) Debug.logInfo("badIndexList:" + badIndexList, module);
String badIndexMsg = StringUtil.join(badIndexList, "\n") + badIndexList.size() + " entities not indexed";
Integer goodIndexCount = (Integer)result.get("goodIndexCount");
String goodIndexMsg = goodIndexCount + " entities indexed.";
if (Debug.infoOn()) Debug.logInfo("goodIndexCount:" + goodIndexCount, module);
ServiceUtil.setMessages(request, badIndexMsg, goodIndexMsg, null);
return "success";
} else {
ServiceUtil.setMessages(request, errMsg, null, null);
return "error";
}
}

调用服务

try {
result = dispatcher.runSync("indexTree", serviceInMap);
} catch (GenericServiceException e) {
String errorMsg = "Error calling the indexTree service." + e.toString();
Debug.logError(e, errorMsg, module);
request.setAttribute("_ERROR_MESSAGE_", errorMsg + e.toString());
return "error";
}

如上调用了indxTree服务，该服务在applications/content/servicedef/services.xml中被定义

<service name="indexTree" auth="true" engine="java" validate="true" transaction-timeout="7200"
location="org.ofbiz.content.search.SearchServices" invoke="indexTree">
<description>Index content under publish point</description>
<attribute mode="IN" name="contentId" optional="false" type="String"/>
<attribute mode="OUT" name="badIndexList" optional="true" type="List"/>
<attribute mode="OUT" name="goodIndexCount" optional="true" type="Integer"/>
</service>

2、smiple-method：使用simple-method方式调用服务

例：applications/accounting/script/org/ofbiz/accounting/payment/PaymentServices.xml

<simple-method method-name="createPaymentAndApplication" short-description="Create a payment and a payment application for the full amount">
<set-service-fields service-name="createPayment" map="parameters" to-map="createPaymentInMap"/>
<call-service service-name="createPayment" in-map-name="createPaymentInMap">
<result-to-field field="paymentId" result-name="paymentId"/>
</call-service>
<check-errors/>
<set-service-fields service-name="createPaymentApplication" map="parameters" to-map="createPaymentAppInMap"/>
<set field="createPaymentAppInMap.paymentId" from-field="paymentId"/>
<set field="createPaymentAppInMap.amountApplied" from-field="parameters.amount"/>
<call-service service-name="createPaymentApplication" in-map-name="createPaymentAppInMap">
<result-to-field field="paymentApplicationId" result-name="paymentApplicationId"/>
</call-service>
<check-errors/>
<field-to-result field="paymentId" result-name="paymentId"/>
<field-to-result field="paymentApplicationId" result-name="paymentApplicationId"/>
</simple-method>

调用服务

<call-service service-name="createPayment" in-map-name="createPaymentInMap">
<result-to-field field="paymentId" result-name="paymentId"/>
</call-service>

该服务createPayment定义于applications/accounting/script/org/ofbiz/accounting/payment/PaymentServices.xml

<simple-method method-name="createPayment" short-description="Create a Payment">
<if>
<condition>
<and>
<not><if-has-permission permission="PAY_INFO" action="_CREATE"/></not>
<not><if-compare-field field="userLogin.partyId" to-field="parameters.partyIdFrom" operator="equals"/></not>
<not><if-compare-field field="userLogin.partyId" to-field="parameters.partyIdTo" operator="equals"/></not>
</and>
</condition>
<then>
<add-error>
<fail-property resource="AccountingUiLabels" property="AccountingCreatePaymentPermissionError"/>
</add-error>
</then>
</if>
<check-errors/>

<make-value entity-name="Payment" value-field="payment"/>
<if-empty field="parameters.paymentId">
<sequenced-id sequence-name="Payment" field="payment.paymentId"/>
<else>
<set field="payment.paymentId" from-field="parameters.paymentId"/>
</else>
</if-empty>
<field-to-result field="payment.paymentId" result-name="paymentId"/>

<if-not-empty field="parameters.paymentMethodId">
<entity-one entity-name="PaymentMethod" value-field="paymentMethod">
<field-map field-name="paymentMethodId" from-field="parameters.paymentMethodId"/>
</entity-one>
<if-compare-field field="parameters.paymentMethodTypeId" operator="not-equals" to-field="paymentMethod.paymentMethodTypeId">
<log level="info" message="Replacing passed payment method type [${parameters.paymentMethodTypeId}] with payment method type [${paymentMethod.paymentMethodTypeId}] for payment method [${parameters.paymentMethodId}]"/>
<set field="parameters.paymentMethodTypeId" from-field="paymentMethod.paymentMethodTypeId"/>
</if-compare-field>
</if-not-empty>
<if-not-empty field="parameters.paymentPreferenceId">
<entity-one value-field="orderPaymentPreference" entity-name="OrderPaymentPreference">
<field-map field-name="orderPaymentPreferenceId" from-field="parameters.paymentPreferenceId"/>
</entity-one>
<if-empty field="parameters.paymentMethodId">
<set field="parameters.paymentMethodId" from-field="orderPaymentPreference.paymentMethodId"/>
</if-empty>
<if-empty field="parameters.paymentMethodTypeId">
<set field="parameters.paymentMethodTypeId" from-field="orderPaymentPreference.paymentMethodTypeId"/>
</if-empty>
</if-not-empty>
<if-empty field="parameters.paymentMethodTypeId">
<add-error>
<fail-property resource="AccountingUiLabels" property="AccountingPaymentMethodIdPaymentMethodTypeIdNullError"/>
</add-error>
</if-empty>

<set-nonpk-fields map="parameters" value-field="payment"/>
<if-empty field="payment.effectiveDate">
<now-timestamp field="payment.effectiveDate"/>
</if-empty>
<create-value value-field="payment"/>
</simple-method>

异步方式调用

<simple-method method-name="sendInvoicePerEmail" short-description="Send an invoice per Email">
<set-service-fields service-name="sendMailFromScreen" map="parameters" to-map="emailParams"/>
<set field="emailParams.xslfoAttachScreenLocation" value="component://accounting/widget/AccountingPrintScreens.xml#InvoicePDF"/>
<set field="emailParams.bodyParameters.invoiceId" from-field="parameters.invoiceId"/>
<set field="emailParams.bodyParameters.userLogin" from-field="parameters.userLogin"/>
<set field="emailParams.bodyParameters.other" from-field="parameters.other"/><!-- to to print in 'other currency' -->
<call-service-asynch service-name="sendMailFromScreen" in-map-name="emailParams"/>
<property-to-field resource="AccountingUiLabels" property="AccountingEmailScheduledToSend" field="successMessage"/>
</simple-method>

异步调用代码

<call-service-asynch service-name="sendMailFromScreen" in-map-name="emailParams"/>

服务中的事务申明
一个服务是否使用事务，是否必须是独立的事务，以及事务的超时时间设置，均可以在服务定义时声明，或者在通过服务引擎调用服务时指定（传入）
1、服务定义时申明事务
例：applications/order/servicedef/services.xml

<service name="sendOrderConfirmation" engine="java" require-new-transaction="true" max-retry="3"
location="org.ofbiz.order.order.OrderServices" invoke="sendOrderConfirmNotification">
<description>Send a order confirmation</description>
<implements service="orderNotificationInterface"/>
</service>

2、在服务调用时指定
java代码

dispatcher.runSync(servicename, context,transactionTimeOut,requireNewTransaction);
dispatcher.runAsync(servicename, context,requester,persist,transactionTimeOut,requireNewTransaction);

事务的管理规则
1、调用服务时传入的参数（是否为独立事务、事务的超时时间）的优先级高于服务定义时定义的参数
2、若服务在定义时声明了不使用事务（use-transaction="false")，那么无论是定义什么的独立事务和超市时间，还是调用服务的时候定义了独立事务和超市时间，都将不会生效
3、服务被申明为不使用事务，则所有的默认为每次操作位一个独立的事务

事务的提交规则
1、没有在服务内部显示操作事务的情况下，事务由服务引擎来管理，当服务返回error时，回滚事务；当服务返回failure或success时提交事务
2、服务间调用使用同一个事务时，内层服务返回failure或success，不提交事务，在最外层服务返回时方提交
3、服务间调用使用同一个事务时，任何一个服务返回error，事务均会回滚。
4、服务间调用使用独立事务时，一个事务回滚或提交不影响其他事务，但一个事务不能访问另一个事务尚未提交的数据
5、服务执行超时，回滚事务

服务超时
1、服务执行是否超时由服务引擎来控制，超时时间，在定义服务时指定，或调用服务的时候指定，若不指定，默认时间为60秒
2、这个超时时间为服务执行的总时间，包括服务内部执行的其他操作时间的总和
3、如果没有开启事务，则配置超时时间也不会生效。

EEAC、SEAC、MCA概念
EEAC：在实体上触发一个服务的调用
SEAC：当条件满足时，调用另外一个服务
MCA：启动javamail-container