Access to add and change pages is restricted. See: https://cwiki.apache.org/confluence/display/OFBIZ/Wiki+access

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 14 Next »

Written By: David E. Jones, jonesde@ofbiz.org


Table of Contents


Introduction


The Mini-Language concept in Open For Business is similar to the Gang of Four Interpreter pattern, or the Mark Grand Little Language pattern. This is also the central theme of the Building Parsers with Java book by Steven John Metsker which the OFBiz Rule Engine is based on. The idea is to create simple languages that simplify complex or frequently performed tasks.

In business software there are things that are done hundreds or thousands of times in a single application that a Mini-Language can simplify to the point of cutting implementation and maintenance times not by just 50%, but often as much as 70-90%. Yes, certain tasks will take only 10% of the effort and knowledge to perform. This makes it easier people not familiar with the software to manipulate existing or build new functionality.

Mini-Languages tend to have instructions that are more like method calls in a general purpose language. They are meant to solve a specific problem in a specific context, and are generally worthless or need to be modified for other contexts or problems.

Often this idea is implemented using a free form (BNF) or english-like syntax. In Open For Business the Mini-Languages are expressed as XML files to simplify the learning and manipulation of the syntax, in addition to making the Mini-Languages easier to write and extend.

The XML schema (XSD) for the simple-map-processor and simple-method XML files is in the distribution in framework/minilang/dtd/simple-methods.xsd or on the website at [<span style="color: #ff0000"><strong>to be modified</strong></span> [www.ofbiz.org/dtds/simple-methods.xsd]]. These are combined into a single file to make it easy to use inlined simple-map-processors inside a simple-method.

To specify the XMLschema for a simple-methods or simple-map-processors XML file use the following:

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="[to be modified www.ofbiz.org/dtds/simple-methods.xsd]">



The Simple Map Processor Mini-Language


Simple Map Processor Overview

The Simple Map Processor Mini-Language performes two primary tasks: validation and conversion. It does this in a context of moving values from one Map to another. The input map will commonly contain Strings, but can contain other object types like Integer, Long, Float, Double, java.sql.Date, Time, and Timestamp.

(info) NOTE: The reference information for the simple-map-processor has been moved to annotations in

[to be modified

www.ofbiz.org/dtds/simple-methods.xsd]

We hope to recommended soon a tool that will use XSL/Transform to render the documentation directly from the XSD file in Browsers




Simple Map Processors Example


<simple-map-processors xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:noNamespaceSchemaLocation="[to be modified www.ofbiz.org/dtds/simple-methods.xsd]">
	<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>




The Simple Method Mini-Language

  • Simple Method Overview
  • Special Context Access Syntax
  • Call Operations
  • Java Call Operations
  • Control and Error Handling Operations
  • Event Specific Operations
  • Service Specific Operations
  • Method Environment Operations
  • Entity Engine Misc. Operations
  • Entity Engine Find Operations
  • Entity Engine Value Operations
  • Entity Engine List Operations
  • Entity Engine Transaction Operations
  • Conditional (If) Operations
  • Other Operations
  • Simple Methods Example

Simple Method Overview

The Simple Method Mini-Language is a simple way to implement an event that is invoked by the Control Servlet or a service that is invoked by the Service Engine. A Simple Method can be invoked through the static methods on the SimpleMethod class, or as an event through an entry in the controller configuration XML file like the following:

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

or as a service through an entry in a services.xml file like the following:

<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>

The path or location for a Simple Method is the classpath and filename of the XML file.

In this Mini-Language you can invoke Simple Map Processors, Services and bsh scripts, perform entity related operations, and create messages to return to the caller. Specific operations can be enclosed in if blocks to execute conditionally and values or fields can be copied around in the maps, lists and method environment.
There are a number of tags which can be used to get and set attributes to/from a request or session object when called as an event or to set attributes in the result when called as a service. These operations are only applied when applicable. In other words if you include an env-to-request operation it will only be invoked when the simple-method is called as an event and an env-to-result operation will only be invoked when the simple-method is called as a service. Everything else is the same when called as an event or a service which makes it easy to write flexible logic that can be mounted/applied in various ways.
There are a number of objects that exist in the method environment when a simple-method starts or that are used as it executes to keep track of certain information. Some will exist when called as an event or a service, these are marked in the XSD. Each name can be overridden using an attribute on the simple-method tag. The defaults are listed below in the XSD.

