--
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:
- General Model properties
- Attributes
- OPL
- Events
- 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)
_
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);
_
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
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:
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 {
}
_