simple-map-processor 和 simple-method XML files
simple-map-processor的两个主要功能：校验，转换
Simple Map Processors Example
- - T : :
simple-method 是可以被Control Servlet 或 a service 调用的Event的的简单实现
Sm 可以被作为static 方法调用(调用者可以是Control Servlet or a service)，或者作为一个类调用(调用者可以是Control Servlet or a service)，也可以通过一个Entity 的 controller 配置文件：
或一个 service 通过一个entry 在一个 services.xml 文件，像下面：
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 |
| 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
Work Effort successfully created. Work Effort successfully updated.