(info) NOTE: The reference information for simple-method has been moved to annotations in

[to be modified

www.ofbiz.org/dtds/simple-methods.xsd]
We hope to recommended soon a tool that will use XSL/Transform to render the documentation directly from the XSD file in Browsers








Special Context Access Syntax

In strings and field names a special syntax is supported to flexibly access Map member, List elements and to insert environment values into string constants.

The ${} (dollar-sign-curly-brace) syntax can be used to insert an environment variable value in pretty much any string constant in a simple-method file. Not only can it be used to reference top-level envrionment variables, the syntax elements described below can be used to access values in sub-structures.

You can use the "." (dot) syntax to access Map members. For example if you specify the attribute field-name="product.productName"it will reference the productName member of the productMap. This would be the same as specifying map-name="product" field-name="productName". Note that this is, of course, more flexible than a field-name/map-name combination because the Map structure can be multiple levels deep. For example if you have use the attributefield-name="products.widget.productName" it will reference the productName in the widget Map which is in the products Map.

The "[]" (square-brace) syntax can be used to access list elements. For example you can specify the attribute field-name="products[0].productName"and it will reference the productName of the first (position zero) element in the products List. To make this more useful you can pull a list index from the environment using something like field-name="products[${currentIndex}].productName".

There are two extensions to the [] syntax that can be used when refering to an environment location that is the target of an operation. If you do not include a number between the square braces the value will be put at the end of the list. If you put a "+" (plus sign) in front of the number between the square braces (ie: [+2]) it will insert the value before that position in the list instead of replacing the value at that location. For example, specifying [+0] would insert the value at the beginning of the list.

In fact, you can use the ${} syntax to substitute any string or other value at any location in a field-name or other string constant. So, you could even reference a Map member named in some other environment variable. For example you could use field-name="products[${currentIndex}].productName".

Okay, enough of the general stuff, you may find in the XSD file descriptions of the available operations. Here is simply a categorized list of them.


Call Operations

call-map-processor
call-service
call-service-asynch
call-bsh
call-simple-method


Java Call Operations

create-object
call-object-method
call-class-method


Control and Error Handling Operations

check-errors
add-error
return


Event Specific Operations

field-to-request
field-to-session
request-to-field
request-parameters-to-list
session-to-field
webapp-property-to-field

Service Specific Operations

field-to-result


Method Environment Operations

map-to-map
field-to-list
to-string
clear-field

[All operations in red have been be replaced by set operation] 

field-to-field (deprecated, do not use)
env-to-env (deprecated, do not use)
env-to-field (deprecated, do not use)
field-to-env (deprecated, do not use)
string-to-field (deprecated, do not use)


Control Operations

iterate
first-from-list


Entity Engine Misc. Operations

now-timestamp-to-env
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.

Attribute Name

Required?

Description

env-name

Y

The name of the method environment field the date will be put in.

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.

Attribute Name

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.

Attribute Name

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.

Attribute Name

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 find an instance of.

map-name

Y

The name of a map in the method environment that will be used for the entity fields.

delegator-name

N

By default this operation is done using the delegator that is part of the simple-method calling context. This allows you to override the default delegator by naming an alternate delegator.

use-cache

N

Specifies whether or not the delegator's cache should be searched before going to the database. This results in much faster retrieval times, but can return stale data that is not the most current in the database. Must be "true" or "false", defaults to "false".

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.

Attribute Name

Required?

Description

list-name

Y

The name of the method environment field that contains the list of GenericValue objects.

entity-name

Y

The name of the entity to find instances of.

map-name

Y

The name of a map in the method environment that will be used for the entity fields.

order-by-list-name

Y

The name of a list in the method environment that contains a list of strings specifying fields to order the results by.

delegator-name

N

By default this operation is done using the delegator that is part of the simple-method calling context. This allows you to override the default delegator by naming an alternate delegator.

use-cache

N

Specifies whether or not the delegator's cache should be searched before going to the database. This results in much faster retrieval times, but can return stale data that is not the most current in the database. Must be "true" or "false", defaults to "false".

