ofbiz进阶分析--minilang(迷你语言)

 

simple-map-processor 和 simple-method XML files

simple-map-processor的两个主要功能：校验，转换

Simple Map Processors Example

<!DOCTYPE simple-map-processors PUBLIC "-//OFBiz//DTD Simple Methods//EN" "http://www.ofbiz.org/dtds/simple-methods.dtd">
	

	
<simple-map-processors>

	
<simple-map-processor name="update">

	
<make-in-string field="estimatedStartDate">
	
<in-field field="estimatedStartYear"><constant>-</constant>
	
<in-field field="estimatedStartMonth"><constant>-</constant>
	
<in-field field="estimatedStartDay"><constant>T</constant>
	
<in-field field="estimatedStartHour"><constant>:</constant>
	
<in-field field="estimatedStartMinute"><constant>:</constant>
	
<in-field field="estimatedStartSecond">
	
</make-in-string>

	
<process field="workEffortId"><copy replace="false"/></process>
	
<process field="scopeEnumId"><copy/></process>
	
<process field="currentStatusId"><copy/><not-empty><fail-message message="Status is missing."/></not-empty></process>
	
<process field="priority"><convert type="Long"><fail-message message="Priority is not a valid whole number."/></convert></process>

	
<process field="estimatedStartDate">
	
<compare-field operator="less" field="estimatedCompletionDate" type="Timestamp" format="yyyy-MM-dd'T'HH:mm:ss">
	
<fail-message message="Estimated Start date/time must be BEFORE End date/time."/></compare-field>
	
<convert type="Timestamp" format="yyyy-MM-dd'T'HH:mm:ss">
	
<fail-message message="Estimated Start Date is not a valid Date-Time."/></convert></process>

	
<process field="estimatedCompletionDate">
	
<convert type="Timestamp"><fail-message message="Estimated Completion Date is not a valid Date-Time."/></convert></process>
	
<process field="estimatedMilliSeconds">
	
<convert type="Double"><fail-message message="Estimated Milli-seconds is not a valid number."/></convert></process>
	
</simple-map-processor>

	
<simple-map-processor name="delete">
	
<process field="workEffortId"><copy/><not-empty><fail-message message="Work Effort ID is missing."/></not-empty></process>
	
</simple-map-processor>

	
</simple-map-processors>

simple-method 是可以被Control Servlet 或 a service 调用的Event的的简单实现

<event type="simple" path="org/ofbiz/commonapp/workeffort/workeffort/WorkEffortSimpleEvents.xml" invoke="update"/>

Sm 可以被作为static 方法调用(调用者可以是Control Servlet or a service)，或者作为一个类调用(调用者可以是Control Servlet or a service)，也可以通过一个Entity 的 controller 配置文件：

<event type="simple" path="org/ofbiz/commonapp/workeffort/workeffort/WorkEffortSimpleEvents.xml" invoke="update"/>

或一个 service 通过一个entry 在一个 services.xml 文件，像下面：

<service name="createPartyRole" engine="simple"
location="org/ofbiz/commonapp/party/party/PartyRoleServices.xml" invoke="createPartyRole" auth="true">
<description>Create a Party Role (add a Role to a Party)</description>
<attribute name="partyId" type="String" mode="IN" optional="true"/>
<attribute name="roleTypeId" type="String" mode="IN" optional="false"/>
</service>

Mini-Language 可以调用 Simple Map Processors, Services and bsh scripts, 操作 entity 相关的操作, and 创建消息返回给调用者. Specific operations can be 附上 in if blocks to execute conditionally and values or fields can be copied around in the maps, lists and method environment.

有许多标签可以得到或者设置属性 到/从一个 request 或者 session object 当被作为一个事件调用 或者设置属性作为返回结果当作为一个服务的时候。如果你包含一个env-to-request 操作，它将仅仅被作为一个enent的时候才会被调用 。一个a env-to-result 操作见仅仅被作为一个service时才可以调用。 Everything else is the same when called as an event or a service which makes it easy to write 灵活的逻辑that can be mounted/applied in various ways.

下面是simple-method标签的完整的属性表:

 

