XeoPrimerObjectModellingLibrary < WebXEO

WebXEO Web>XeoPrimer>XeoPrimerObjectModellingLibrary (2011-04-04, NicolauGrosskopf) (raw view)
-- Main.PedroRio - 17 Dec 2010
---+ XEO Library - Modeling the Entities

In the [[WebXEO.XeoPrimerObjectModelling][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 ( [[WebXEO.XeoPrimerLibraryIntroduction][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.

<img width="800" alt="Book Category General Properties" src="http://wiki.itds.pt/pub/WebXEO/XeoPrimerObjectModellingLibrary/BookCategoryGeneral.png" title="Book Category General Properties" height="301" />

__Figure ME.1 - Book Category Object Model__

<img width="800" alt="Book Category Attribute Name" src="http://wiki.itds.pt/pub/WebXEO/XeoPrimerObjectModellingLibrary/BookCategoryAttribute.png" title="Book Category Attribute Name" height="264" />

__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):

<strong>LIB_Publisher </strong>( 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 [[WebXEO.XeoPrimerLibraryIntroduction][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.

<img width="800" alt="Book Object Attribute Properties" src="http://wiki.itds.pt/pub/WebXEO/XeoPrimerObjectModellingLibrary/BookObjectAttribute.png" title="Book Object Attribute Properties" height="348" />

__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.<em><br /></em>

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

<img width="800" alt="Attribute Collection for LIB_Book" src="http://wiki.itds.pt/pub/WebXEO/XeoPrimerObjectModellingLibrary/BookObjectAttributeCollection.png" title="Attribute Collection for LIB_Book" height="403" />

__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<em><br /> </em> | Object<em><br /> </em> | Publisher<em><br /> </em> | The Book's Publisher<em><br /> </em> | N/A<em><br /> </em> | false<em><br /> </em> | LIB_Publisher<em><br /> </em> |
| 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 (<strong>L</strong>ist <strong>o</strong>f <strong>V</strong>alues) 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" -&gt; "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)

<img width="800" alt="Lov Editor" src="http://wiki.itds.pt/pub/WebXEO/XeoPrimerObjectModellingLibrary/LovEditor.png" title="Lov Editor" height="253" />

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

<img width="800" alt="Lov Editor State Attribute" src="http://wiki.itds.pt/pub/WebXEO/XeoPrimerObjectModellingLibrary/LovEditorStateAttribute.png" title="Lov Editor State Attribute" height="209" />

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

<img width="1025" alt="Choose Lov For Book State Attribute" src="http://wiki.itds.pt/pub/WebXEO/XeoPrimerObjectModellingLibrary/ChooseLovForBookStateAttribute.png" title="Choose Lov For Book State Attribute" height="512" />

__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 <strong>and </strong>username attribute in both Librarians and Library Users to add custom behavior later on.

<img width="960" alt="InterfaceImplementation.png" src="http://wiki.itds.pt/pub/WebXEO/XeoPrimerObjectModellingLibrary/InterfaceImplementation.png" title="InterfaceImplementation.png" height="720" />

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

<strong>LIB_Librarian</strong>( 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.

<img width="800" alt="Interface Implementation XEO Studio" src="http://wiki.itds.pt/pub/WebXEO/XeoPrimerObjectModellingLibrary/InterfaceImplementationXEOStudio.png" title="Interface Implementation XEO Studio" height="339" />

__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 [[WebXEO.XeoPrimerConcepts#orphanConcept][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).

<img width="527" alt="Non-Orphan Object Model" src="http://wiki.itds.pt/pub/WebXEO/XeoPrimerObjectModellingLibrary/ReturnNonOrphan.png" title="Non-Orphan Object Model.png" height="381" />

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

<strong>LIB_Message</strong>( 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.

<img width="800" alt="Message Object 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:

<strong>LIB_Librarian</strong>( 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):

<strong>LIB_Contact</strong>( 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:

<strong>LIB_PublisherNucleus</strong>( 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:

<strong>LIB_Publisher </strong>( 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. [[WebXEO.XeoPrimerObjectBehavior][Jump to the next chapter]] to know how to add behavior to the XEO Models.
Attachments
Topic attachments
I	Attachment	Action	Size	Date	Who	Comment
png	BookCategoryAttribute.png	manage	14.6 K	2010-12-17 - 16:36	PedroRio	BookCategory Attribute Name
png	BookCategoryGeneral.png	manage	17.4 K	2010-12-17 - 16:36	PedroRio	BookCategory General Properties
png	BookObjectAttribute.png	manage	29.5 K	2010-12-20 - 09:08	PedroRio	Book Object Attribute
png	BookObjectAttributeCollection.png	manage	28.2 K	2010-12-20 - 13:54	PedroRio	Attribute Object Collection
png	ChooseLovForBookStateAttribute.png	manage	21.9 K	2010-12-21 - 11:46	PedroRio
png	InterfaceImplementation.png	manage	33.9 K	2011-03-09 - 15:28	PedroRio
png	InterfaceImplementationXEOStudio.png	manage	29.0 K	2010-12-20 - 15:39	PedroRio	Interface Implementation XEO Studio
png	LovEditor.png	manage	12.3 K	2010-12-21 - 11:33	PedroRio
png	LovEditorStateAttribute.png	manage	12.1 K	2010-12-21 - 11:38	PedroRio	Lov Editor State Attribute
png	MessageObjectCollectionWithTypes.png	manage	23.6 K	2010-12-21 - 12:19	PedroRio
png	ReturnNonOrphan.png	manage	12.4 K	2010-12-21 - 09:54	PedroRio	Non-Orphan Wizard
Topic revision: r16 - 2011-04-04 - NicolauGrosskopf
No permission to view TWiki.WebTopBar
No permission to view TWiki.WebBottomBar