use-iterator

N

Specifies whether or not to use the EntityListIterator when doing the query. This is much more efficient for large data sets because the results are read incrementaly instead of all at once. Note that when using this the use-cache setting will be ignored. Also note that an EntityListIterator must be closed when you are finished, but this is done automatically by the iterate operation. Must be "true" or "false", defaults to "false".

filter-list-by-and

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

Attribute Name

Required?

Description

list-name

Y

The name of the method environment field that contains the list of GenericValue objects.

to-list-name

N

The name of the method environment field the filtered list will be put into. Defaults to the value of the list-name attribute (ie goes to the same place it came from, replacing the old list).

map-name

N

The name of a map in the method environment that will be used for the entity fields. If no map is used this will just make a copy of the list.

filter-list-by-date

The filter-list-by-date tag filters the given list by the valid date using the from and thru dates in each value object.

Attribute Name

Required?

Description

list-name

Y

The name of the method environment field that contains the list of GenericValue objects.

to-list-name

N

The name of the method environment field the filtered list will be put into. Defaults to the value of the list-name attribute (ie goes to the same place it came from, replacing the old list).

valid-date-name

N

The name of a field in the method environment date to filter by. Defaults to now.

from-field-name

N

The name of the GenericValue field to use as the beginning effective date. Defaults to fromDate.

thru-field-name

N

The name of the GenericValue field to use as the ending effective date. Defaults to thruDate.

all-same

N

Specifies whether or not all GenericValue objects in the list are of the same entity. Defaults to true.


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.

Attribute Name

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.

Attribute Name

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.

Attribute Name

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.

Attribute Name

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.

Attribute Name

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.

Attribute Name

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.

Attribute Name

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.

Attribute Name

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.

Attribute Name

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

store-list

The store-list tag uses the delegator to store all entity values in the list. This is different than storing a single value in that values in the list will be inserted if it does not exist or updated if it does exist.

Attribute Name

Required?

Description

list-name

Y

The name of the method environment field that contains the list of GenericValue objects.

remove-list

The remove-list tag uses the delegator to remove all entity values in the list. For each value in the list if it is a primary key just that entity instance will be removed, but if it is not a full primary key all entity instances will be removed from the datasource that match the constraint of the field map.

Attribute Name

Required?

Description

list-name

Y

The name of the method environment field that contains the list of GenericValue objects.


Entity Engine Transaction Operations

transaction-begin

The transaction-begin tag will begin a transaction if one is not already in place. If a transaction is begun the environment field named as the began-transaction-name will be set to true, otherwise it will be set to false.

Note that unless the simple-method is flagged to not use a transaction all simple-methods will be inside a transaction. The same is true for service calls through the Service Engine.

Attribute Name

Required?

Description

began-transaction-name

N

The name of the method environment field that contains a Boolean specifying whether or not a transaction was begun in the current transaction demarcation. Defaults to "beganTransaction".

transaction-commit

The transaction-commit tag will commit a transaction if a transaction was begun in the current demarcation context as represented by the environment field named as the began-transaction-name. If the Boolean in that field is false no commit will be done.

Attribute Name

Required?

Description

began-transaction-name

N

The name of the method environment field that contains a Boolean specifying whether or not a transaction was begun in the current transaction demarcation. Defaults to "beganTransaction".

transaction-rollback

The transaction-rollback tag will rollback a transaction if a transaction was begun in the current demarcation context as represented by the environment field named as the began-transaction-name. If the Boolean in that field is false a set rollback only will operation will be done instead of rollback which will force the transaction to rollback regardless of which method or object is responsible for beginning and ending the transaction.

Attribute Name

Required?

Description

began-transaction-name

N

The name of the method environment field that contains a Boolean specifying whether or not a transaction was begun in the current transaction demarcation. Defaults to "beganTransaction".


Conditional (If) Operations

if

The if operation offers a flexible way of specifying combinations of conditions, alternate conditions, and operations to run on true evaluation of the conditions or to run otherwise.

The other if operations are meant for a specific, simple condition when used outside of the condition sub-element of this operation. The attributes of the other if operations are the same when used inside this operation. In this case they are empty tags and do not have any sub-elements because the operations to run are under the then or else tags.

