-- PedroRio - 17 Dec 2010

XEO Library - Modeling the Entities

In the last section, you've seen how to use XEO Studio to create the XEO Model for the Author entity (named LIB_Author). Now you'll start by progressively creating the XEO Models for the other entities. To make things easier to explain and also to show XEO's ability to deal with change over time you'll first create some Object Models that do not contain all of their attributes and, as the explanation progresses, add the remaining attributes later on.

You've already learned how to add a textual attribute, define the label, set its length and make it a required attribute (from the previous section), so now you'll make use of that knowledge to define the next entity: the "Book Category". First we'll define a small convention to describe XEO Model to be used in this section of the documentation, which is depicted in the following table:

Object_Model_Name ( Object Model Label)

Attribute Name	Attribute Type	Label	Description	Length	Required	Object Type
Name of the attribute	Data type of the attribute (Text, Number)	The label to display for the attribute	Documentation about the attribute	Length of the attribute (valid for number/text attributes)	Whether the attribute is required or not	The type of Object Models with which the attribute can relate to

Note: Not all types of attributes have all properties described in the previous table. The value N/A means that the property is Not Applicable to the current attribute

An example may be more clear, for the Book Category entity ( recall the book category entity from previous sections):

LIB_BookCategory ( Book Category)

Attribute Name	Attribute Type	Label	Description	Length	Required	Object Type
name	Text	Name	Name of the category	30	true	N/A

To create the LIB_BookCategory XEO Model, go to the "File" menu, select "New" and then "XEO Object Model". In the XEO Package field, find the "LIB$1.0" package and in the name type "LIB_BookCategory", in the description you can write "Represents a book category". Press finish and add a "Text" attribute and fill the name field with "name", label with "Name" , description with "Name of the category", length with 30 and in the "Required" section, choose "BOL" from the dropdown menu and type "true" in the field that appears. Your XEO Model should look like the one depicted in figure ME.1 and ME.1a.

Figure ME.1 - Book Category Object Model

Figure ME.1a - Book Category Name Attribute

Next, create the XEO Models for entities Publisher and Book. Create the Publisher entity as the following (use the new XEO Object Model wizard as before and choose the LIB$1.0 Package):

LIB_Publisher ( Publisher )

Attribute Name	Attribute Type	Label	Description	Length	Required	Object Type
name	Text	Name	Publisher Name	40	true	N/A
address	Text	Address	Publisher Address	100	true	N/A
website	Text	WebSite	Publisher Website	40	false	N/A

Then, create the Book entity with the following definition (also in the LIB$1.0 package):

LIB_Book ( Book )

Attribute Name	Attribute Type	Label	Description	Length	Required	Object Type
title	Text	Title	Book Title	100	true	N/A
isbn	Text	ISBN	Book ISBN	13	true	N/A
edition	Text	Edition	Book Edition	30	true	N/A
summary	LongText	Summary	The Book's Summary	N/A	false	N/A
frontCover	BinaryData	Front Cover	The Book's Front Cover	N/A	false	N/A
backCover	BinaryData	Back Cover	The Book's Back Cover	N/A	false	N/A

Save both XEO Models and by now you'll have four XEO Object Models (LIB_Author, LIB_BookCategory, LIB_Publisher and LIB_Book). If you recall from the introduction, the Book entity had a 1:N relation with authors and categories and a 1:1 relation with publishers. You'll now add those relations to the LIB_Book Object Model.

Adding a 1:1 Relation attribute

You'll begin with the 1:1 relation with publishers. Open the LIB_Book Object Model and add another attribute of type "Object". For the attribute name use "publisher", for the label type "Publisher" and in the description type "Book Publisher". You'll notice that "Object" attributes have a different set of properties from previous attributes created, one of them being the "Type" (highlighted in red in figure ME.2). The type property defines which type of instances (i.e. instances of which XEO Model) can relate to instances of the current XEO Model; in this situation you want that LIB_Book instances have a relation with LIB_Publisher instances so you'll have to select the LIB_Publisher object model.

The default value for the Type property of an Object attribute is object.boObject. boObject is the super class for all Object Model instances (similar to Object in Java) and you can use it as representation of "any Object Model". The object.XEOModelName is the syntax used internally but by pressing the "Browse" button (see figure ME.2) you only need to choose from the list of XEO Models in your project (Typing XEO Model names will narrow the list progressively). Choose "LIB_Publisher" as the type for the publisher attribute.

Figure ME.2 - Editing an attribute of type Object (for the LIB_Book Object Model)

