-- PedroRio - 30 Jan 2011

XEO Object Model Reference

This section is a reference of all options regarding the creation of a XEO Object Model and it's divided in five (5) parts:

1. General Model properties
2. Attributes
3. OPL
4. Events
5. Methods

General Model Properties

In XEO Studio, while editing the general properties of an Object Model, you'll see the following: (depicted in figure ModelRef.1)

Figure ModelRef.1 - General Properties Editing for an Object Model.

Reference of XEO Model General Properties

1 - Name

The name of the XEOModel, this name must be equal to the name of file. This is the name that's used when referencing this XEO Model from other XEO Models (like when creating collection attributes, or relation attributes) or the name to be used in XEOQL expressions.

2 - Type

The type of the XEO Model. There are three different types of XEO Models:

• Object
• Abstract
• Interface

The most common type is "Object", which allows you to create instances of the given Model. The "abstract" type represents an abstract Model (much like an abstract class in Java) which allows you to define a set of attributes, events, etc... which you can later reuse in concrete (i.e. type "Object") XEO Models, by extending the abstract XEO Model. The Interface type, represents an interface which Models can implement, therefore inheriting all of their attributes and becoming of that type (i.e. if Model A implements interface B, issuing a XEOQL expression of "select B" will return all instances of A, along will all other instances of Models that implement B).

You cannot create instances of Models that are either Interface or Abstract.

3 - Orphan

Determines whether instances of this Model are Orphans or not ( recall from the XEO Concepts). An orphan instance is one that can exist by it self, while a non-orphan instance is one that can only exist with a parent instance. Think of an invoice and an invoice line, it only makes sense for an invoice line to exist if it's inside an invoice.

While a Model can be declared an Orphan/Non-Orphan using this property, relations between Models can also change that situation. See in Attributes.

4 - Extends

Any Model can extend other Model (single inheritance), inheriting it's attributes, events and methods. Any of those attributes, events and methods can be redefined in the extending Model. In this property you choose the Model to extend.

5 - Description

A description of the Model, serves as documentation.

6 - Label

A label for the Model, it's used throught the application in places such as the "New OBJECT_LABEL" menu in toolbars, when a label of the Object Model is displayed.

7 - Mastertable

The MasterTable property allows you to choose the database table that will hold this Object Model's data (see Database Manager section, also). It can be used for:

• Object Models that extend other Models and you want to have all instances in the same table
• Mapped Object Models (from existing database tables)

_

8 - CardID

The CardID of a XEO Model is a way to identify its instances. The name CardID derives from the idea of an Identification Card (or Business Card) that people have. For a person you normally have their name, phone number, e-mail, etc. The CardID property is declared using a syntax which allows to refer to the instance's attributes to compose an "Identification Card" for that particular instance. For example, if Object Model "A" has attributes name, task and age and you use the following expression for the CardID:

[name] is a [task]

And an instance has the following values for the name, task and description attributes (respectively): "John Smith", "Manager", "30". The CardID for that instance will be:

John Smith is a Manager

If you use the following CardID declaration:

[name] : [age]

The same instance would have the following CardID.

John Smith : 30

Important:

• The CardID for each instance is a calculated value. It's not stored persistently, as such you can change it as many times as you want while building your application.
  
• The syntax for a CardID expression is any name of a XEO Model attribute inside square brackets to refer to their value. Any other character will be interpreted as a literal text.
  

_

9 - Extends Java

Every Object Model is converted to a Java class that extends from the netgest.bo.runtime.boObject class. It's possible to make it that the generated Object Model extends from a different class (which, however, must extend from the boObject class), in order to do processing of something in a different way. To use that class as the base for the Object Model you'll need to type the fully qualified name of that class.

_

10 - Implemented Interfaces

A list of all the implemented interfaces by the current Model. An Object Model can declare that it implements any number of interfaces (and will inherit all of their attributes and events).