Sub-Element Name

How Many

Description

condition

1

A simple element with no attributes that contains the condition that will be evaluated to determine which sub-operations to execute. To combine the other if operations documented below the and, or, xor, and notelements can be used. The and, or, and xor elements can contain as many general if operations and modifier/combination elements (ie and, or, xor, and not).

then

1

The then element is used to contain operations that will run if the condition evaluate to true. A then tag must be included, but can be empty.

else-if

0 to many

The else-if element can be used to specify alternate conditional execution blocks. Each else-if element must contain two sub-elements: condition and then. These operations are used the same as the condition and then elements describes above. If the condition of the parent if element is evaluated to false, each condition of the else-if sub-elements will be evaluated, and the operations under the then element corresponding first condition that evaluates to true will be run.

else

0 or 1

The else element can be used to contain operations that will run if the condition evaluates to false, and if no else-ifsub-conditions evaluate to true. It can contain any simple-method operation. The else tag must be placed as the last tag under the if tag.

if-validate-method

The operations contained by the if-validate-method tag will only be executed if the validate method returns true. This tag can contain any of the simple-method operations, including the conditional/if operations.

Attribute Name

Required?

Description

map-name

N

The name of the method environment field that contains the map that the field to be validated will come from. If not specified the field-name will be treated as a method environment field name (an env-name).

field-name

Y

The name of the map field that will be validated.

method

Y

The name of the method that will be called to validate the field. It must be a static method that takes a single String parameter and return a boolean.

class

N

The name of the class that contains the validation method. If not specified defaults to "org.ofbiz.base.util.UtilValidate".

Sub-Element Name

How Many

Description

Any Operation

0 to many

Any simple-method operation can be nested under an if-* tag.

else

0 or 1

The else tag can be used to contain operations that will run if the condition fails, or in other words if the operations under the if tag do not run. It can contain any simple-method operation. The else tag must be placed as the last tag under the if-* tag.

if-compare

The operations contained by the if-compare tag will only be executed if the comparison returns true. This tag can contain any of the simple-method operations, including the conditional/if operations.

Attribute Name

Required?

Description

map-name

N

The name of the method environment field that contains the map that the field to be validated will come from. If not specified the field-name will be treated as a method environment field name (an env-name).

field-name

Y

The name of the map field that will be compared.

operator

Y

Specified the comparison operator must be one of the following: less, greater, less-equals, greater-equals, equals, not-equals, or contains.

value

Y

The value that the field will compared to. Must be a String, but can be converted to other types.

type

N

The data type to use for the comparison. Must be one of the following: String, Double, Float, Long, Integer, Date, Time, or Timestamp. If no type is specified the default will be String.

format

N

A format specifier to use when converting String objects to other data types, mainly Date, Time and Timestamp.

Sub-Element Name

How Many

Description

Any Operation

0 to many

Any simple-method operation can be nested under an if-* tag.

else

0 or 1

The else tag can be used to contain operations that will run if the condition fails, or in other words if the operations under the if tag do not run. It can contain any simple-method operation. The else tag must be placed as the last tag under the if-* tag.

if-compare-field

The operations contained by the if-compare-field tag will only be executed if the comparison returns true. This tag can contain any of the simple-method operations, including the conditional/if operations.

Attribute Name

Required?

Description

map-name

N

The name of the method environment field that contains the map that the field to be validated will come from. If not specified the field-name will be treated as a method environment field name (an env-name).

field-name

Y

The name of the map field that will be compared.

operator

Y

Specified the comparison operator must be one of the following: less, greater, less-equals, greater-equals, equals, not-equals, or contains.

to-map-name

N

The name of the method environment field that contains the map that the field to be compared will come from. If left empty will default to the method environment. It does not default to the map-name because that would make it impossible to compare a map field to an environment field.

to-field-name

N

The name of the to-map field that the main field will be compared to. If left empty will default to the field-name.

type

N

The data type to use for the comparison. Must be one of the following: String, Double, Float, Long, Integer, Date, Time, or Timestamp. If no type is specified the default will be String.

format

N

A format specifier to use when converting String objects to other data types, mainly Date, Time and Timestamp.

