加载服务定义文件
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
1 public static String indexTree(HttpServletRequest request, HttpServletResponse response) { 2 3 Map<String, Object> result; 4 Map<String, Object> serviceInMap = FastMap.newInstance(); 5 HttpSession session = request.getSession(); 6 GenericValue userLogin = (GenericValue)session.getAttribute("userLogin"); 7 serviceInMap.put("userLogin", userLogin); 8 LocalDispatcher dispatcher = (LocalDispatcher) request.getAttribute("dispatcher"); 9 Map<String, Object> paramMap = UtilHttp.getParameterMap(request); 10 String siteId = (String)paramMap.get("contentId"); 11 serviceInMap.put("contentId", siteId); 12 try { 13 result = dispatcher.runSync("indexTree", serviceInMap); 14 } catch (GenericServiceException e) { 15 String errorMsg = "Error calling the indexTree service." + e.toString(); 16 Debug.logError(e, errorMsg, module); 17 request.setAttribute("_ERROR_MESSAGE_", errorMsg + e.toString()); 18 return "error"; 19 } 20 String errMsg = ServiceUtil.getErrorMessage(result); 21 if (Debug.infoOn()) Debug.logInfo("errMsg:" + errMsg, module); 22 if (Debug.infoOn()) Debug.logInfo("result:" + result, module); 23 if (UtilValidate.isEmpty(errMsg)) { 24 List<String> badIndexList = UtilGenerics.checkList(result.get("badIndexList")); 25 if (Debug.infoOn()) Debug.logInfo("badIndexList:" + badIndexList, module); 26 String badIndexMsg = StringUtil.join(badIndexList, "\n") + badIndexList.size() + " entities not indexed"; 27 Integer goodIndexCount = (Integer)result.get("goodIndexCount"); 28 String goodIndexMsg = goodIndexCount + " entities indexed."; 29 if (Debug.infoOn()) Debug.logInfo("goodIndexCount:" + goodIndexCount, module); 30 ServiceUtil.setMessages(request, badIndexMsg, goodIndexMsg, null); 31 return "success"; 32 } else { 33 ServiceUtil.setMessages(request, errMsg, null, null); 34 return "error"; 35 } 36 }
调用服务
1 try { 2 result = dispatcher.runSync("indexTree", serviceInMap); 3 } catch (GenericServiceException e) { 4 String errorMsg = "Error calling the indexTree service." + e.toString(); 5 Debug.logError(e, errorMsg, module); 6 request.setAttribute("_ERROR_MESSAGE_", errorMsg + e.toString()); 7 return "error"; 8 }
如上调用了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