Note: Object attributes can have several more properties which will be discussed later in the documentation (for example, it's possible to declare the following: instances "LIB_Book" have a 1:1 relation, through attribute X, with an instance of Model A, Model B or Model C, instead of just one possible target).

This is the state of the LIB_Book Object Model after adding the Object Attribute.

LIB_Book ( Book )

Attribute Name	Attribute Type	Label	Description	Length	Required	Object Type
title	Text	Title	Book Title	100	true	N/A
isbn	Text	ISBN	Book ISBN	13	true	N/A
edition	Text	Edition	Book Edition	30	true	N/A
summary	LongText	Summary	The Book's Summary	N/A	false	N/A
frontCover	BinaryData	Front Cover	The Book's Front Cover	N/A	false	N/A
backCover	BinaryData	Back Cover	The Book's Back Cover	N/A	false	N/A
publisher	Object	Publisher	The Book's Publisher	N/A	false	LIB_Publisher

To finalize the LIB_Book Object Model you'll need to add the 1:N relations (with Categories and Authors) which will be done in the following section.

Adding a 1:N Relation (Collection) attribute

Collection attributes in XEO Models represent 1:N relations, which are among the most common in XEO Object Modeling. To create a Collection attribute it's required to specify not only the target Object Model(s) but also the cardinality of the relation (minimum an maximum), as usual there are several other options which will be explored later. Check figure ME.3 to see how to create the collection attribute for the "Book Categories" relations.

Figure ME.3 - Editing an attribute of type Collection (for the LIB_Book Object Model)

Add another Collection attribute named "authors" (label = Authors, description = "Book Authors", type = LIB_Author). The LIB_Publisher Object Model has a 1:N relation with Publisher Nucleus, and a 1:N relation with Contacts but we'll leave for later. In the next section entities representing users and their interaction with books shall be created. The final LIB_Book entity should be like the following:

LIB_Book ( Book )

Attribute Name	Attribute Type	Label	Description	Length	Required	Object Type
title	Text	Title	Book Title	100	true	N/A
isbn	Text	ISBN	Book ISBN	13	true	N/A
edition	Text	Edition	Book Edition	30	true	N/A
summary	LongText	Summary	The Book's Summary	N/A	false	N/A
frontCover	BinaryData	Front Cover	The Book's Front Cover	N/A	false	N/A
backCover	BinaryData	Back Cover	The Book's Back Cover	N/A	false	N/A
publisher	Object	Publisher	The Book's Publisher	N/A	false	LIB_Publisher
categories	Collection	Categories	The list of Book Categories	N/A	false	LIB_BookCategory
author	Collection	Authors	The list of Book authors	N/A	false	LIB_Author
state	Text (Lov)	State	The state of the book (if it's loaned or in the library	1	true	N/A

Notice the state attribute, which represents the state of the book (whether it's in the library or with some library user). The state is an attribute which can have two values (available/unavailable) and instead of using the value 0/1 or true/false in a Number/Boolean attribute and having to make the conversion each time you want to display the value (i.e. to show the string "Available" or "Unavailable) you'll use a XEO Lov (List of Values) which allows you to map keys to values (and you'll map "0" to "Unavailable" and "1" to Available) and integrates directly with the XEO Model, see the next section on how to create a XEO Lov.

Introducing XEO Lovs ( LIB_Book state )

A XEO Lov is a file with the .xeolov extension and it's basically a container for lists of values (i.e. one .xeolov file can have multiple lists of values). Alternatively XEO Model attributes can define their own List of Values, but that list cannot be reused by another attribute (nor in another XEO Model). To create a new XEO Lov file, go the "File" menu, choose "New" -> "XEO Lov", choose the "LIB$1.0" package type the name "LIB_Lov" and press finish.

After finish is pressed, the XEO Lov editor will open (the screen is depicted in figure ME.3a, where the default "lov1" List is chosen)

Figure ME.3a - XEO Lov Editor

When a new XEO Lov file is created, a single list of values is created by the name of "lov1" with two items (label1/value1 and label2/value2), use the buttons in the details panel (on the right, in figure ME.3a) to edit the values so that they match the following screen (figure ME.3b) and save the XEO Lov.

Figure ME.3b - XEO Lov editor with the State Lov values.

To finalize the LIB_Book entity the state attribute, must be linked to the "book_state" lov in the LIB_LOV.xeolov file. Open the LIB_Book XEO Model and select the state attribute and scroll down to the "Lov" section in the attribute's details panel. Press the "Browse" button and start typing "book_" in the text field to narrow the choice of lovs, select the "book_state" lov and press ok (see figure ME.3c for details).

Figure ME.3c - Choosing a lov item for the values of the state attribute in the LIB_Book XEO Model.

Save the XEO Model to finalize the changes and proceed to the next section to create the remaining XEO Object Models.

Librarians, Users, Messages, Movements and Returns

In this chapter you'll model the entities that deal with users and their interaction with books. (Librarians and Users, Movements and Returns and finally the Messages librarians can send each other). XEO provides a set of XEO Models that help dealing with users, so the best way is always to reuse one of those. One the XEO Models is the iXEOUser interface which declares a set of attributes (name, username, password, id, e-mail) necessary for user accounts. Librarians and Users will require these attributes and add another attribute which is the library identifier (for users) and library employee identifier (for librarians). The librarian also has a 1:N relation with the messages entity.

Overriding attributes in an implemented interface

It's also possible to override an attribute definition inherited from an implemented interface. This is usually done usually to add custom behavior to that attribute (which may not be present in the interface). In the XEO Library application you'll override the e-mail and username attribute in both Librarians and Library Users to add custom behavior later on.

Figure ME.4 - User and Librarian implementing interface iXEOUser and additional attributes regarding user identification

Start by creating the Library User and Librarian models with the following structure (respectively):

LIB_User ( Library User )

Attribute Name	Attribute Type	Label	Description	Length	Required	Object Type	Notes
userIdentifier	Number	Library ID	Library Identifier	10	true	N/A	-
active	Boolean	Active	User is Active Flag	N/A	false	N/A	-
email	Text	E-mail	The user's e-mail	30	true	N/A	Overrides the attribute in iXEOUser
lastname	Text	Last Name	The user's last name	30	true	N/A	-
username	Text	Username	The username	30	true	N/A	-

LIB_Librarian( Library Employee )

Attribute Name	Attribute Type	Label	Description	Length	Required	Object Type	Notes
employeeId	Number	Employee Number	Identifier of an Employee	10	true	N/A	-
email	Text	E-mail	The librarian's e-mail	30	true	N/A	Overrides the attribute in iXEOUser
lastname	Text	Last Name	The librarian's last name	30	true	N/A	-
username	Text	Username	The librarian's username	30	true	N/A	-

Now, you must set both the Object Models to implement the iXEOUser interface. Doing so, requires to open each Object Model, find the "General" section and press the "Edit..." button which will open the general properties in the details panel; find the "Implemented Interfaces" section and press the add button. The result is depicted in figure ME.5.

Figure ME.5 - Interface Implementation in XEO Studio

Next, you'll create the Movement entity (representing a Library User taking some books home, from the library). Create the LIB_Movement Object Model in the LIB$1.0 package as usual) with the following attributes.

LIB_Movement ( Movement )

Attribute Name	Attribute Type	Label	Description	Length	Required	Object Type	Notes
id	Sequence	Id	Identifier	10	true	N/A
dueDate	Date	Due Date	Due date for the movement	N/A	true	N/A
fine	Number	Fine	Fine to apply to the user of this movement (if delivery not in time)	10	false	N/A
user	Object	User	User that took the books home	N/A	true	LIB_User
books	Collection	Books	Books took by the user	N/A	false	LIB_Book
state*	Text (Lov)	State	The state of the movement (open / closed)	1	true	N/A	Link to "movement_state" lov

*Create a Lov in LIB_Lov.xeolov named "movement_state" with two items (label/value): "Open" / "0" and "Closed" / "1".

Instances of the Return entity only make sense if there's an instance of the Movement entity to associate them with (you can't return books you haven't taken). Recall from the XEO Concepts that XEO can declare Object Models which can only exist as children of other Object Models, those were referred to as Orphan and Non-Orphan Object Models. In the case of the return entity it's an example of a non-orphan entity (i.e. it cannot exist as an "orphan", it must have a parent), as such, when creating the Return entity we need to uncheck the "Orphan" box in the XEO Studio Wizard (as depicted in figure ME.5a, highlighted in red).

Figure ME.5a - Creating a non-orphan Object Model - LIB_Return

Afterwards create the Return entity with the following attributes:

LIB_Return (Return)

Attribute Name	Attribute Type	Label	Length	Description	Required	Type
id	Sequence	Id	10	Identifier	true	N/A
note	Text	Note	100	Note for this return	false	N/A
books	Collection	Books	N/A	Books returned	false	LIB_Book

Save the LIB_Return Object Model and add a collection attribute to the LIB_Movement Object Model for the returns, the LIB_Movement entity should have the following structure:

LIB_Movement ( Movement )

Attribute Name	Attribute Type	Label	Description	Length	Required	Object Type
id	Sequence	Id	Identifier	10	true	N/A
dueDate	Date	Due Date	Due date for the movement	N/A	true	N/A
fine	Number	Fine	Fine to apply to the user of this movement (if delivery not in time)	10	false	N/A
user	Object	User	User that took the books home	N/A	true	LIB_User
books	Collection	Books	Books took by the user	N/A	false	LIB_Book
returns	Collection	Returns	List of returns made by the user	N/A	false	LIB_Return

_

Message and Librarian (finalizing)

Create the Message Object Model with the following structure:

LIB_Message( Message )

Attribute Name	Attribute Type	Label	Description	Length	Required	Object Type
subject	Text	Subject	Subject of the Message	50	true	N/A
bodyMessage	LongText	Body	The body of the message	N/A	true	N/A
date	Date	Date	Date of the message	N/A	false	N/A
urgent	Boolean	Urgent	Whether the message is urgent or not	N/A	false	N/A
recipients	Collection	Recipients	The recipients of the message	N/A	false	boObject*

* - As explained before, boObject is the generic object type in XEO, which means that using boObject in the type of a collection attribute allows you to relate with any instance of any Object Model. In this situation, however, we only want to allow a message to be delivered to a specific librarian, or to a group of librarians, as such the definition of the recipients attribute should allow to relate to instances of the LIB_Librarian Model or with groups of Librarians. One of XEO's built-in Object Models is the Ebo_Group which represents a group of users in the application and you'll use that for the recipients attribute. When creating the recipients attribute, choose as type "boObject" and scroll down to the "Objects" section and press the "add" button to add the LIB_Librarian and Ebo_Group Models to the definition, this will restrict the type of instances for the relation. See figure ME.6 for details.

CollectionWithTypes" src="http://wiki.itds.pt/pub/WebXEO/XeoPrimerObjectModellingLibrary/MessageObjectCollectionWithTypes.png" title="Message Object CollectionWithTypes" height="344" />

Figure ME.6 - Collection attribute with restrictions to the type of target Object Models.

With the LIB_Message XEO Model complete, you just need to add a collection attribute to the LIB_Librarian so that it keeps track of what messages it has sent. The final structure for the LIB_Librarian Object is the following:

LIB_Librarian( Library Employee )

Attribute Name	Attribute Type	Label	Description	Length	Required	Object Type
employeeId	Number	Employee Number	Identifier of an Employee	10	true	N/A
messages	Collection	Messages	Messages sent by this librarian	N/A	false	LIB_Message
email	Text	E-Mail	The librarian's e-mail	30	true	N/A
lastname	Text	Last Name	The librarian's last name	50	false	N/A
username	Text	Username	The librarian's username	50	true	N/A

To finalize the entity modeling, the only remaining entities are the Contact and Publisher Nucleus, which you'll create in the next section.

Contact and Publisher Nucleus

A contact is an entity to help represent the contacts of people connected to the publishers and their nucleus, thus it only makes sense when connected to those entities and should be created as a non-orphan entity. The definition of a contact is the following (create it in the LIB$1.0 package):

LIB_Contact( Contact )

Attribute Name	Attribute Type	Label	Description	Length	Required	Object Type
name	Text	Name	Name of the contact	100	true	N/A
phone	Text	Phone	Phone number of the contact	10	false	N/A
email	Text	E-mail	E-mail of the contact	50	true	N/A
businessCard	BinaryData	Business Card	Image with the business card of the identifier	N/A	false	N/A

The Publisher Nucleus entity can only exist when a parent Publisher is responsible for it, as such, the LIB_PublisherNucleus is a non-orphan Object Model (uncheck the "Orphan" option in the new XEO Model wizard), which has the following structure:

LIB_PublisherNucleus( Publisher Nucleus )

Attribute Name	Attribute Type	Label	Description	Length	Required	Object Type
name	Text	Name	Name of the nucleus	100	true	N/A
address	Text	Phone	Address of the nucleus	100	false	N/A
contacts	Collection	Contacts	List of contacts for this nucleus	N/A	false	LIB_Contact

Also, you need to change the LIB_Publisher XEO Model (adding the relation to contacts). The final definition for the LIB_Publisher XEO Model is the following:

LIB_Publisher ( Publisher )

Attribute Name	Attribute Type	Label	Description	Length	Required	Object Type
name	Text	Name	Publisher Name	40	true	N/A
address	Text	Address	Publisher Address	100	true	N/A
website	Text	WebSite	Publisher Website	40	false	N/A
contacts	Collection	Contacs	Publisher Contacts	N/A	false	LIB_Contact

Save all open XEO Models and you've finalized the initial modeling of the XEO Library entities. Jump to the next chapter to know how to add behavior to the XEO Models.