(r23) XeoPrimerObjectBehavior < WebXEO

WebXEO Web>XeoPrimer>XeoPrimerObjectBehavior (revision 23) (raw view)~~EditAttach~~
-- Main.PedroRio - 21 Dec 2010
---+ XEO Object Model Behavior- XEO Library

Custom Behavior in XEO Models can be achieved through various way (each with a specific purpose):
   * Model Events
   * Model Methods
   * Attribute Events
   * Attribute Properties

To define custom behavior there are two methods: BOL and the Java API. BOL is an acronym for <strong>B</strong>usiness <strong>O</strong>bject <strong>L</strong>anguage which is essentially a small expression language specific to the XEO platform to help declare behavior. Everything that can be done using BOL can be done using Java (BOL expressions are ultimately converted to Java like any XEO Model is converted to a java class).

In this chapter you'll create the custom behavior required for the XEO Models in the Library application and you'll learn the basics of XEO's Java API (and BOL).
---+++ XEO Java API (Basic Introduction) <a name="apiIntro"></a>

Each XEO Model is ultimatelly converted to a Java class to support operations (database tables are also created to persist data) and abstract from the relational data model. The classes created from XEO Models extend from a java class included in the framework (the _boObject_ class), which has a set of base methods to deal with attributes and other Model properties.

A user can login to a XEO Application via a login form or using the Java API to create a session within the XEO application. Having access to a _boSession_ instance, the Java API can be used to create new instances of XEO Models, load existing instances, change attribute values in existing instances as well as persist any changes made to those instances. One can also query XEO Model instances and iterate through the results. You can also check a XEO Model definition to perform operations based on that information.

In order to load an instance object, to create a new instance or to make a query XEO needs a "context". A context is an instance of the _EboContext_ class which can be created anytime (given there's access to a _boSession_) and the operations to load an object, create an object and query objects all require a parameter which is the context. The EboContext keeps in memory the loaded objects (and changes to their attribute values), acts as cache and has a connection to the database (meaning that creating many _EboContext_ instances can consume all available connections to the database). It's possible to create two different contexts and load the same instance into both of them, in this scenario changes made to each instance are not visible from the other context and if both objects are changed and then saved, the last save will crush the first one. The hierarchy of these classes is depicted in figure OB.1.

<img width="960" alt="boSession and EboContext hierarchy" src="http://wiki.itds.pt/pub/WebITDS/XeoPrimerObjectBehavior/JavaAPIboSession.png" title="boSession and EboContext hierarchy" height="720" />

__Figure OB.1 - boSession and EboContext hierarchy (with two instances with BOUI = 111, to depict the possibility to have different values)__

In most situations, there's no need to explicitly create instances of _EboContext_, because an _EboContext_ is always created in each request ( __FIXME: Vericar se isto é correcto__) and that context can be used inside your custom code. Each _boObject_ instance has access to an _EboContext_ instance (the context in which it's loaded) so even if a method receives as parameter a _boObject_, you still have access to the _EboContext_.

The following tables represent the most important classes in the XEO API and list some of the methods that are used to create behavior for XEO Models. More detailed information can be found on the [[XeoPrimerJavaAPI][XEO Java API Page]].

__boObject__ - Represents an instance of an XEO Model
| *Method Name* | *Description* | *Arguments* | *Return type* |
| update | Saves the object instance | - | void |
| getAttribute | Retrieves the handler for an attribute (non-collection) | (String) attributeName | AttributeHandler |
| exists | Checks whether the instance is saved in the database | - | boolean |
| getBridge | Retrieves the handler for a collection attribute | (String) collectionName | BridgeHandler |

__AttributeHandler__ - Represents a handler to deal with an attribute (non-collection) of an Object Model
| *Method Name* | *Description* | *Arguments* | *Return Type* |
| getName | Returns the name of the attribute (as defined in the Object Model) | - | String |
| getValueString | Retrieves the value of the attribute as a String* | - | String |
| getValueLong | Retrieves the value of the attribute as a Long* | - | Long |
| getValueDate | Retrieves the value of the attribute as a Data* | - | java.util.Date |
| getValueiFile | Retrieves the value of the attribute as a binary data Wrapper (iFile)* | - | netgest.io.iFile |
| getValueBoolean | Retrieves the value of the attribute as a Boolean* | - | Boolean |
| setValueString | Sets the value of the attribute with a String* | (String) newVal | void |
| setValueLong | Sets the value of the attribute with a Long* | (Long) newVal | void |
| setValueDate | Sets the value of the attribute with a Date* | (Date) newVal | void |
| setValueiFile | Sets the value of the attribute with a IFile* | (iFile) newVal | void |
| setValueBoolean | Sets the value of the attribute with a Boolean* | (Boolean) newVal | void |

