(r5) XeoPrimerBOL < WebXEO

WebXEO Web>XeoPrimer>XeoPrimerBOL (revision 5) (raw view)~~EditAttach~~
-- Main.PedroRio - 21 Dec 2010
---+ Business Object Language (BOL)

The Business Object Language is a small expression language to help define conditions for the behavior in XEO Object Models. It allows to reference attribute values, compare them with other values as well as making small calculations. The following sections explain the various operators and statements that can be used in the language
---+++ Attributes

Object Model attributes can be referenced in BOL expressions by their name, for example if you want to build the follwing: "If the value of attribute X is bigger than 5, return true" the bol expression would be "if (x &gt; 5) return true". This syntax works for attributes that are not Collection nor Object.

When dealing with an Object attribute you can refer to the values of its attributes by using the separator '.' ; Imagine a situation where we have a XEO Model to represent a Person a Car and a Car Brand, where Person has 1:1 relation to Car which has a 1:1 relation to Brand, those relations are depicted in figure BOL.1. The following tables have the definition of the Object Models.

*Person* ( Person )
| *Attribute Name* | *Attribute Type* | *Label* | *Description* | *Length* | *Required* | *Object Type* |
| name | Text | Name | Person Name | 30 | - | N/A |
| avg_km_car_year | Number | Average Km's | Average KM's per year with a car | 30 | - | N/A |
| driver_license | Text | Driver License Number | The identifier of the driver license | 30 | - | N/A |
| ID | Text | Identifier | The identifier of the person | 30 | - | N/A |
| age | Number | Age | The age of the person | 3 | - | N/A |
| favorite_car | Text | Favorite Car | The favorite car of the person | 30 | - | N/A |
| car | Object | Car | The car of the person | 30 | - | Car |

*Car* ( Car )
| *Attribute Name* | *Attribute Type* | *Label* | *Description* | *Length* | *Required* | *Object Type* |
| model | Text | Model | The model of the car | 30 | - | N/A |
| age | Number | Age | The age of the car | 3 | - | N/A |
| kms | Number | Kilometers | The number of kilometers the car has done | 4 | - | N/A |
| brand | Object | Brand | The car brand | 4 | - | N/A |

*Brand* ( Brand )
| *Attribute Name* | *Attribute Type* | *Label* | *Description* | *Length* | *Required* | *Object Type* |
| name | Text | Name | Name of the category | 30 | true | N/A |

<img width="960" alt="BOL Model" src="http://wiki.itds.pt/pub/WebITDS/XeoPrimerBOL/BOL.png" title="BOL Model" height="296" />

__Figure BOL.1 - XEO Models for the BOL example.__

__Tentar verificar se é possível usar "parent.att" em BOL__
---+++ Boolean Values

Boolean values can in BOL expressions, the folowing expressions represent the "true" value:
   * true
   * yes
   * y
   * YES

In the same way, the following values represent the "false" value:
   * false
   * no
   * n
   * NO

---+++ Conditional Statements

In BOL you can use conditional expressions in the form of if/else statements. The syntax is like the following:
<verbatim>if ( CONDITION )
   BOL EXPRESSION
else
   BOL EXPRESSION</verbatim>

If you need more conditions you use if/else with brackets
<verbatim>if (CONDITION ){
  //BOL EXPRESSIONS
  //BOL EXPRESSIONS
} else {
  //BOL EXPRESSIONS
  //BOL EXPRESSIONS 
}
</verbatim>

_
---+++ Returning a value

Most BOL expressions are used in places where they must return a value (be it a boolean, string or numeric value). In order to do that BOL has the expression "return" which will return the result of evaluating the expression on its right side. Example:
<pre><verbatim>return true</verbatim>
</pre> <verbatim>return YES
if (att1 > 2)
  return "Foo"
else
  return "Bar"</verbatim>

---+++ Operators

BOL expressions can have multiple operands linked by operators, as with most programming languages. In BOL the following operators are allowed
   * &gt; (Bigger)
   * &gt;= (Bigger or Equal)
   * == (Equal)
   * &lt;= (Less or Equal)
   * &lt; (Less)
   * ! (Negation)
   * && ( And)
   * || (Or)
   * != (Different)

You can have expressions such as:
<pre><verbatim>if (att1 > 2 && att2 != 45 && att3 == 'F') return "42"</verbatim>
</pre>

_
---+++ Functions

BOL includes a set of predefined functions which can be used inside every BOL Expression.