AttributeName	Reqd?	DefaultValue	Description
method-name	Y	N/A	A name (preferably a legal Java identifier) for this method. This name must be unique for the XML file it is in as it will be used to reference this method externally.
short-description	Y	N/A	A short description of the method for certain system error messages.
login-required	N	"true"	Is a logged in user (UserLogin object, or login.username and login.password Strings) required to run this method? "true" or "false".
use-transaction	N	"true"	Create a transaction if none exists for this thread? "true" or "false".
default-error-code	N	"error"	The default error return code.
default-success-code	N	"success"	The default success return code.
parameter-map-name	N	"parameters"	As event: copy of request parameters As service: incoming context
event-request-object-name	N	"request"	(as event only)
event-response-code-name	N	"_response_code_"	(as event only)
event-error-message-name	N	"_error_message_"	(as event only)
event-event-message-name	N	"_event_message_"	(as event only)
service-response-message-name	N	"responseMessage"	(as service only)
service-error-message-name	N	"errorMessage"	(as service only)
service-error-message-list-name	N	"errorMessageList"	(as service only)
service-success-message-name	N	"successMessage"	(as service only)
service-success-message-list-name	N	"successMessageList"	(as service only)
delegator-name	N	"delegator"	A GenericDelegator object to use in the method
security-name	N	"security"	A Security object to use in the method
dispatcher-name	N	"dispatcher"	A LocalDispatcher object to use in the method

---

访问特殊 Contex的语法

访问Map成员，属性field-name="product.productName" 将引用product Map的productName成员，另一种写法是map-name="product" field-name="productName" ，下面的写法更加自由：name="products.widget.productName"，这句将访问products （Map类型）的widget成员(也是一个Map类型)的productName成员

访问List 成员，例子：field-name="products[0].productName"将访问products(List类型)的第一个元素的productName属性。为了更有用，，你可以从环境中得到一个List的索引，如：field-name="products[${currentIndex}].productName"，甚至一个Map的引用：field-name="products[${currentIndex}].${currentMember}"

Call Operations

call-map-processor

call-map-processor 标签调用一个简单的map processor 从一个存在的map 或创建一个新的map 或者添加到已经存在的map中去，如果这个名字的out-map 已经存在的话。 Resulting messages 被加入一个命名的 list, 如果这个名字的list不存在的话，一个新的List就会被创建. 记住，同一个context中所有的map和list必须有唯一的名字

 

AttributeName	Required?	Description
xml-resource	N	The full path and filename on the classpath of the XML file which contains an external map processor to execute. This is only required if an external map processor is desired.
processor-name	N	The name of the external map processor to execute in the specified xml-resource. This is only required if an external map processor is desired.
in-map-name	Y	The name of a map in the method environment to use as the input map.
out-map-name	Y	The name of a map in the method environment to use as the output map. Will be created if it does not exist already. If already exists will be added to in place.
error-list-name	N	The name of a list in the method environment that the error messages will be added to. Will be created if it does not exist. Defaults to "error_list".

Sub-ElementName	HowMany	Description
simple-map-processor	0 or 1	Uses the same definition as the simple-map-processor in the context of a simple-map-processors XML file. Allows for an inlined simple-map-processor.

call-service

 

这个标签通过服务引擎调用一个服务，如果特殊的error code被返回，那么事件会被丢弃，当前线程中的事务会被回滚。否则，就继续处理下去

result-to-request 和 result-to-session elements will be 忽略当调用一个service context的时候

 

 

AttributeName	Required?	Description
service-name	Y
in-map-name	Y
include-user-login	N	Defaults to "true".
error-code	N	Defaults to "error".
success-code	N	Defaults to "success".

Sub-ElementName	HowMany	Description
error-prefix	0 or 1
error-suffix	0 or 1
success-prefix	0 or 1
success-suffix	0 or 1
message-prefix	0 or 1
message-suffix	0 or 1
default-message	0 or 1
results-to-map	0 to many
result-to-field	0 to many
result-to-request	0 to many
result-to-session	0 to many
result-to-result	0 to many

 

call-service-asynch

 

返回结果会被忽略，因此没有返回消息会被使用，但会有系统错误，如：数据库错误

 

AttributeName	Required?	Description
service-name	Y
in-map-name	Y
include-user-login	N	Defaults to "true".

 

 

call-bsh

 

bsh的context 是当前simple-method 环境中的maps, lists 和特殊的objects whose names are defined in the simple-method attributes.