Sub-Element Name

How Many

Description

Any Operation

0 to many

Any simple-method operation can be nested under an if-* tag.

else

0 or 1

The else tag can be used to contain operations that will run if the condition fails, or in other words if the operations under the if tag do not run. It can contain any simple-method operation. The else tag must be placed as the last tag under the if-* tag.

if-regexp

The operations contained by the if-regexp tag will only be executed if the value complies with the regular expression. This tag can contain any of the simple-method operations, including the conditional/if operations.

Attribute Name

Required?

Description

map-name

N

The name of the method environment field that contains the map that the field to be validated will come from. If not specified the field-name will be treated as a method environment field name (an env-name).

field-name

Y

The name of the map field that will be compared.

expr

Y

A regular expression that the map value must comply with.

Sub-Element Name

How Many

Description

Any Operation

0 to many

Any simple-method operation can be nested under an if-* tag.

else

0 or 1

The else tag can be used to contain operations that will run if the condition fails, or in other words if the operations under the if tag do not run. It can contain any simple-method operation. The else tag must be placed as the last tag under the if-* tag.

if-empty

The operations contained by the if-empty tag will only be executed if the map field is empty. This tag can contain any of the simple-method operations, including the conditional/if operations.

Attribute Name

Required?

Description

map-name

N

The name of the method environment field that contains the map that the field to be validated will come from. If not specified the field-name will be treated as a method environment field name (an env-name).

field-name

Y

The name of the map field that will be compared.

Sub-Element Name

How Many

Description

Any Operation

0 to many

Any simple-method operation can be nested under an if-* tag.

else

0 or 1

The else tag can be used to contain operations that will run if the condition fails, or in other words if the operations under the if tag do not run. It can contain any simple-method operation. The else tag must be placed as the last tag under the if-* tag.

if-not-empty

The operations contained by the if-not-empty tag will only be executed if the map field is not empty. This tag can contain any of the simple-method operations, including the conditional/if operations.

Attribute Name

Required?

Description

map-name

N

The name of the method environment field that contains the map that the field to be validated will come from. If not specified the field-name will be treated as a method environment field name (an env-name).

field-name

Y

The name of the map field that will be compared.

Sub-Element Name

How Many

Description

Any Operation

0 to many

Any simple-method operation can be nested under an if-* tag.

else

0 or 1

The else tag can be used to contain operations that will run if the condition fails, or in other words if the operations under the if tag do not run. It can contain any simple-method operation. The else tag must be placed as the last tag under the if-* tag.

if-has-permission

The operations contained by the if-has-permission tag will only be executed if the user has the specified permission, and optionally the action. This tag can contain any of the simple-method operations, including the conditional/if operations.

Attribute Name

Required?

Description

permission

Y

The name of the permission in the database. The user must belong to a security group that has this permission.

action

N

If an action is specified the user can have one of two permissions: the permission + "_ADMIN" or permission + action. Examples of actions include "_CREATE", "_VIEW", etc.

Sub-Element Name

How Many

Description

Any Operation

0 to many

Any simple-method operation can be nested under an if-* tag.

else

0 or 1

The else tag can be used to contain operations that will run if the condition fails, or in other words if the operations under the if tag do not run. It can contain any simple-method operation. The else tag must be placed as the last tag under the if-* tag.

check-permission

The check-permission tag checks to see if the current user has the specified permission. The the user does not have the specified permission or there is no user associated with the context then the failure message from fail-message or file-property will be added to the specified error list.

Attribute Name

Required?

Description

permission

Y

The name of the permission in the database. The user must belong to a security group that has this permission.

action

N

If an action is specified the user can have one of two permissions: the permission + "_ADMIN" or permission + action. Examples of actions include "_CREATE", "_VIEW", etc.

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 does not exist. Defaults to "error_list".

Sub-Element Name

How Many

Description

alt-permission

0 to many

Allows you to specify alternate permissions, any of which will satisfy this check permission. If the current userLogin does not have any of these permissions the error will be added to the list. Has two attributes: permission and action that behave just as the corresponding attributes described above for the check-permission element.

fail-message

one

An inline failure message.

fail-property

one

A failure message from a properties file.

check-id

