You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ofbiz.apache.org by jl...@apache.org on 2007/01/26 23:52:37 UTC
svn commit: r500393 - /ofbiz/trunk/framework/minilang/dtd/simple-methods.xsd
Author: jleroux
Date: Fri Jan 26 14:52:36 2007
New Revision: 500393
URL: http://svn.apache.org/viewvc?view=rev&rev=500393
Log:
Some new simple-method (mini-lang) annotations/documentations. (https://issues.apache.org/jira/browse/OFBIZ-571)
Modified:
ofbiz/trunk/framework/minilang/dtd/simple-methods.xsd
Modified: ofbiz/trunk/framework/minilang/dtd/simple-methods.xsd
URL: http://svn.apache.org/viewvc/ofbiz/trunk/framework/minilang/dtd/simple-methods.xsd?view=diff&rev=500393&r1=500392&r2=500393
==============================================================================
--- ofbiz/trunk/framework/minilang/dtd/simple-methods.xsd (original)
+++ ofbiz/trunk/framework/minilang/dtd/simple-methods.xsd Fri Jan 26 14:52:36 2007
@@ -99,16 +99,45 @@
<!-- ELEMENTS start here -->
<xs:element name="field">
+ <xs:annotation>
+ <xs:documentation>
+ Typical field-name/map-name pair. With the "." Syntax, the map-name is typically no longer necessary because
+ you can do map-name.field-name in the field-name attribute, but those are still there for legacy purposes.
+ </xs:documentation>
+ </xs:annotation>
<xs:complexType>
<xs:attributeGroup ref="attlist.field"/>
</xs:complexType>
</xs:element>
<xs:attributeGroup name="attlist.field">
- <xs:attribute type="xs:string" name="field-name" use="required"/>
- <xs:attribute type="xs:string" name="map-name"/>
- <xs:attribute type="xs:string" name="type"/>
+ <xs:attribute type="xs:string" name="field-name" use="required">
+ <xs:annotation>
+ <xs:documentation>
+ Name of the field to put value in.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:attribute>
+ <xs:attribute type="xs:string" name="map-name">
+ <xs:annotation>
+ <xs:documentation>
+ Name of the related map.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:attribute>
+ <xs:attribute type="xs:string" name="type">
+ <xs:annotation>
+ <xs:documentation>
+ Type of the value put in the field.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:attribute>
</xs:attributeGroup>
<xs:element name="string">
+ <xs:annotation>
+ <xs:documentation>
+ String of type java.lang.String
+ </xs:documentation>
+ </xs:annotation>
<xs:complexType mixed="true">
<xs:attributeGroup ref="attlist.string"/>
</xs:complexType>
@@ -117,9 +146,20 @@
<xs:attribute type="xs:string" name="value"/>
</xs:attributeGroup>
<xs:element name="simple-methods">
+ <xs:annotation>
+ <xs:documentation>
+ Opening tag of simple-method files.
+ </xs:documentation>
+ </xs:annotation>
<xs:complexType>
<xs:sequence>
- <xs:element maxOccurs="unbounded" ref="simple-method"/>
+ <xs:element maxOccurs="unbounded" ref="simple-method">
+ <xs:annotation>
+ <xs:documentation>
+ Opening tag of a simple-method definition.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
@@ -397,7 +437,8 @@
<xs:element name="set-service-fields" substitutionGroup="CallOperations">
<xs:annotation>
<xs:documentation>
-
+ Take all the incoming files for this service, or all the incoming service attributes,
+ and look for fields with the same name in the incoming map and copy those onto the outgoing map.
</xs:documentation>
</xs:annotation>
<xs:complexType>
@@ -408,21 +449,21 @@
<xs:attribute type="xs:string" name="service-name" use="required">
<xs:annotation>
<xs:documentation>
-
+ Name of the service from which take all the incoming files, or all incoming attributes.
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute type="xs:string" name="map-name" use="required">
<xs:annotation>
<xs:documentation>
-
+ Incoming map to copy fields from.
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute type="xs:string" name="to-map-name" use="required">
<xs:annotation>
<xs:documentation>
-
+ Map to copy to fields to.
</xs:documentation>
</xs:annotation>
</xs:attribute>
@@ -431,7 +472,9 @@
<xs:annotation>
<xs:documentation>
The call-service tag invokes a service through the Service Engine.
- If the specified error code is returned from the service, the event is aborted and the transaction in the current thread is rolled back. Otherwise, the remaining operations are invoked.
+ If the specified error code is returned from the service,
+ the event is aborted and the transaction in the current thread is rolled back.
+ Otherwise, the remaining operations are invoked.
The result-to-request and result-to-session elements will be IGNORED when
called in a service context. So, they are ONLY used when called in an event context.
@@ -458,14 +501,33 @@
</xs:complexType>
</xs:element>
<xs:attributeGroup name="attlist.call-service">
- <xs:attribute type="xs:string" name="service-name" use="required"/>
- <xs:attribute type="xs:string" name="in-map-name"/>
+ <xs:attribute type="xs:string" name="service-name" use="required">
+ <xs:annotation>
+ <xs:documentation>
+ Name of the service to call.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:attribute>
+ <xs:attribute type="xs:string" name="in-map-name">
+ <xs:annotation>
+ <xs:documentation>
+ Optional name of a map in the method environment to use as the input map.
+ If you're not going to pass any parameters to the service than you can just
+ leave off the in-map name, although typically in a service tag you will see
+ a service-name and the in-mapname passed in.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:attribute>
<xs:attribute name="include-user-login" default="true">
+ <xs:documentation>
+ Include-user-login by default will include the user login,
+ so if there is a user login for the current simple-method
+ it will pass that in to the service. If you don't want it to
+ pass that in you can just set this to false.
+ Defaults to "true".
+ </xs:documentation>
<xs:simpleType>
<xs:annotation>
- <xs:documentation>
- Defaults to "true".
- </xs:documentation>
</xs:annotation>
<xs:restriction base="xs:token">
<xs:enumeration value="true"/>
@@ -474,12 +536,17 @@
</xs:simpleType>
</xs:attribute>
<xs:attribute name="break-on-error" default="true">
+ <xs:annotation>
+ <xs:documentation>
+ If there's an error in the service by default
+ it will stop the current simple-method and return an
+ error message that came from the service it called. If
+ you don't want it to when there's an error you can just
+ set that to false.
+ Defaults to "true".
+ </xs:documentation>
+ </xs:annotation>
<xs:simpleType>
- <xs:annotation>
- <xs:documentation>
- Defaults to "true".
- </xs:documentation>
- </xs:annotation>
<xs:restriction base="xs:token">
<xs:enumeration value="true"/>
<xs:enumeration value="false"/>
@@ -502,41 +569,83 @@
</xs:attribute>
</xs:attributeGroup>
<xs:element name="error-prefix">
+ <xs:annotation>
+ <xs:documentation>
+ Specify a resource and a property to prepend to the error message.
+ </xs:documentation>
+ </xs:annotation>
<xs:complexType mixed="true">
<xs:attributeGroup ref="attlist.propertyInfoOptional"/>
</xs:complexType>
</xs:element>
<xs:element name="error-suffix">
+ <xs:annotation>
+ <xs:documentation>
+ Specify a resource and a property to append to the error message.
+ </xs:documentation>
+ </xs:annotation>
<xs:complexType mixed="true">
<xs:attributeGroup ref="attlist.propertyInfoOptional"/>
</xs:complexType>
</xs:element>
<xs:element name="success-prefix">
+ <xs:annotation>
+ <xs:documentation>
+ Specify a resource and a property to prepend to the success message.
+ </xs:documentation>
+ </xs:annotation>
<xs:complexType mixed="true">
<xs:attributeGroup ref="attlist.propertyInfoOptional"/>
</xs:complexType>
</xs:element>
<xs:element name="success-suffix">
+ <xs:annotation>
+ <xs:documentation>
+ Specify a resource and a property to append to the success message.
+ </xs:documentation>
+ </xs:annotation>
<xs:complexType mixed="true">
<xs:attributeGroup ref="attlist.propertyInfoOptional"/>
</xs:complexType>
</xs:element>
<xs:element name="message-prefix">
+ <xs:annotation>
+ <xs:documentation>
+ Specify a resource and a property to prepend to any kind of message.
+ </xs:documentation>
+ </xs:annotation>
<xs:complexType mixed="true">
<xs:attributeGroup ref="attlist.propertyInfoOptional"/>
</xs:complexType>
</xs:element>
<xs:element name="message-suffix">
+ <xs:annotation>
+ <xs:documentation>
+ Specify a resource and a property to append to any kind of message.
+ </xs:documentation>
+ </xs:annotation>
<xs:complexType mixed="true">
<xs:attributeGroup ref="attlist.propertyInfoOptional"/>
</xs:complexType>
</xs:element>
<xs:element name="default-message">
+ <xs:annotation>
+ <xs:documentation>
+ Message that you can specify for the case where the service does not return a message.
+ You can just specify a default-message to use as if the service had returned that default-message.
+ </xs:documentation>
+ </xs:annotation>
<xs:complexType mixed="true">
<xs:attributeGroup ref="attlist.propertyInfoOptional"/>
</xs:complexType>
</xs:element>
<xs:element name="results-to-map">
+ <xs:annotation>
+ <xs:documentation>
+ results-to-map will take all of the results of the service,
+ the outgoing maps from the service and put them in a map of the given map-name.
+ </xs:documentation>
+ </xs:annotation>
<xs:complexType>
<xs:attributeGroup ref="attlist.results-to-map"/>
</xs:complexType>
@@ -545,12 +654,21 @@
<xs:attribute type="xs:string" name="map-name" use="required">
<xs:annotation>
<xs:documentation>
-
+ Name of a map where results will be put in.
</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:attributeGroup>
<xs:element name="result-to-field">
+ <xs:annotation>
+ <xs:documentation>
+ Specify the name of the field in the result and then the name of the field in the context you want to put it in,
+ and optionally the name in the map.
+
+ There's a field-map there. If you don't specify a field-name then the result-name will be used for the field-name,
+ that's the name of the variable that will be created in the current context for the value of that result.
+ </xs:documentation>
+ </xs:annotation>
<xs:complexType>
<xs:attributeGroup ref="attlist.result-to-field"/>
</xs:complexType>
@@ -559,21 +677,22 @@
<xs:attribute type="xs:string" name="result-name" use="required">
<xs:annotation>
<xs:documentation>
-
+ Name of the result. May be used for the field-name. If you don't specify a field-name,
+ that's the name of the variable that will be created in the current context for the value of that result.
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute type="xs:string" name="map-name">
<xs:annotation>
<xs:documentation>
-
+ Optionnal map name.
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute type="xs:string" name="field-name">
<xs:annotation>
<xs:documentation>
-
+ Optionnal field name.
</xs:documentation>
</xs:annotation>
</xs:attribute>
@@ -581,7 +700,10 @@
<xs:element name="result-to-request">
<xs:annotation>
<xs:documentation>
-
+ result-to-request is event specific.
+ It takes the result with the given name and puts it in a request attribute with the given name here.
+ Again the request-name is optional.
+ If you leave it off then it will put it in an attribute with the name of the result-name.
</xs:documentation>
</xs:annotation>
<xs:complexType>
@@ -592,14 +714,15 @@
<xs:attribute type="xs:string" name="result-name" use="required">
<xs:annotation>
<xs:documentation>
-
+ Name of the result. May be used for the request attribute name. If you don't specify a request-name ,
+ that's the name of the request attribute that will be created for the value of that result.
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute type="xs:string" name="request-name">
<xs:annotation>
<xs:documentation>
-
+ Optionnal request name.
</xs:documentation>
</xs:annotation>
</xs:attribute>
@@ -607,7 +730,8 @@
<xs:element name="result-to-session">
<xs:annotation>
<xs:documentation>
-
+ Specify the name of the session attribute that you want it to put the value in.
+ If you don't specify one it will use the result-name.
</xs:documentation>
</xs:annotation>
<xs:complexType>
@@ -618,14 +742,15 @@
<xs:attribute type="xs:string" name="result-name" use="required">
<xs:annotation>
<xs:documentation>
-
+ Name of the result. May be used for the session attribute name. If you don't specify a session-name ,
+ that's the name of the session attribute that will be created for the value of that result.
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute type="xs:string" name="session-name">
<xs:annotation>
<xs:documentation>
-
+ Optionnal session name.
</xs:documentation>
</xs:annotation>
</xs:attribute>
@@ -633,9 +758,14 @@
<xs:element name="result-to-result">
<xs:annotation>
<xs:documentation>
+ result-to-result is service specific (when the service is being called as a service).
+
+ It will take the result of the service you're calling with the call service operation and it will put it in with the result of the current service.
+ So result-name is the name of the result in the service that was called using the call-service tag.
+
NOTE that these attributes are somewhat confusing: result-name is the name of the field in the result of this service call that the value comes FROM;
service-result-name is the name of the field in the result of this simple-method called as a service where the value goes TO;
- in other words FROM result-name and TO service-result-name.
+ in other words FROM result-name and TO service-result-name.
</xs:documentation>
</xs:annotation>
<xs:complexType>
@@ -646,14 +776,14 @@
<xs:attribute type="xs:string" name="result-name" use="required">
<xs:annotation>
<xs:documentation>
-
+ Name of the field in the result of this service call that the value comes FROM.
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute type="xs:string" name="service-result-name">
<xs:annotation>
<xs:documentation>
-
+ Name of the field in the result of this simple-method called as a service where the value goes TO.
</xs:documentation>
</xs:annotation>
</xs:attribute>
@@ -671,15 +801,27 @@
</xs:complexType>
</xs:element>
<xs:attributeGroup name="attlist.call-service-asynch">
- <xs:attribute type="xs:string" name="service-name" use="required"/>
- <xs:attribute type="xs:string" name="in-map-name"/>
+ <xs:attribute type="xs:string" name="service-name" use="required">
+ <xs:annotation>
+ <xs:documentation>
+ Name of the service called asynchronously.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:attribute>
+ <xs:attribute type="xs:string" name="in-map-name">
+ <xs:annotation>
+ <xs:documentation>
+ The name of a map in the method environment to use as the input map.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:attribute>
<xs:attribute name="include-user-login" default="true">
+ <xs:annotation>
+ <xs:documentation>
+ Defaults to "true".
+ </xs:documentation>
+ </xs:annotation>
<xs:simpleType>
- <xs:annotation>
- <xs:documentation>
- Defaults to "true".
- </xs:documentation>
- </xs:annotation>
<xs:restriction base="xs:token">
<xs:enumeration value="true"/>
<xs:enumeration value="false"/>
@@ -1279,7 +1421,7 @@
<xs:element name="list-to-list" substitutionGroup="EnvOperations">
<xs:annotation>
<xs:documentation>
-
+ Copy a list to another list.
</xs:documentation>
</xs:annotation>
<xs:complexType>
@@ -1290,14 +1432,14 @@
<xs:attribute type="xs:string" name="list-name" use="required">
<xs:annotation>
<xs:documentation>
-
+ Name of the list to copy from
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute type="xs:string" name="to-list-name" use="required">
<xs:annotation>
<xs:documentation>
-
+ Name of the list to copy to
</xs:documentation>
</xs:annotation>
</xs:attribute>
@@ -1305,12 +1447,14 @@
<xs:element name="order-map-list" substitutionGroup="EnvOperations">
<xs:annotation>
<xs:documentation>
-
+ Sort a list : ordered by fields names given in order-by attribute.
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:sequence>
- <xs:element maxOccurs="unbounded" ref="order-by"/>
+ <xs:element maxOccurs="unbounded" ref="order-by">
+ Names of fields to order list by.
+ </xs:element>
</xs:sequence>
<xs:attributeGroup ref="attlist.order-map-list"/>
</xs:complexType>
@@ -1319,16 +1463,28 @@
<xs:attribute type="xs:string" name="list-name" use="required">
<xs:annotation>
<xs:documentation>
-
+ Name of the list ordered by fields names given in order-by attribute.
</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:attributeGroup>
-
<xs:element name="set" substitutionGroup="EnvOperations">
<xs:annotation>
<xs:documentation>
-
+ Move a value from one field to another field.
+ You can also take a value, just a string constant or a string
+ that is made up of a mixture of constant and flexible
+ string expansion variables, the ${} things, that will be
+ put in the field.
+ You can also specify a default value in the case that the
+ value evaluates to an empty string or the from field is
+ null or empty. Then the default-value will be used.
+ Again you can use the flexible string expander here, the
+ ${} syntax and such. It can also do a type conversion,
+ so going from whatever type the source data is in,
+ which would be a string value or whatever the variable
+ type is for a from field, it can convert that to any of
+ these types before setting it in the target field.
</xs:documentation>
</xs:annotation>
<xs:complexType>
@@ -1339,35 +1495,35 @@
<xs:attribute type="xs:string" name="field" use="required">
<xs:annotation>
<xs:documentation>
-
+ Name of the field to copy value to.
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute type="xs:string" name="from-field">
<xs:annotation>
<xs:documentation>
-
+ Name of the field to copy value from.
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute type="xs:string" name="value">
<xs:annotation>
<xs:documentation>
-
+ Simple value to copy in field.
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute type="xs:string" name="default-value">
<xs:annotation>
<xs:documentation>
-
+ Default value to copy in field if value evaluates to an empty string or the from field is null or empty.
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="type">
<xs:annotation>
<xs:documentation>
-
+ Type to convert to.
</xs:documentation>
</xs:annotation>
<xs:simpleType>
@@ -1390,7 +1546,8 @@
<xs:attribute name="set-if-null" default="false">
<xs:annotation>
<xs:documentation>
-
+ If the source variable is null it should set it on the new field, and the default for that is false.
+ If the source variable is null it will leave the target field as it was.
</xs:documentation>
</xs:annotation>
<xs:simpleType>
@@ -1403,7 +1560,11 @@
<xs:attribute name="set-if-empty" default="true">
<xs:annotation>
<xs:documentation>
-
+ If the source value, either from a value or from a field, is empty, and
+ empty-string an empty list or a null value. In this case
+ it's set to true. If you don't want to set, if you want it to
+ leave the target field alone when the source is empty,
+ then you need to set this to false.
</xs:documentation>
</xs:annotation>
<xs:simpleType>
@@ -1417,7 +1578,10 @@
<xs:element name="string-append" substitutionGroup="EnvOperations">
<xs:annotation>
<xs:documentation>
- NOTE: the prefix and suffix will only be used IFF the current string and the string to be appended are both not empty
+ NOTE: the prefix and suffix will only be used IFF the current string and the string to be appended are both not empty.
+
+ So if the field does not exist then it will create a new field with this string value.
+ If it does exist then it will append this string value to the end.
</xs:documentation>
</xs:annotation>
<xs:complexType>
@@ -1428,7 +1592,11 @@
<xs:attribute type="xs:string" name="field-name" use="required">
<xs:annotation>
<xs:documentation>
-
+ The field that you want string-append to operate on.
+ This is the target field where the value will be put, and this is the string to append to
+ that field. So if the field does not exist then it will create
+ a new field with this string value. If it does exist then it
+ will append this string value to the end.
</xs:documentation>
</xs:annotation>
</xs:attribute>
@@ -1442,28 +1610,39 @@
<xs:attribute type="xs:string" name="string" use="required">
<xs:annotation>
<xs:documentation>
-
+ The string to append to the field named in field-name.
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute type="xs:string" name="arg-list-name">
<xs:annotation>
<xs:documentation>
-
+ arg-list-name is used to insert values from a list into
+ the string using the object in the standard Java library
+ that does this sort of string expresison with a { } brackets
+ and a number, no dollar sign.
+ This pattern of the arg-list-name with the prefix and
+ suffix is something form the early days which is still
+ supported, but the best thing to do here is just use the
+ flexible string expander which is far more flexible and
+ powerful. So you can have the prefix variables to expand
+ and everything all mixed into one string.
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute type="xs:string" name="prefix">
<xs:annotation>
<xs:documentation>
-
+ Used in conjunction with arg-list-name.
+ String that will be prepended to the string,
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute type="xs:string" name="suffix">
<xs:annotation>
<xs:documentation>
-
+ Used in conjunction with arg-list-name.
+ String that will be appended to the string,
</xs:documentation>
</xs:annotation>
</xs:attribute>
@@ -1471,7 +1650,12 @@
<xs:element name="string-to-list" substitutionGroup="EnvOperations">
<xs:annotation>
<xs:documentation>
-
+ Take a string literally that can also have a flexible string expander and such in it,
+ and it will add it to a list.
+ Note that you can have an arg-listname for using the standard
+ Java style argument list where you have in the source
+ string numbers inside of { } brackets that represent the
+ number the index in the argument list to insert at that point.
</xs:documentation>
</xs:annotation>
<xs:complexType>
@@ -1482,20 +1666,30 @@
<xs:attribute type="xs:string" name="string" use="required">
<xs:annotation>
<xs:documentation>
-
+ String to add to the list named in list-name.
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute type="xs:string" name="list-name" use="required">
<xs:annotation>
<xs:documentation>
-
+ List to add string to.
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute type="xs:string" name="arg-list-name">
<xs:annotation>
<xs:documentation>
+ arg-list-name is used to insert values from a list into
+ the string using the object in the standard Java library
+ that does this sort of string expresison with a { } brackets
+ and a number, no dollar sign.
+ This pattern of the arg-list-name with the prefix and
+ suffix is something form the early days which is still
+ supported, but the best thing to do here is just use the
+ flexible string expander which is far more flexible and
+ powerful. So you can have the prefix variables to expand
+ and everything all mixed into one string.
</xs:documentation>
</xs:annotation>