The current env 不能被修改, but if a Map 被返回 by the bsh block ,map 中的成员将被存入当前的 env.

Error messages go on the error list and are handled with the check-errors tag.

 

AttributeName	Required?	Description
resource	N
error-list-name	N	Defaults to "error_list".

 

 

call-simple-method

 

call-simple-method 标签调用另一个simple-method 在同一个 context中, 包括所有的environment fields, either the event or service objects that the calling simple-method was called with.

 

AttributeName	Required?	Description
xml-resource	N	The full path and filename on the classpath of the XML file which contains an external simple-method to execute. This is only required if a simple-method in a different file is desired.
method-name	Y	The name of the simple-method to execute in the specified xml-resource, or in the current XML file if no xml-resource is specified.

---

 

 

Java Call Operations

create-object

out-map 同上，simple-map-processor 标签可以放在 call-map-processor 标签里面。

 

 

AttributeName	Required?	Description
xml-resource	N	The full path and filename on the classpath of the XML file which contains an external map processor to execute. This is only required if an external map processor is desired.
processor-name	N	The name of the external map processor to execute in the specified xml-resource. This is only required if an external map processor is desired.
in-map-name	Y	The name of a map in the method environment to use as the input map.
out-map-name	Y	The name of a map in the method environment to use as the output map. Will be created if it does not exist already. If already exists will be added to in place.
error-list-name	N	The name of a list in the method environment that the error messages will be added to. Will be created if it does not exist. Defaults to "error_list".

Sub-ElementName	HowMany	Description
simple-map-processor	0 or 1	Uses the same definition as the simple-map-processor in the context of a simple-map-processors XML file. Allows for an inlined simple-map-processor.

call-object-method

Calls a method on an existing object that exists in a field in the environment or in a map in the environment.

The string and field sub-elements are passed to the method as arguments in the order they are specified. If the sub-elements do not match the method arguments an error will be returned.

The return value will be put in the named field if an value is returned and if a field and optionally a map name are specified.

 

AttributeName	Required?	Description
obj-field-name	Y	The name of the field the object is in that has the method to be called.
obj-map-name	N	The name of the map the field of the object is in that has the method to be called. If this is not specified the environment will be used to find the field in.
method-name	Y	The name of the method to call on the given object.
ret-field-name	N	The name of the field to put the result in. If not specified any return value will be ignored.
ret-map-name	N	The name of the map the field of the return value is in. If not specified but the field name is then the environment will be used to find the field in.

Sub-ElementName	HowMany	Description
string	0 to many	Used to specify an inline String argument to the method call.
field	0 to many	Used to specify a field to be passed as an argument to the method call. The field can be in a map in the environment or if no map-name is specified then the field will come directly from the environment.

call-class-method

Calls a static method on a class.

The string and field sub-elements are passed to the method as arguments in the order they are specified. If the sub-elements do not match the method arguments an error will be returned.

The return value will be put in the named field if an value is returned and if a field and optionally a map name are specified.

 

AttributeName	Required?	Description
class-name	Y	The name of the class to call the static method on.
method-name	Y	The name of the static method to call on the given class.
ret-field-name	N	The name of the field to put the result in. If not specified any return value will be ignored.
ret-map-name	N	The name of the map the field of the return value is in. If not specified but the field name is then the environment will be used to find the field in.

Sub-ElementName	HowMany	Description
string	0 to many	Used to specify an inline String argument to the method call.
field	0 to many	Used to specify a field to be passed as an argument to the method call. The field can be in a map in the environment or if no map-name is specified then the field will come directly from the environment.

---

 

 

call-simple-method

 

 

Method Environment Operations

 

map-to-map

field-to-field

 

The field-to-field tag copies a field from a map to a field in another map.

 

field-to-list

The field-to-list tag appends a field to the specified list.

 

env-to-field

The env-to-field tag copies a field from the method environment to a field in a map.

 

field-to-env

The field-to-env tag copies a field from a map to a field in the method environment.

string-to-field

The string-to-field tag puts the inlined string value in the specified field.

string-to-list

The string-to-list tag appends the inlined string value in the specified List.

to-string

The to-string tag converts the Object in the specified field to a String, putting the string in the same field.

 

clear-field

The clear-field tag clears/removes the specified field.

 