11 - Versioning

Activates versioning for the current Object Model. Whenever an instance of the current Model is saved, if any of its attributes are changed, a new version of the instances is created. The list of versions of a given instance can be seen in an edit viewer of the instance if the renderListVersionBtn property of the editToolBar component is true, in that viewer and versioning is active in the XEO Model)

In order to have programatic access to the versions of an object you need to do the following:

• Retrieve the most recent instance (by loading it)
• Create a context to hold the prior version (if you use the same context, it will override your instance)
• Rollback the instance in the new context
• Load the instance to that new context

Sample code bellow:

boObject        objectVersion = boObject.getBoManager().loadObject(eboCtx, bouiVersion);
            
boVersioning    versioningManager = new boVersioning();
long            bouiOfObject = objectVersion.getAttribute("changedObject").getValueLong();
long            versionOfObject = objectVersion.getAttribute("version").getValueLong();
            
//Create a new context to hold the rollback version
//which means the original object can be left alone
versioningManager.rollbackVersion(newContext,bouiOfObject,versionOfObject, true);
            
boObject        rollBackVersion =  boObject.getBoManager().loadObject(newContext, bouiOfObject);

_

12 - TextIndex

TextIndex will (if active) index all simple type attributes of this Model (integer, string, date, etc...) and will index all simple types of child objects if the "appendChilds" attribute is true (and the childs are declared in the "attributes" box. If references to other Object Models are specified you can set how deep the indexer should go and if it should index all attributes or only the CardID of those instances. Non-Orphan childs will always be indexed.

The active property activates the indexer for this Object Model.

The appendChilds property activates the indexer for simple properties of the Object Models related through object and collection attributes (they must be declared in the attributes section)

The deep property allows you to choose how deep the indexer will go when indexing attributes of related Object Models.

Attributes - Which attributes to index and if only the cardId of the attribute (object attribute is indexed)

_

13 - Locale

Defines the Object Model's locale. The most important property is the "Language" property as it defines the language of the XEO Object Model which is used to decide if the labels for the attributes, methods, etc... are retrieved from the XEO Model itself or from one of the translation files.

14 - Database Manager

The database manager section has four (4) properties:

• Xeo Compatible (boolean)
• Manage Tables (boolean)
• Manage Views (boolean)
• Manager Class (String)

This section allows to choose some properties regarding the data source of the Object Model.

The Xeo Compatible option is an option that by default is "true". If false is the value of this property the Object Model is marked as not being XEO Compatible, which means you'll have to provide a value for the "Mastertable" property, for it to know where to retrieve the data. You may also provide a "Manager Class" that will provide the means to access/update the data for this Object Model, or use XEO's default Manager class attempt to provide that for you ()

The Manage Tables option has true as a default value and if the value is false means that XEO will not create the tables for this Object Model.

The Manage Views option has true as a default value and if the value is false means that XEO will not create the views for this Object Model.

The Manager Class option allows you to specify the fully qualified name of a class that implements the netgest.bo.data.IXEODataManager interface which will be responsible for managing data for the instances of this Object Model.

Attributes

Common attribute properties - Every type of Object Model Attribute has a set of properties which are common between other types. This section explains those common properties.

AttributeText - An attribute to represent a small/medium string of text.

AttributeNumber - Attribute to store numbers of any kind

AttributeBoolean - Represents a boolean (true/false) value

AttributeObjectCollection - Represents a relation to a collection of other instances

AttributeObject - Represents a relation with a single instance

AttributeDate - Represents a date (without time) - Does not have special attributes

AttributeDateTime - Represents a date (with time) - Does not have special attributes

AttributeSequence - Represents a sequence of values

AttributeBinaryData - Represents generic binary data (usually a file) - Does not have special attributes

AttributeLongText - Holds large amounts of text

AttributeDuration - ( Deprecated) - Represents a duration of time.

_

OPL

OPL (Object Policy Labeling) allows you to create a permission system for instances at runtime. You can configure custom rules by implementing an interface (also known as class keys), or more generic rules using attribute keys.

Class Keys

To use a class key you must implement the ISecurityClassKeys interface and declare it in the XEO Model, like depicted in figure ModelRef.2a.

Figure ModelRef.2a - Class Keys configuration with sample org.example.security.SecurityImpl class

To configure an Attribute Key you use the same "Add" button, but choose "Attribute Key" and then choose which type (Read, Write, Delete, Full Control) you want. Then you configure for which attribute (the attribute must represent a user, groups of users or role) the attribute key applies to, like depicted in figure ModelRef.2b, bellow.

Figure ModelRef.2b - Attribute Key configuration (2 attribute keys, Read and Write, for the CREATOR and SYS_USER attribute)

_

Events

As depicted in figure ModelRef.3, the Events section allows you to define an event and open the editor to type the code of the event.

There are four different types of actions which trigger eight (8) events (each action generates an OnBeforeEvent and an OnAfterEvent)

• OnBeforeCreate (triggered when a new instance of the object model is to be created)
• OnBeforeLoad (triggered when an existing instance of the object model is to be loaded)
• OnBeforeSave (triggered when an instance (new or existing) of the object model is to be saved)
• OnBeforeDestroy (triggered when an existing instance of the object model is to be deleted)
• OnAfterCreate (triggered after a new instance of the object model is created)
• OnAfterLoad (triggered after an existing instance of the object model is loaded)
• OnAfterSave (triggered after an existing instance of the object model is saved)
• OnAfterDestroy (triggered after an existing instance of the object model is deleted)

Note: OnBefore* events are Java methods that return boolean. If the return value is false the action (create, load, save, destroy) will not be executed and an error will be generated. OnAfter* events are also Java methods, but are void and don't interfere with the instance.

Figure ModelRef.3 - Events editing screen (other options blured to highlight events)

_

Methods

Methods in a XEO Object Model allow you to define an operation that is specific of a given entity and can be invoked either via XEO's API or using XEO Web Viewers (XEO Model methods are automatically included by default in an EditToolBar component (inside FormEdit components)).

Figure ModelRef.4 depicts what you see in XEO Studio while editing a Method:

Figure ModelRef.4 - Editing a Method in XEO Studio (other properties blurred to highlight Methods)

The following section will explained each option of a Method (following the numeration in figure ModelRef.4)

1 - Name

The name of the method (its identifier). This is identifies the method and allows you to invoke the method using XEO's API, or to use the xvw:modelMethod component to create a single method in a toolBar.

2 - Label

The label of the Method. The label is displayed when the method is rendered as button in a toolbar.

3 - Icon

The icon of the method. If declared, when the method is rendered as a button in a toolbar, that button will have the icon image declared in this option.

4 - Menu

Deprecated

5 - ToolBar

Whether or not this method should appear in an editToolBar automatically, when rendered in an edit form.

6 - Transaction

TODO: Não parece ser usado, porque no boDefMethodImpl (parse do XML dos métodos) o Transaction é uma propriedade booleana que só é usada no serializeMethod() da classe boDefSerializer.

There are four options:

• Required
• RequiresNew
• Supports
• NotSupported

7 - Hidden When

Condition to declare when the method should not be rendered in an edit toolbar automatically. The condition must be set using Java code, the method must return a boolean value indicating whether the method is hidden or not. XEO Studio automatically generates a handler class for the XEO Model and creates the method with the correct signature so that you only have to create the business logic.

8 - Body

The body option is where you create the set of instructions that make the method's logic. You must set it using Java (again, XEO Studio will create a method in the XEO Model's handler class so that you only have to code the method's logic).

If you have a method named "executeActions" the skeleton of the code generated by XEO Studio will be the following:

public void executeActions(boObject obj) throws boRuntimeException {      
}

_