(r8) XeoPrimerObjectBehavior < WebXEO

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

Custom Behavior in XEO Object Models can be achieved through various way :
   * Object Events
   * Object Methods
   * Attribute Events
   * Attribute Properties

To define custom behavior there are two methods: BOL and the Java API. BOL is an acronym for Business Object Language which is essentially a small expression language specific to the XEO platform to aid in creating custom behavior. Everything that can be done using BOL can be done using Java (BOL expressions are ultimately converted to Java as the whole Object Model is also converted to Java).

In this chapter we'll create the custom behavior required for the Object Models in the XEO Library and introduce briefly the XEO Java API (and BOL).
---+++ XEO Java API (Basic Introduction)

Each XEO Object 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 Object 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 the login form or using the Java API to create a session within the XEO application. With access to a _boSession_, the Java API can be used to create new instances of Object Models, load existing instances, change attribute values in an existing instance as well as save the changed values. One can also query object instances and iterate through the results as well as checking the Object Model definitions 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) and acts as cache and has a connection to the database (as such they should be managed with care). It's possible to create two different contexts and load the same object instance into both of them, in this scenario changes made each instance are not visible from another 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__

In most situations, there's no need to explictly 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 its loaded) so even if a method receives as parameter a boObject, you still have access to the EboContext.

Most Important APIs for defining custom behavior in the XEO Library (the list is a sub-set of the entire methods for the given classes only to illustrate the more commonly used methods in the XEO API), more detailed information on the [[XeoPrimerJavaAPI][XEO Java API Page]].

__boObject__ - Represents an instance of an Object 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._

__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 (Object querying was purposely left out of the list) to define the behavior for the Object Models in the XEO Library application. Next, we'll create the first Object Model Method, the removeCategories for the LIB_Book.
---+++ Creating the first XEO Method - removeCategories (LIB_Book)

The LIB_Book Object Model has a collection of categories (representing Book categories). As a convenience, if a Librarian wrongly categorizes the a book we'll have a method that will clean all categories for that book (instead of individually removing each category). Open the LIB_Book Object 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 Object Model Method in XEO Studio__

Whenever Java code needs to be created to perform custom-logic, XEO Studio creates a Java class for each Object Model and names the methods appropriatelly with the correct parameters. In the case of Object 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 our 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) Object 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. To code the remove all book categories from the instance book object, the flow of java code will 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.

<img width="744" alt="Remove All Categories Method" src="http://wiki.itds.pt/pub/WebITDS/XeoPrimerObjectBehavior/RemoveAllCategoriesMethod.png" title="Remove All Categories Method" height="342" />

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

<img width="719" alt="Remove All Categories Method Optimized" src="http://wiki.itds.pt/pub/WebITDS/XeoPrimerObjectBehavior/RemoveAllCategoriesMethodOptimized.png" title="Remove All Categories Method Optimized" height="187" />

__Figure OM.1c - removeAllCategoires method source code optimized__

a

a

a

a

a

a

a

a

a

a

a

a

a
Attachments
Topic attachments
I	Attachment	Action	Size	Date	Who	Comment
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: r8 - 2010-12-27 - PedroRio
No permission to view TWiki.WebTopBar
No permission to view TWiki.WebBottomBar