_* - If an attribute is of a given type (String, Number) and you try to retrieve/set the value of the attribute of a different type it will throw an exception (unless the value can be converted to that type - i.e. you can get the String value of a Numeric attribute, but you cannot get the Date value of a Boolean attribute)._

__bridgeHandler__ - Represents a handler to deal with a collection attribute of an Object Model (similar to an java.util.Iterator)
| *Method Name* | *Description* | *Arguments* | *Return Type* |
| getName | Returns the name of the collection attribute | - | String |
| beforeFirst | Resets the handler to the first position of the collection | - | Boolean |
| next | Advances the handler to next position of the collection | - | Boolean |
| getObject | Retrieves the object in the current position of the handler | - | boObject |
| add | Add a new object to the end of the collection | (Long) BOUI | boolean |
| remove | Removes the boObject in the current position of the handler | - | boolean |

__boManagerBean__ - Manages the load/create operations for boObjects
| *Method Name* | *Description* | *Arguments* | *Return Type* |
| loadObject | Loads a given instance object to a context | (EboContext) ctx, (Long) BOUI | boObject |
| createObject | Creates a new instance object of a given Object Model in a context | (EboContext) ctx, (String) ObjectModelName | boObject |

This set of classes will be almost enough (querying was purposely left out of the list) to define the behavior for the Object Models in the XEO Library application. Next, you'll create the first XEO Model Method, the _removeCategories_ method, for the LIB_Book Model.
---+++ Creating the first XEO Method - removeCategories (LIB_Book)

The LIB_Book XEO Model has a collection of categories (representing Book categories). As a convenience, if a Librarian wrongly categorizes the book it'll have a method that will clean all categories for that book (instead of forcing the librarian to individually remove each category). Open the LIB_Book Model and go to the "Methods" section and press the add (plus) button to add a new method. Type in "removeAllCategories" for the name of the method and "Remove all categories" for the Label, go to the "Body" section of the method, choose "JAVA" as the language and press the "edit" button (see figure OB.1 for details), which will open a "LIB_BookHandler" Class in Eclipse's Java Editor (see figure OB.1, again, for details).

<img width="800" alt="Studio Create Method" src="http://wiki.itds.pt/pub/WebITDS/XeoPrimerObjectBehavior/StudioCreateMethod.png" title="Studio Create Method" height="598" />

__Figure OB.1 - Creating a new XEO Model Method in XEO Studio__

Whenever Java code needs to be created to perform custom-logic, XEO Studio creates a Java class for each XEO Model and names the methods appropriatelly with the correct parameters. In the case of XEO Model Methods the method declaration is always the name of the method given in the Object Model definition with the boObject representing the current instance as parameter.

These auto-generated classes are placed in a different source-code folder (as depicted in figure OB.1a) within the xeo.code.java.XEOPackageName (in this case XEOPackageName = LIB$1.0 = LIB1_0). There's one java package for each XEO Package in your project (that uses custom java code, of course)

<img width="274" alt="StudioJavaHandlersSource.png" src="http://wiki.itds.pt/pub/WebITDS/XeoPrimerObjectBehavior/StudioJavaHandlersSource.png" title="StudioJavaHandlersSource.png" height="139" />

__Figure OB.1a - Different source code folder for XEO Studio's generated classes.__
---++++++ Remove All Book Categories - The Java Code

Each (and every) XEO Model Method will be generated by XEO Studio using the method's name property and passing a boObject instance (representing the current instance at runtime) as a parameter. The flow of java code for "remove all book categories" ill be like the following:
   * Check if the instance is saved (if it exists, it does not make sense to remove book categories from a book which does not yet exist in the library).
   * Load the collection attribute and position the handler in the first position of the collection.
   * Iterate through all elements and remove them.
   * Save the instance.