<strong><em>DATE FUNCTIONS<a name="dates"></a></em></strong>

Functions that return a date <strong><em><br /></em></strong>

NOW - Returns the current date with time

TODAY - Returns the current date without time information

NOW_HOURS - Returns the current date with time information about the hour (discards minutes, seconds and mili-seconds)

NOW_MINUTES - Returns the current date with time information about the hour and minutes (discards seconds and mili-seconds)

---

__ROUND__

ROUND(Number) - Rounds to the nearest integer (0.4 -&gt; 0; 0.5 -&gt; 1)

---

__CONCAT (Concatenates two values)__

<em><strong><br /></strong></em>
   * CONCAT(String,String)
   * CONCAT (Number,Number) - Number can be long/int value
   * CONCAT (Object,Object) - Converts each Object to string and concatenates

---

__TO_DATE (Converts to a Date value)__

   * TO_DATE(Date, Format)
   * TO_DATE (Object, Format), Object is converted to a String and converted to date
   * TO_DATE (long, Format) - Convertes UNIX time miliseconds to a date

O <em>Format </em>must be compatible with the ones accepted by [[http://download.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html][SimpleDateFormatter]] (if the format is not correct it will simply return a null value)

The first argument can be one of the following functions (NOW, TODAY, NOW_MINUTES, NOW_HOURS, or any other valid date.

---

__SUM__

   * SUM ( Number , Number )
   * SUM (Object , Object) - Converts the Object to Numbers and sums the numbers

_Example:_
<verbatim>Sum(3 , 1 ) will return 4

Sum (att1, att2 )  - assuming both are attributes which contain a value that can converted  to a number will return the sum of the two
</verbatim>

---

__SUBTRACT__

   * SUBTRACT (Number, Number)
   * SUBTRACT (Object, Object) - Converts the Object to String

_Example:_
<verbatim>Substract (3 , 1 ) will return 2

Subtract (att1, att2 ) - assuming both are attributes which contain a value that can converted to a number will return the difference between the two
</verbatim>

---

__DIFF_IN_DAYS (Difference in days between two dates)__

Returns the number of days between two dates

   * <span style="white-space: pre;">DIFF_IN_DAYS</span> (Date, Date)
   * <span style="white-space: pre;">DIFF_IN_DAY</span> (Date, Long)
   * DIFF_IN_DAY (Long, Date)
   * DIFF_IN_DAY (Long, Long)

Example:
<verbatim>DIFF_IN_DAYS (NOW, TO_DATE('22/12/2012','dd/MM/yyyy')) which will return the number of days between today and December 22nd, 2012</verbatim> <pre><verbatim>DIFF_IN_DAYS (TO_DATE('20/12/2012','dd/MM/yyyy'), TO_DATE('22/12/2012','dd/MM/yyyy')) which will return 2 (two)</verbatim>
</pre>

---

__DIFF_IN_UTIL_DAYS (Difference in work days between two dates)__

   * DIFF_IN_UTIL_DAYS (Date, Date)
   * DIFF_IN_UTIL_DAYS (Date, Long) - The long value is a Unix timestamp
   * DIFF_IN_UTIL_DAYS (Long, Date) - The long value is a Unix timestamp
   * DIFF_IN_UTIL_DAYS (Long, Long) - The long value is a Unix timestamp

---

__IS_NULL (Checks if a given value is null)__

Works for all kinds of attributes except for Collection attributes. Returns true is the value of the attribute is null (i.e. newly created object will have all attributes null (except if they have a default value)).

Example:
<verbatim>if (IS_NULL (att1)) return true</verbatim>

_

<strong><em>
---
<br /></em></strong>

addErrorMessage - __Does not work.__

---+++ Examples

This section shows some examples of BOL expressions using the previous Model (Person, Car and Brand)

<img width="960" alt="BOL Complete Example" src="http://wiki.itds.pt/pub/WebITDS/XeoPrimerBOL/BOL_Complete.png" title="BOL Complete Example" height="720" />

__Figure BOL.2 - Examples of BOL Expressions__

_
Attachments
Topic attachments
I	Attachment	Action	Size	Date	Who	Comment
png	BOL.png	manage	8.1 K	2010-12-22 - 15:59	PedroRio
png	BOL_Complete.png	manage	33.0 K	2010-12-22 - 16:43	PedroRio	BOL Complete
Topic revision: r5 - 2010-12-28 - PedroRio
No permission to view TWiki.WebTopBar
No permission to view TWiki.WebBottomBar