FamilyWall API

h1. Object Model (general)

This wiki page documents general principle about the Object Model of the application, such as account, owner, author, etc...

h2. Owner and owned objects

h3. OWNERS

Objects in the database may be either 'owner' or 'owned' objects.

_OWNER_ objects are main objects of the application that can be retrived directly from the database using their ID or another identifier. 

They are like-entry points in the database. There are two owners objects at the moment in the application:

* Accounts

* Families

>

> Owner objects are main entry points of the database. That means in case of database horizontal partitioning, two owners may be located on different databases.

>

> *OwnerId are LONG which are unique across all kind of owners*

>

h3. OWNED

Other objects are owner by accounts or families. For instance: 

* messages, 

* contact, 

* events, 

* profile, 

* setting, 

* location, etc...

>

> That means that you cannot retrieve directly a message from the application, you must have his OWNER before, and any database access to a specific message will be 

 done in the context of his owner. Typically it is entirely possible that messages with a different owners could be stored in different databases.

>

h3. Kind of Owned objects

There are several kind of owned objects:

* Owned by accounts and public: owned by account and any accounts belonging to the same family (or other groups) can access those objects (IModelObject).

* Owned by accounts and private: owned by account and only the owner can access the object.

* Owned by family: any account of the family can access this object.

h3. MetaId

Ids of object are expressed as a string and shall be considered as OPAQUE by any client. 

However in many cases such ids are MetaId and the syntax of such ids are

<pre> <ObjectType>/<OwnerId>_<ObjectId>_<SubId>  </pre>

* ObjectType define the type of objects such as account, contact, etc...

* OwnerId is a long being the internal id of the owner. Any one type of object can only have one type of owner so the Id is unambiguous.

* ObjectId is a long internal id of the object. In case of a owner, it is not present.

* SubId is an optional information.

* accountId is simply represented by a long, there is no ObjectType/

For instance: 

* thread/282_16766 is a message thread of id=16766 which belong to the family 282 (the fact that this is a family and not an account is bound by the nature of thread)

* place/282_3522 is a place of id=3522 which belong to the family 282 (idem)

* event/282_4725_2012 is an event of id=4725 which belong to the family 282 (idem) and the subId=2012 indicate that this is the recurence of year=2012 for a bday.

* 123 is the id of the account 123

* family/63 is the id of the family 63

h2. AUTHOR

* _AUTHOR_ is representing who has created the object. It has specifically much sense for object owned by the family such as Events or Contacts.

It is represented in the database and in the JSON by the attribute *accountId*

h2. Special cases of messages

Message management is a little bit strange in regard to those aspects (owner, author), so they are specifically explained here:

# Messages are _Owned by accounts and private_ : that means that you can only see your messages

# When somebody send a message, *two objects* are created: one message for the sender (in the sent-box) and one for the recipient.

# The message for the sender is owned by the sender so he can see it in his view of the message thread.

# The message for the recipiend is owned by the recipiend so he can see it in his view of the message thread.

>

> This enables to have a email-like behavior: if the sender is deleting a thread of messages, the recipient's thread is left unchanged. Same for read/unread flag

>