The code to remove all book categories is depicted in figure OB.1b.
<verbatim>public void removeAllCategories(boObject obj) throws boRuntimeException {
        //Check if the object is saved in the database, new objects cannot remove categories
        if(obj.exists()) {
            //Get the collection handler (bridgeHandler) for the categories attribute
            bridgeHandler categories = obj.getBridge("categories"); 
            //Iterate through them all and remove
            while (categories.next())
            { categories.remove(); }
            //Save the object
            obj.update();
        }
    }</verbatim>

__Figure OM.1b - Remove all book categories method souce code.__

The _removeAllCategories_ methods could be optimized, because the <em>bridgeHandler </em>class has a convenience method, _truncate_, which will remove all elements in the bridge. The result is depicted in figure OM.1c.
<pre><verbatim>package xeo.code.java.lib1_0;

import netgest.bo.runtime.*;

public class LIB_BookHandler {

    public void removeAllCategories(boObject obj) throws boRuntimeException {
        //Check if the object is saved in the database, new objects cannot remove categories
        if(obj.exists()) {
            //Get the collection handler (bridgeHandler) for the categories attribute
            bridgeHandler categories = obj.getBridge("categories"); 
            //Truncate the collection, removing all elements
            categories.truncate();
            //Save the object
            obj.update();
        }
    }
}</verbatim>
</pre>

__Figure OM.1c - removeAllCategoires method source code optimized__

Next you'll add behavior to validate the e-mail attribute in the LIB_Librarian and LIB_User
---+++ LIB_Librarian & LIB_User Behavior - Validate the e-mail attribute

The LIB_Librarian XEO Model has an _email_ attribute, representing the Librarian's e-mail. E-mail addresses follow a specific pattern and can be validated before saving a Librarian instance. Open the LIB_Librarian Model, select the _email_ attribute, in the details panel scroll to the section with "Valid" as title and select JAVA from the dropdown menu and click "edit". XEO Studio will generate a handler class with the following method:
<verbatim>public boolean email_Valid(boObject obj,AttributeHandler attribute) throws boRuntimeException {
        return true;
 }</verbatim>

The objective of this document is not to teach Java Programming, as such the code for the email_Valid method, could be the following:
<verbatim>public boolean email_Valid(boObject obj,AttributeHandler attribute) throws boRuntimeException {
        
        //Keep the value to return
        boolean res = false;
        
        //Get the attribute value
        String email = attribute.getValueString();
        
        //Create a pattern to check for e-mails
        Pattern p = Pattern.compile(".+@.+\\.[a-z]+");
        Matcher m = p.matcher(email);
        
        //If the pattern matches, e-mail is ok
        if(m.matches() || email.length() == 0)
            res = true;
        else
            obj.addErrorMessage("Invalid e-mail " + email); //Else, add error 
        
        //Return the result
        return res;
        
    }</verbatim>