The check-id tag checks to see if the ID value in the given field is a valid ID string. Valid IDs can be any sequence of characters or digits but must not containt the following characters: space [ ], doublequote ["], single quote ['], ampersand [&], question mark [?], less-than sign [<], greater-than sign [>].

Attribute Name

Required?

Description

field-name

Y

The name of the field that contains the ID value to check.

map-name

N

The name of the Map that contains the field. If not specified the environment will be used to find the field.

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 does not exist. Defaults to "error_list".

Sub-Element Name

How Many

Description

fail-message

one

An inline failure message.

fail-property

one

A failure message from a properties file.


Other Operations

property-to-field

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

Attribute Name

Required?

Description

resource

Y

The resource location of the properties file.

property

Y

The property whose value will be put in the field.

default

N

The default value to use if the specified property is empty.

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.

log

The log tag logs a message used the OFBiz Debug class, which uses Log4J to log to the console, a file, or some other location. The message is a concatenation of the message attribute and then all of the field and string sub-element values in the order they are specified.

Attribute Name

Required?

Description

level

Y

The logging/debug level to use. Must be one of the following: verbose | timing | info | important | warning | error | fatal | always. These are the standard OFBiz logging levels.

message

N

A shortcut for simple messages. If used along with field and/or string sub-elements the inline string in the message will come first.

Sub-Element Name

How Many

Description

field

0 to many

Inserts the value of the field into the message where specified.

string

0 to many

Inserts the value of the inline string into the message where specified.

calculate

The calculate tag performs the specified calculation and puts the result in an object in the field of the specified map (see the calculate element attribute descriptions above). The type of the object can be specified with thetype attribute, but defaults to Double.

The calculate tag can contain calcop andnumber tags, and thecalcop tag can also contain these two tags to enable nested calculations.

Each calcop tag has three attributes: operator, map-name and field-name. Only the operator is required. The operator specifies the operation to perform on the given field and nested calcops and numbers. It must be one of the following: get | add | subtract | multiply | divide | negative.

Regardless of the operator the action is very similar. It translates to a formula like the following: (V1 operator V2 operator V3). In other words a final result is calculated by applying the operator to the values in the order they are specified. If a field-name (and optionally map-name) is specifies on the calcop tag that field will be used as the first value, otherwise the first nested calcop or number will be the first value.

The get operator is just an alias for add. It adds all of the values under it. Likewise the negative operator is almost an alias for subtract, with the exception that the first value is negated instead of left positive. For convenience the calculate tag itself acts like an add, in other words the calcops and numbers under it are all added together.

Attribute Name

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.

type

N

The object type to put into this field. Can be: Double | Float | Long | Integer. The default is Double.

Sub-Element Name

How Many

Description

calcop

0 to many

This tag is used to apply an operator in the calculation. It can have calcop and number tags nested under it, making it also act like a parenthesis. It has three attributes: operator, map-name, and field-name. These are described below.

number

0 to many

This is used to put a numeric constant (a number) into the calculation. It has one attribute: value. This must be a properly formatted number or an error will result.

Here is an example of an XML snippet that performs the calculationa=b+(((c+x+2)-d)/e), or in Reverse Polish Notation (a little bit closer to the resulting XML, and the notation used in the Rule Engine)a=(b,/(((c,x,2),-d),e)). Here is the XML: <calculate field-name="a">
<calcop operator="get" field-name="b"/>
<calcop operator="divide">
<calcop operator="multiply">
<calcop operator="add" field-name="c">
<calcop operator="get" field-name="x"/>
<number value="2"/>
</calcop>
<calcop operator="negative" field-name="d"/>
</calcop>
<calcop operator="get" field-name="e"/>
</calcop>
</calculate>


Simple Methods Example

<simple-methods xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="[<span style="color: #ff0000"><strong>to be modified</strong></span> [www.ofbiz.org/dtds/simple-methods.xsd]]"><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="newEntity.lastModifiedDate"/>
<now-timestamp-to-env env-name="newEntity.createdDate"/>
<set from-field="userLogin.userLoginId" field="newEntity.lastModifiedByUserLogin"/>
<set from-field="userLogin.userLoginId" field="newEntity.createdByUserLogin"/>
<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>

  • No labels