(r10) XeoPrimerConcepts < WebXEO

WebXEO Web>XeoPrimer>XeoPrimerConcepts (revision 10) (raw view)~~EditAttach~~
-- Main.PedroRio - 06 Dec 2010
---+ XEO Concepts

This chapter introduces the basic concepts necessary to use the XEO framework an XEO's approach to development.

---+++ XEO's approach to development

XEO was designed from scratch with the purpose of modelling business (real-world) entities using an object oriented approach, as the team felt that that was the most natural way of developing a web-application. Being able to create an entity, its data model and web pages for listing all instances of that entity (with powerful options such as ordering and grouping), editing single instances and searching a particular instance, while still being able to use customized logic to implement behavior, without dealing with all the low-level complexities was truly the ultimate goal.

Developing starts by defining a set of entities (XEO Object Models) and their properties, using XEO Studio's Object Model editor (basically a graphic editor for a specific XML language). Those entities are processed by the framework in a processes known as "XEO Build" which generates the data model, and support classes to interact with the entities. Using the Object Model as a base, web viewers for listing, edit and search instances can be "scaffolded" (ala Ruby on Rails) by XEO Studio.

As seen above, using XEO is all about modelling business entities as XEO Object Models, which will be used by the framework to create the data model, logic and web layer for each of those entities, which can then be further customized to fit the business logic of the application. Let's begin with the basics of a XEO Object Model (to know more about how a XEO Object Model is used to build your application, check the "XEO Model Builder" section)
---+++ XEO Object Model

An Object Model is the XEO representation of a business entity. Almost every business entity can be described in a number of "atributes" and relations with other entities (be it relations of extension, 1-1 relation, or 1-N relation). For example, if we're modelling a entity that represents a "Book" in real life, that book would probably have attributes such as the book's title, the author's name, the edition number or category list (drama, romance, etc...) of the book.
---+++++ Attributes

In a XEO Object Model, attributes modelling the properties of a business entity can be of different types. XEO provides attributes that represent Textual values ( *AttributeText*), Numeric Values ( *AttributeNumber*), Date and Time values ( *AttributeDate* and *AttributeDateTime*), Sequential Values ( *AttributeSequence*), Long textual values ( *AttributeLongText*) and Boolean values ( *AttributeBoolean*) as well as attributes to make a 1:1 relation (single relation - *AttributeObject*) and to make a 1:N relation (a relation to a collection of objects - *AttributeObjectCollection*)

Each of those types of attribute have specific properties which can be set to customize their behavior, which we'll see further in the documentation. These properties vary with the type of attribute, naturally. For example, a Numeric Value can have a property _maxValue_ and _minValue_ (which specify maximum and maximum values for the attribute) while a collection attribute can have the maximum number of objects to which the first can relate to (or declare the type of objects to which the first can relate to)
---+++++ Custom Behavior (Logic)

One of the defining features of XEO is the possibility to associate business logic directly to the Object Models, and also with their attributes. By allowing business logic to be "embedded" in the Object Model, instances of a given model are now almost like "living entities" which respond to events and have customized actions all without complex code managing events handling and etc. Custom Business Logic is defined using the Java Language and interaction with the current instance object (or other objects) can be done by using XEO's Java API. Such logic can influence the viewer layer, because logic can determine whether a given object/attribute is visible, required, etc...

Let's take a look at the possibilities for defining business logic in an Object Model.
---++++++ Attributes

Attributes themselves can have logic associated. For example, a given attribute may have a default value that is calculated, or its value may need be validated when its value is changed (and that validation, may required more or less complicated operations).