AttributeName	Required?	Description
map-name	N	The name of the map in the method environment. If not specified the field-name will be used to get the field from the method environment.
field-name	Y	The name (key) of the map field to use.

iterate

The operations contained by the iterate tag will be executed for each of the entries in the list, and will make the current entry available in the method environment by the entry-name specified. This tag can contain any of the simple-method operations, including the conditional/if operations.

 

first-from-list

The first-from-list tag will get the first entry from the given list and put it in the environment field with the given entry-name.

Entity Engine Misc. Operations

now-timestamp-to-env

The now-timestamp-to-env tag creates a java.sql.Timestamp object with the current date and time in it and puts it in a field in the method environment

now-date-to-env

The now-date-to-env tag creates a java.sql.Date object with the current date in it and puts it in a field in the method environment.

sequenced-id-to-env

The sequenced-id-to-env tag gets a sequenced ID from the Entity Engine (through the delegator) and puts it in the specified method environment field. The object will be a java.lang.Long, but can of course be converted to a String.

 

AttributeName	Required?	Description
sequence-name	Y	The name of the sequence to pass to the delegator. The same name must always be used for sequenced IDs that will be used for a certain entity field otherwise non-unique keys may result.
env-name	Y	The name of the method environment field the sequenced ID will be put in.

set-current-user-login

The set-current-user-login tag sets the UserLogin GenericValue object to be used for authentication for the rest of the method. This is mostly used for calling services, etc.

 

AttributeName	Required?	Description
value-name	Y	The name of the method environment field that contains the UserLogin GenericValue object.

 

 

Entity Engine Find Operations

find-by-primary-key

The find-by-primary-key tag uses the delegator to find an entity value by its primary key. The resulting GenericValue object will be placed in the method environment using the specified value-name.

 

find-by-and

The find-by-and tag uses the delegator to find entity values by anding the fields passed in the map. The resulting GenericValue objects will be placed in the method environment using the specified list-name.

filter-list-by-and

The filter-list-by-and tag filters the given list by the fields in the specified map.

 

Entity Engine Value Operations

make-value

The make-value tag uses the delegator to construct an entity value. The resulting value will not necessarily exist in the database, but will simply be assembled using the entity-name and fields map. The resulting GenericValue object will be placed in the method environment using the specified value-name.

 

AttributeName	Required?	Description
value-name	Y	The name of the method environment field that contains the GenericValue object.
entity-name	Y	The name of the entity to construct an instance of.
map-name	N	The name of a map in the method environment that will be used for the entity fields.

clone-value

The clone-value tag make a copy of the value in the method environment field specified by value-name. The resulting GenericValue object will be placed in the method environment using the specified new-value-name.

 

AttributeName	Required?	Description
value-name	Y	The name of the method environment field that contains the GenericValue object.
new-value-name	Y	The name of the method environment field that will contain the new GenericValue object.

create-value

The create-value tag persists the specified GenericValue object by creating a new instance of the entity in the datasource. An error will result if an instance of the entity exists in the datasource with the same primary key.

 

AttributeName	Required?	Description
value-name	Y	The name of the method environment field that contains the GenericValue object.

 

store-value

The store-value tag persists the specified GenericValue object by updating the instance of the entity in the datasource. An error will result if an instance of the entity does not exist in the datasource with the same primary key.

 

AttributeName	Required?	Description
value-name	Y	The name of the method environment field that contains the GenericValue object.

remove-value

The remove-value tag removes the specified GenericValue object by removing the instance of the entity in the datasource. An error will result if an instance of the entity does not exist in the datasource with the same primary key.

 

AttributeName	Required?	Description
value-name	Y	The name of the method environment field that contains the GenericValue object.

remove-by-and

The remove-by-and tag uses the delegator to remove entity values from the datasource and is constrained by anding the fields passed in the map. Make sure the map contains something, or all values will be removed.

 

AttributeName	Required?	Description
entity-name	Y	The name of the entity to remove instances of.
map-name	Y	The name of a map in the method environment that will be used for the entity fields.

clear-cache-line

Uses the delegator to clear elements from the cache; intelligently looks at the map passed to see if it is a byPrimaryKey, and byAnd, or an all.

 