For the LIB_User Model add the same valid behavior to the email attribute (since it's the same validation, you can create a class with the code and invoke it from both places.
---+++ LIB_Librarian & LIB_User Behavior - Username formula

When creating a new Libriarian or a new User a username must be chosen for both of them. Assume the library has a default "rule" for creating usernames which is the concatenation of their name, a separator (a dot) and the last name. *A formula is a behavior that allows to have an attribute whose value can be calculated based on the values of other attributes (i.e. its dependencies)*. The formula is triggered whenever one of the depedencies (value of the attribute from which this depends) is changed.

Open the LIB_Librarian Object Model and locate the _username_ attribute, find the _Formula_ section and press "Edit" to let XEO Studio generate the Java class for the handler and then add two attributes as "depends" (see red bordered zone in figure OB.2), the _name_ and _lastname_ attributes (name is inherited from _iXEOUser_ interface; this means the formula behavior will be invoked whenever the value of name/lastname are changed.

<img width="800" alt="Formula Behavior" src="http://wiki.itds.pt/pub/WebITDS/XeoPrimerObjectBehavior/FormulaBehavior.png" title="Formula Behavior" height="259" />

__Figure OB.2 - Editing dependents in a Formula for the username attribute in LIB_Librarian__

Go to the Java handler class created by XEO Studio and fill in the following code:
<verbatim>public String username_Formula(boObject obj,AttributeHandler attribute) throws boRuntimeException {
        
        //Only use the rule for a new librarian
        if(!obj.exists()) {
            //Get the name value
            String firstName = obj.getAttribute("name").getValueString().toLowerCase().toString();
            //Get the last name value
            String lastName = obj.getAttribute("lastname").getValueString().toLowerCase().toString();
            
            //If both values are not null
            if(firstName.length() == 0 || lastName.length() == 0)
                return firstName + "." + "librarian";
            else
                return firstName + "." + lastName;
        } //In an existing object, return the existing value 
        else
            return obj.getAttribute("username").getValueString().toString();        
}</verbatim>

The code for the formula will attempt to concatenate the name and lastname, if both have a value, or the name and the string "librarian" (all strings are separated by a dot), in case the object instance does not exist. If the instance object already exists, it returns the current value of the username attribute.

The (almost) same code is valid for the formula of the username in the LIB_User Object Model (instead of concatenating with ".librarian" in one of the situations it concatenates with ".user".
<verbatim>public String username_Formula(boObject obj,AttributeHandler attribute) throws boRuntimeException {
        //Only use the rule for a new librarian
        if(!obj.exists()) {
            //Get the name value
            String firstName = obj.getAttribute("name").getValueString().toLowerCase().toString();
            //Get the last name value
            String lastName = obj.getAttribute("lastname").getValueString().toLowerCase().toString();
            
            //If both values are not null
            if(firstName.length() == 0 || lastName.length() == 0)
                return firstName + "." + "user";
            else
                return firstName + "." + lastName;
        } //In an existing object, return the existing value 
        else
            return obj.getAttribute("username").getValueString().toString();
    }</verbatim>

_Code for Formula of the username attribute (in the LIB_User Object Model)_

_

---+++ LIB_Message Behavior - Date Default Value and DisabledWhen

The Message XEO Model has a _date_ attribute which represents the date the message was sent. Although a system SYS_DTCREATE attribute exists in all instances, this is added so that you could see some behaviors such as the default value and the disabled condition. The _date_ attribute is a value that will not be user-editable (it would not make sense to change the date a certain message was sent), as such it's a value that needs to be displayed but not changed and XEO provides that ability by allowing a "disabled when" condition for each attribute.

Go the _date_ attribute in LIB_Message and scroll to the "Default Value" section, choosing Java from the drop down and press edit (which will trigger the generation of a Java class handler for LIB_Message. The code to return the current date is the following:
<verbatim>public String date_DefaultValue(boObject obj,AttributeHandler attribute) throws boRuntimeException {
        Calendar dueDate = Calendar.getInstance();
        return new Date(dueDate.getTimeInMillis()).toString();
    }</verbatim>

_Default value code for the data attribute_

One could use BOL, instead of JAVA to set this value, as the [[WebITDS.XeoPrimerBOL][Business Object Language]] has an expression, [[WebITDS.XeoPrimerBOL#dates][ _NOW_ ]], which returns the current date.

For the disabled condition, in the same attribute scroll to the "Disabled When" section and choose "BOL" from the drop down and type _true_ as the value (Java code could also be used with a "return true" statement inside the function, *this dual usage of BOL and Java is to highlight that it can be done and each language should be used whenever they make sense to you as a developer*.
---+++ LIB_Movement - Events, default value and collection attribute restrictions

The Movement entity represents a book loan from a Library User. A Movement instance can be in one of two states. The "Open" state (where some, or all, of the books are still in possession of the Library User and the "Closed" state when the User has returned all books of that movement. Books that are currently loaned to a user have their state as "Unavailable" which is something done in the act of creating the Movement. Also, movements cannot be changed (i.e. if a user wants to add another book to a movement he can't, he must create a new movement)
---++++++ Updating all Books in the creation of a movement (onBeforeSave)

To update all books in the creation of a movement you'll add an OnBeforeSave event to the LIB_Movement XEO Model, in which you'll change the state of the all of the books of the movement to "unavailable". To add an event, open the LIB_Movement Object Model and go the _Events_ section, press the _add_ button and choose "OnBeforeSave" from the drop down, then press "Edit" button to let XEO Studio generate the handler class for the LIB_Movement XEO Model, see figure OB.3 for an illustration.

<img width="800" alt="Add onBeforeSave Event to Movement" src="http://wiki.itds.pt/pub/WebITDS/XeoPrimerObjectBehavior/AddEventMovement.png" title="Add onBeforeSave Event to Movement" height="378" />

__Figure OB.3 - Adding the onBeforeSave event to the LIB_Movement Object Model__

The condition for the onBeforeEvent is to change all instances of LIB_Book in the _books_ collection attribute to a state of "Unavailable", but only if the movement itself is a new movement (it doesn't exist and its state attribute has value 0 [more on this in the following paragraph]). The java code to assure this condition is the following:
<verbatim>/**
     * 
     * Before a new Movement is saved, change the state of all books
     * 
     * @param obj The Movement instance
     * @param event The triggered event
     * @return True if the movement can be saved
     * 
     * @throws boRuntimeException If an error occurs while updating 
     * a book
     */
    public boolean onBeforeSave(boObject obj,boEvent event) throws boRuntimeException {

        //Only execute this action
        if (!obj.exists()
                && obj.getAttribute("state").getValueString().equals("0")) {
            //Retrieve the collection attribute and put the handler in
            //the first position
            bridgeHandler books = obj.getBridge("books");
            books.beforeFirst();
        
            //Iterate through all books and change state to 1 (see Lov values from LIB_Lov)
            while (books.next()) {
                boObject currentBook = books.getObject();
                currentBook.getAttribute("state").setValueString("1");
            }
        }
        
        //Return true so that the 
        return true;
    }</verbatim>

*Note*: There's no call to the update() method on each boObject representing a book. Whenever the owner of a collection attribute is saved, all elements in the collection are saved as well, and since this code is executed right before the save of the movement instance, when save actually occurs, all books will be updated.
---++++++ Default State for the movement

The _state_ attribute will have a default value of "Open", which means when a movement is created it's always because the user has loaned some books from the library. The "Open" state is the label corresponding (in the _movement_type_ lov) to the "0" value, so in order to have that as a default value, go to the _state_ attribute, find the "Default Value" section, choose "BOL" and type in "0" (without quotes).
---++++++ Locking all attributes of an existing movement - onAfterLoad

Whenever an existing LIB_Movement instance is opened you want to lock all attributes so that they cannot be changed. The only thing that can be done in a movement is return books (which will be done later in the documentation due to the dependency on book selection from the visual layer). Add the _onAfterLoad_ event to the LIB_Movement Object Model and choose Java as the language and press edit to let XEO Studio create another method within the existing Java class handler. The code for the event is the following:
<verbatim>/**
     * 
     * Disables all attributes of an existing movement
     * 
     * @param obj The instance movement
     * @param event The event 
     * 
     * @throws boRuntimeException If a problem occurs while disabling the attributes
     */
    public void onAfterLoad(boObject obj,boEvent event) throws boRuntimeException {
        
        //Only apply the condition if the object is saved
        if (obj.exists()) {
            
            //Get an enumeration of all attributes
            Enumeration atts = obj.getAllAttributes().elements();

            //Iterate through all of them and disable them
            while (atts.hasMoreElements()) {
                AttributeHandler currAtt = (AttributeHandler) atts.nextElement();
                currAtt.setDisabled();
            }
        }
    }</verbatim>

---++++++ Collection Attribute restrictions (Filtering)

When adding a new collection attribute to an Object Model one has to choose the type of XEO Model instances which are allowed in the collection. You can choose a single type of instance (from one Object Model) or a set of different types. Business Logic, however, can dictate that not all instances from a given type are applicable and XEO provides a feature to allow filtering of instances. <br />Please note that this feature only has an effect when using XEO's Web Component Layer, i.e. if you create a filter on a collection and use the API to add an instance that is of a valid Object Model for that collection but does not match the rules of the filter, nothing is going to prevent it to be added. Filters are applied when listing instances in a lookup viewer. Most of the times, this is all that's needed as all interaction with the application is done through the Web layer but XEO provides mechanisms to allow you verify (programatically) that an instance added to a collection matches your filter (more on that in the following paragraphs)

In the _books_ attribute of the LIB_Movement Object Model the only books that should be added are ones which are not currently loaned to a user (i.e. the state of the book is "Available", whose value is "0" as defined in _book_state_ lov). In order to create a filter you'll need to know a bit about XEOQL (also known as BOQL, *not BOL*).
---++++++ XEO QL Basic Introduction

XEO Query Language (or BOQL - Business Object Query Language) is a small SQL-based querying language in order to select a set of XEO Model instances. XEOQL allows to select a set of instances while being able to set conditions on that search (just like SQL), let's see an example:
<verbatim>select LIB_Book</verbatim>

The previous query selects all instances of the LIB_Book Object Model, let's see another example with some conditions.
<verbatim>select LIB_Book where title = 'Angels and Demons'</verbatim>

The previous query selects all LIB_Book instances which have a title equal to "Angels and Demons", see the next example for a demonstration of querying using relations between
<pre><verbatim>select LIB_Book.categories where LIB_Book.BOUI = 1111</verbatim>
</pre>

The previous query selects all Book Categories for the Book instance with BOUI equal to 1111

To know more about XEOQL read the [[WebITDS.XeoPrimerXeoQL][XEOQL chapter]]. For now let's continue with the filter.

Going back to the LIB_Movement filter (and using the knowledge from XEO QL), the filter you want to apply can be described as "all book instances whose attribute state is available", translating to XEOQL would be "<em> select LIB_Book where state = '0'</em> ", to add an Object filter, select the "books" attribute in XEO Studio, scroll to the "Object Filters" section and press "add". A new window will open, in the XEOQL filed type the expression " select LIB_Book where state = '0' " (without quotes), see figure OB.4 for details.

<img width="960" alt="Add Object Filter Movement" src="http://wiki.itds.pt/pub/WebITDS/XeoPrimerObjectBehavior/AddObjectFilterMovement.png" title="Add Object Filter Movement" height="720" />

__Figure OB.4 - Adding an Object Filter to the books attribute collection__
---++++++ Default Value for DueDate

The due date for a return of the books is seven days from the initial loan, as such you're going to add a default value for the _dueDate_ attribute in the form of Java code. Go to the "Default Value" section of the _dueDate_ attribute and select Java and press edit. In the Java editor, type the following code:
<verbatim>/**
     * 
     * Default value for dueDate attribute, which is seven days from the current
     * day
     * 
     * @param obj The instance movement
     * @param attribute The attribute handler for dueDate
     * 
     * @return A string with the date seven days from today
     * 
     * @throws boRuntimeException
     */
    public String dueDate_DefaultValue(boObject obj,AttributeHandler attribute) throws boRuntimeException {
        //Retrieve a calendar for current time
        Calendar dueDate = Calendar.getInstance();
        //Add seven days
        dueDate.add(Calendar.DATE, 7);
        //Return the date
        return new Date(dueDate.getTimeInMillis()).toString();
    }</verbatim>

This finishes our tour in the XEO Library Behavior. Next we'll go to the Web Components Layer (in the mean time we invite you to read more on the Java API, BOQL or BOL)

In the next chapter you'll [[XeoPrimerWebComponentsIntro][start creating the XEO Web Viewers for the Library Application]].

<strong><em>____</em></strong>
Attachments
Topic attachments
I	Attachment	Action	Size	Date	Who	Comment
png	AddEventMovement.png	manage	18.2 K	2010-12-28 - 09:47	PedroRio	Event for LIB_Movement
png	AddObjectFilterMovement.png	manage	98.1 K	2010-12-28 - 15:50	PedroRio
png	FormulaBehavior.png	manage	16.4 K	2010-12-27 - 17:22	PedroRio
png	JavaAPIboSession.png	manage	31.7 K	2010-12-23 - 11:38	PedroRio	boSession e EboContext
png	RemoveAllCategoriesMethod.png	manage	9.8 K	2010-12-27 - 09:18	PedroRio	Remove Book Categories method
png	RemoveAllCategoriesMethodOptimized.png	manage	6.0 K	2010-12-27 - 09:40	PedroRio	RemoveCategoriesOptimized
png	StudioCreateMethod.png	manage	35.2 K	2010-12-23 - 16:28	PedroRio
png	StudioJavaHandlersSource.png	manage	3.5 K	2010-12-23 - 16:37	PedroRio
Topic revision: r23 - 2011-03-31 - PedroRio
No permission to view TWiki.WebTopBar
No permission to view TWiki.WebBottomBar