Attributes can have logic to define the following

   * <strong>Validation </strong>(code that will run when the parent instance object is saved, to check it the current value of the attribute is valid)
   * *Default Value* (code that will run when the parent instance object is first saved and the value of the attribute was not set, default value can be made to depend on the values of other attribute)
   * <strong>Requirement </strong>(code that determines whether or not the value of this attribute must be set before the parent object can be saved)
   * <strong>OnChange </strong>(code that will run whenever the value of this attribute is changed)
   * *Disabled When* (code that will determine when the attribute is disabled (i.e. its value cannot be changed))
   * *Hidden When* (code that will determine when the attribute is hidden - this logic is directly associated with the viewers layer
   * *Formula* (code that will run to determine the value of the attribute, allows to do calculations and such)
---++++++ Events

Every instance of an Object Model can react (i.e. execute Java code) to certain actions in its life cycle. Each action generates two events (an <em>onBeforeAction </em>event and an <em>onAfterAction </em>event) in which you can write your code, the list of actions (and events) is as follows:

   * create ( _onBeforeCreate_ and _onAfterCreate_)
   * load ( _onBeforeLoad_ and _onAfterCreate_)
   * save ( _onBeforeSave_ and _onAfterSave_)
   * destroy ( _onBeforeDestroy_ and _onAfterDestroy_)

Each <strong>onBefore</strong>Event returns a boolean value. If the returned value is true, the action (load, create, save, destroy) associated with the event is carried on, otherwise the action is not executed (this allows, for example, to control when an object is to be deleted, if all required conditions for that to happen are met)

In the following figure is depicted the XEO Events mechanims and when they are triggered given a certain action performed on an instance object.

<img width="960" alt="XEO Object Events" src="http://wiki.itds.pt/pub/WebITDS/XEoPrimerConcepts/ObjectsEvents.png" title="XEO Object Events" height="720" />
---++++++ Attribute Events

Attributes may also react to events triggered by actions made upon the attributes and there are three groups of events available. The first group of events (regular events) is applicable to all attributes, except collection attribute (AttributeObjectCollection), the second group is only applicable to collection attributes (collection events) and the last group contains the events that are common to all attributes (common events). The List is as follows:

Regular Events:

   * *OnBeforeGetValue* (Triggered before a value is loaded into the attribute)
   * *OnAfterGetValue* (Triggered after the value is loaded into the attribute)

Collection Events:

   * *OnBeforeAdd* (Triggered before an object is added to the collection)
   * *OnBeforeLoadBridge* (Triggered before the collection is loaded)
   * *OnBeforeChangeOrder* (Triggered before an object in a collection is moved inside the collection, when it changes the order of the object)
   * *OnBeforeRemove* (Triggered before an object is removed from the collection)
   * *OnAfterAdd* (Triggered after an object is added to the collection)
   * *OnAfterLoadBridge* (Triggered after the collection is loaded)
   * *OnAfterChangeOrder* (Triggered after an object is moved inside the collection, when it changes the order of object)
   * *OnAfterRemove* (Triggered after an element is removed from the bridge)

Common Events:

   * *OnChange* (Triggered when the attribute is changed)
   * *OnBeforeChange* (Triggered before the attribute is actually changed)
   * *OnAfterChange* (Triggered after the attribute is actually changed)

aaa

---++++++ Methods

Most often, business entities modeled in an application have logic associated with them (i.e. entities are not just there to represent the data model). Often enough, that logic is decoupled from the entity model due to constraints of the programming language/framework used to create that application. Using XEO, entity business logic can be created right along side the model of the entity, in the form of "Methods". Methods are entry-points in a XEO Object Model to declare business logic associated to the entity; those methods will be available in all instance objects and can perform any desired actions.

Imagine, for example we're dealing with Invoices (each Invoice has several "Invoice Lines" each of those lines has a state indicating whether it has been processed or not). The Invoice entity has a flag (true/false) which determines when that Invoice has been processed (an Invoice is considered _processed_ when all its items [Invoice Lines] have been processed). At a given point in time in the application, some action occurs and the consequence of that action is that a given invoice should be considered "processed". Using XEO Methods, we can defne a _processInvoice_ method (which will available to all instance of the Invoice Object Model) that will check every Invoice Line of the instance and set its _processed_ attribute to true and in the end, change the _processed_ attribute of the Invoice to true.

By declaring a method in a XEO Object Model that behavior is now available in every instance of the Object Model; furthermore if that Object Model is used in another application that behavior is taken along with the Model definition, there's no need to "hunt down" the code in the application logic layer.

In the figure bellow is depicted how the process of defining and invoking a XEO Method on an instance object.

<img width="960" alt="XEO Methods" src="http://wiki.itds.pt/pub/WebITDS/XEoPrimerConcepts/Methods.png" title="XEO Methods" height="720" />

---+++++ OPL (Object Policy Labeling)

One important factor when creating a business application is security (including permissions). XEO has a feature named Object Policy Labeling (OPL) which helps to create a permission system for Object Instances.

When defining a XEO Object Model, we can determine who has the permission to read the instances, change the instances, delete the instances or have full control over instances, these are called "AttributeKeys".
---++++++ AttributeKeys

A note before explaining the OPL mechanism: The XEO framework includes some System Object Models which represent entities such as Users, Groups and Profiles and those Object Models are required to set the OPL mechanism (worry not, because it's possible to use your own users/groups with OPL)

The main idea is to give read/write/delete/full control permissions to instances of a User/Group/Role Object Model which means a given XEO Model must declare an AttributeObject relation to a User/Group/Role and then a read/write/delete/full control permission can be given to the

The following figure depicts and example of OPL usage.

<img width="960" alt="XEO OPL" src="http://wiki.itds.pt/pub/WebITDS/XEoPrimerConcepts/OPL.png" title="XEO OPL" height="720" />
---++++++ Class Keys

There's also the possibility to create user-defined permissions by implementing specific interfaces. Implementing these interfaces allows great liberty for developers which may defined complex permission rules, such as "a given group can only change objects on even days between 13:00 and 15:42", these are known as ClassKeys (will be explained in another Chapter)

__FALTA FALAR DE SEGURANÇAS COM EBO_POLICY (mas só genericamente)__

---+++ XEO Interfaces / Extension

Most object-oriented languages have concepts like Inheritance and Interfaces. XEO being a Java-based framework makes use of those concepts in its XEO Object Models.
---++++++ XEO Object Model Extension

When creating a new XEO Object Model we can extend an existing Object Model (and inheriting all of its attributes, events and methods). If required all of these can be overridden in the new Object Model. Extension can be seen just like in a regular object oriented programming language (although there's no multiple inheritance, like in C++).
---++++++ A XEO Interface

A XEO Interface is similar in objectives to a Java Interface, meaning that Object Models that implement the XEO Interface share the same type, *but contrary to Java Interfaces*, in XEO Interfaces you can define regular object attributes, events and methods and *when an object implements the interface it will inherit all of the interface's attributes, events and methods*.

In the following figure, an example of Object Model extension and Interface Implementation is depicted

<img width="960" alt="XEO Interface and Extension" src="http://wiki.itds.pt/pub/WebITDS/XEoPrimerConcepts/InterfaceAndExtension.png" title="XEO Interface and Extension" height="720" />
---+++ Orphan / Non-Orphan Object Models

In most applications there's a notion of entities that can only exist if a another entity exists, or more properly, an instance of an entity can only exist if another instance of an entity exists, frequently this is called a parent-child relationship where the child cannot exist without its parent. XEO mimics this behavior with the Orphan/ Non-Orphan Concepts

Contrary to what its common in our society, the most common types of XEO Object Models, are *Orphan*. This means that instances of that model can exist without the need for a parent (hence the term "Orphan"). Instances of Non-Orphan Object Models can only exist in the context of a parent instance.

XEO will only allow to create instances of Non-Orphan Object Models, if there's a parent instance object, the visual layer will reflect this kind of relation. A good example of Orphan/Non-Orphan relation is the Invoice/Invoice Line example. An Invoice would be an Orphan Object Model and the Invoice Line would be a Non-Orphan Object Model.
---+++ XEO Package

XEO Object Models can be logically grouped in XEO Packages, which helps organizing an XEO application. XEO Packages can have sub-packages to further organize the application structure. XEO Packages do not, however, separate Object Models by namespace or package name, this means that if you create two objects with the same name in different XEO Projects, only one will make it your to application.

__Como é a order, o primeiro a ser encontrado fica, ou o último a ser encontrado fica__
---+++ XEO Lovs

Along side XEO Object Models, XEO has a concept named a XEO Lov (List of Value). XEO Lovs are basically key/value pairs of identifiers and labels, which can be used as the values for an Object Model Attribute. If a given XEO Model represents a Person which defines an AttributeText that's the country of that person, we can restrict the values of the Attribute to existing countries by using a XEO Lov. XEO Lovs are statically created. but their values are stored in the database, as such, the list of values can be changed overtime.
---+++ XEO Builder

At the heart of the XEO Framework is the XEO Builder. The XEO Builder is responsible for most the "magic" behind the scenes, which is analyzing all XEO Object Models and creating the underlying support structures. Each XEO Object Model is converted to a Java class (which is later compiled for use within our application) and database tables are created to support the current Object Model as well as auxiliar database tables (to support AttributeObjectCollections with other Object Models).

The XEO framework, includes a set of System Object Models, which are required for the correct functioning of a XEO application (namely Objects modeling groups, users, security features, etc...).

When creating a new project, all XEO Object Models will be "built" by the XEO Builder and all other required structures will also be created. Each new XEO Object Model added to the project, or Model that is altered, does not require a complete build to the project, the XEO Builder is clever enough to detect changes to existing XEO Models and build only the required ones.

The XEO Builder is integrated in XEO Studio, the primary development environment for XEO applications

__(Isto TEM DE SAIR DAQUI, mais para a frente, quando apresentar o XEO Studio?)__

---+++ XEO Web Components

XEO Framework was created to produce web-applications, as such it requires a visual layer in the form of webpages so that users can interact with instance of XEO Object Models, such as listing instances, editing specific instances or searching an instance.

XEO's Visual Layer is a component based layer, in which the nesting of components creates the desired layout for the application, the component layer (named XEO Web Components) is based on Java Server Faces (JSF base components are actually usable in along with XEO Web Components)

XEO Web Components are used inside a XEO Viewer, which is essentially a container for the components. XEO Viewers are the structure used to support the rendering of the Web Components. In a XEO Application there are four different types of Viewers:

   * Main Viewer (The viewer that creates the XEO Application's structure)
   * List Viewer (A viewer to list instances of a XEO Model)
   * Edit Viewer (A viewer to edit an instance of a XEO Model)
   * Lookup Viewer (A viewer to search/select a specific instance of a XEO Model)

List, Edit and Lookup Viewers *are designed to deal with XEO Objects, but are not limited to* XEO Objects. Most of the XEO Web Components are independent from XEO Objects and can be used to create interfaces that have nothing to do with them, i.e. *we can created customized viewers*.

First a screenshot of a typical XEO Viewer to give the feeling of a XEO application

*Main Viewer* (Defines the application structure, elements in the tree structure will be open as tabs in the white section)

<img width="1278" alt="Main Viewer" src="http://wiki.itds.pt/pub/WebITDS/XEoPrimerConcepts/MainXvw.png" title="Main Viewer" height="374" />

List Viewer

aa

Edit Viewer

aa

Lookup Viewer

aaa
Attachments
Topic attachments
I	Attachment	Action	Size	Date	Who	Comment
png	InterfaceAndExtension.png	manage	29.3 K	2010-12-10 - 10:46	PedroRio	Interface and Extension
png	MainXvw.png	manage	10.0 K	2010-12-10 - 15:32	PedroRio	MainXVW
png	Methods.png	manage	33.0 K	2010-12-09 - 11:32	PedroRio	XEO Methods
png	OPL.png	manage	38.9 K	2010-12-09 - 15:29	PedroRio	XEO OPL
png	ObjectsEvents.png	manage	23.5 K	2010-12-07 - 14:01	PedroRio	XEO Events
Topic revision: r10 - 2010-12-10 - PedroRio
No permission to view TWiki.WebTopBar
No permission to view TWiki.WebBottomBar