AttributeName	Required?	Description
entity-name	Y	The name of the entity to clear cache lines of.
map-name	Y	The name of a map in the method environment that will be used for the entity fields. If the fields in the map form the full primary key the entry will be removed from the byPrimaryKey cache. If the map exists but the fields do not include a full primary key the entry will be removed from the byAnd cache. If no map-name is specified the entry will be removed from the all cache.

clear-entity-caches

This is a very simple tag that should be used sparingly because of the performance impact. It clears all lines from all Entity Engine caches. It has no attributes or sub-elements.

set-pk-fields

Looks for each PK field in the named map and if it exists there it will copy it into the named value object.

 

AttributeName	Required?	Description
value-name	Y	The name of the method environment field that contains the GenericValue object.
map-name	Y	The name of a map in the method environment that will be used for the entity fields.
set-if-null	N	Specifies whether or not to set fields that are null or empty. Defaults to true.

set-nonpk-fields

Looks for each non-PK field in the named map and if it exists there it will copy it into the named value object.

 

AttributeName	Required?	Description
value-name	Y	The name of the method environment field that contains the GenericValue object.
map-name	Y	The name of a map in the method environment that will be used for the entity fields.
set-if-null	N	Specifies whether or not to set fields that are null or empty. Defaults to true.

 

Entity Engine List Operations

 

 

 

 

 

Simple Methods Example

<!DOCTYPE simple-methods PUBLIC "-//OFBiz//DTD Simple Methods//EN" "http://www.ofbiz.org/dtds/simple-methods.dtd">
	

	
<simple-methods>
	
<simple-method method-name="createProduct" short-description="Create an Product">
	
<check-permission permission="CATALOG" action="_CREATE"><fail-message message="Security Error: to run createProduct you must have the CATALOG_CREATE or CATALOG_ADMIN permission"/></check-permission>
	
<check-id field-name="productId" map-name="parameters"/>
	
<check-errors/>
	

	
<make-value value-name="newEntity" entity-name="Product"/>
	
<set-nonpk-fields map-name="parameters" value-name="newEntity"/>
	
<set-pk-fields map-name="parameters" value-name="newEntity"/>
	

	
<now-timestamp-to-env env-name="nowTimestamp"/>
	
<env-to-field env-name="nowTimestamp" field-name="lastModifiedDate" map-name="newEntity"/>
	
<env-to-field env-name="nowTimestamp" field-name="createdDate" map-name="newEntity"/>
	
<field-to-field field-name="userLoginId" map-name="userLogin" to-field-name="lastModifiedByUserLogin" to-map-name="newEntity"/>
	
<field-to-field field-name="userLoginId" map-name="userLogin" to-field-name="createdByUserLogin" to-map-name="newEntity"/>
	

	
<create-value value-name="newEntity"/>
	

	
<!-- induce keywords if autoCreateKeywords is emtpy or Y-->
	
<if-empty field-name="autoCreateKeywords" map-name="newEntity">
	
<call-bsh><![CDATA[org.ofbiz.commonapp.product.product.KeywordSearch.induceKeywords(newEntity);]]></call-bsh>
	
<else>
	
<if-compare field-name="autoCreateKeywords" map-name="newEntity" operator="equals" value="Y">
	
<call-bsh><![CDATA[org.ofbiz.commonapp.product.product.KeywordSearch.induceKeywords(newEntity);]]></call-bsh>
	
</if-compare>
	
</else>
	
</if-empty>
	
</simple-method>
	
<simple-method event-name="create" short-description="Create Work Effort">
	
<call-map-processor xml-resource="org/ofbiz/commonapp/workeffort/workeffort/WorkEffortMapProcessors.xml" 
	
processor-name="update" in-map-name="parameters" out-map-name="context"/>
	
<check-errors/>
	
<call-service service-name="createWorkEffort" in-map-name="context">
	
<default-message>Work Effort successfully created.</default-message>
	
<result-to-request result-name="workEffortId"/></service>
	
</simple-method>
	
<simple-method event-name="update" short-description="Update Work Effort">
	
<call-map-processor xml-resource="org/ofbiz/commonapp/workeffort/workeffort/WorkEffortMapProcessors.xml" 
	
processor-name="update" in-map-name="parameters" out-map-name="context"/>
	
<check-errors/>
	
<call-service service-name="updateWorkEffort" in-map-name="context">
	
<default-message>Work Effort successfully updated.</default-message></service>
	
</simple-method>
	
</simple-methods>