Object Identity Package

TARMS Inc.

September 07, 2000

TARMS Inc. http://www.tarms.com

Copyright c 2000 TARMS Inc.

Permission is hereby granted, free of charge, to any person obtaining acopy of this model and associated documentation files (the “Model”),to deal in the Model without restriction, including without limitationthe rights to use, copy, modify, merge, publish, distribute, sublicense,and/or sell copies of the Model, and to permit persons to whom theModel is furnished to do so, subject to the following conditions:

1. The origin of this model must not be misrepresented; you mustnot claim that you wrote the original model. If you use thisModel in a product, an acknowledgment in the productdocumentation would be appreciated but is not required.Similarly notification of this Model’s use in a product would beappreciated but is not required.

2. Altered source versions must be plainly marked as such, andmust not be misrepresented as being the original software.

3. This notice, including the above copyright notice shall beincluded in all copies or substantial portions of the Model.

THE MODEL IS PROVIDED “AS IS”, WITHOUT WARRANTY OFANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOTLIMITED TO THE WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE ANDNONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORSOR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTIONOF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUTOF OR IN CONNECTION WITH THE MODEL OR THE USE OROTHER DEALINGS IN THE MODEL.

Typeset in LATEX.

Contents

1 Use Cases 21.1 New Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Edit Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3 Get Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.4 Compute Delta . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 Interfaces 32.1 Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2.1.1 Relationships. . . . . . . . . . . . . . . . . . . . . . . . 42.1.2 Operations . . . . . . . . . . . . . . . . . . . . . . . . . 4

2.2 Frank . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42.2.1 Relationships. . . . . . . . . . . . . . . . . . . . . . . . 42.2.2 Operations . . . . . . . . . . . . . . . . . . . . . . . . . 4

2.3 Keyable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.3.1 Relationships. . . . . . . . . . . . . . . . . . . . . . . . 52.3.2 Operations . . . . . . . . . . . . . . . . . . . . . . . . . 5

2.4 Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.4.1 Relationships. . . . . . . . . . . . . . . . . . . . . . . . 62.4.2 Operations . . . . . . . . . . . . . . . . . . . . . . . . . 6

3 Architectural Service Interfaces 73.1 Depot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

3.1.1 Relationships. . . . . . . . . . . . . . . . . . . . . . . . 83.1.2 Operations . . . . . . . . . . . . . . . . . . . . . . . . . 8

4 Classes 94.1 DomainModel. . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

4.1.1 Relationships. . . . . . . . . . . . . . . . . . . . . . . . 94.1.2 Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . 94.1.3 Operations . . . . . . . . . . . . . . . . . . . . . . . . . 10

4.2 FrankModel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104.2.1 Relationships. . . . . . . . . . . . . . . . . . . . . . . . 104.2.2 Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . 104.2.3 Operations . . . . . . . . . . . . . . . . . . . . . . . . . 11

4.3 VersionModel. . . . . . . . . . . . . . . . . . . . . . . . . . . . 114.3.1 Relationships. . . . . . . . . . . . . . . . . . . . . . . . 114.3.2 Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . 114.3.3 Operations . . . . . . . . . . . . . . . . . . . . . . . . . 11

1

5 Architectural Services 125.1 DepotModel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

5.1.1 Relationships. . . . . . . . . . . . . . . . . . . . . . . . 13

6 Exceptions 136.1 OutOfOrderException. . . . . . . . . . . . . . . . . . . . . . . . 13

6.1.1 Operations . . . . . . . . . . . . . . . . . . . . . . . . . 13

7 Associations 137.1 performer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147.2 created. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147.3 modified. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147.4 store. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147.5 within . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157.6 depository. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

List of Figures

1 Class Diagram— Franking. . . . . . . . . . . . . . . . . . . . . 162 Class Diagram— Keying and Storage. . . . . . . . . . . . . . . 173 Class Diagram— Examples. . . . . . . . . . . . . . . . . . . . . 18

List of Tables

1 Object Identity— Associations. . . . . . . . . . . . . . . . . . . 131 . . . continued. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Package Description

The object identity package contains the basic models for deciding whether twoobjects refer to the same business object.

As objects are modified, they have a number of versions. Each version containsinformation as to when the version was created, by whom and for what purpose.Versioning allows an audit trail to be followed for the object, as each version canbe saved individually to persistent storage.

2

1 Use Cases

1.1 New Object

From an initial object, create a new family of objects with a unique key and aninitial version number.

For example: create a new deal object, ready for editing. Once the object hasbeen accepted, assign it a new deal number (key) from a central pool of keys and aversion number of 1.

1.2 Edit Object

To edit a versioned object, make a copy of the object and modify the copy. Whenthe modifications are complete, the copy is turned into the current version, with anew version number.

1.3 Get Object

Get the current version of an object, identified by its key.

1.4 Compute Delta

Get the current version of an object, identified by the object key and the previousversion to the current version. Compute the differences between the two versionsand return the delta.

2 Interfaces

2.1 Domain

Domains represent the business structure of an organization. An organization isassumed to have a number of semi-independent databases. Each database is locatedin a separate domain. Ownership, update and modification rights to an object areassigned to a single domain.

Domains have a hierarchical structure, reflecting the large-scale structure of theorganization. For example, the Singapore business unit domain is contained withinthe Asia-Pacific region domain which, in turn, is contained within the Global do-main.

3

2.1.1 Relationships

Class Description Notes* Comparable" Comparable# DomainModel §4.1*:Inherits ":Realizes#:Realized by

2.1.2 Operations

String domainId() domainId

The domain name. Return a unique identifier for the domain.

Domain parent() parent

The parent domain. Return the parent domain of this domain, or nil if this hasno parent.

Boolean equals(Comparable arg) equals

arg: Comparable The object to compare this object against.The equality relationship. Two domains are equal if their domain identifiers

are equal.

2.2 Frank

When a versioned object is created or modified, it needs to be franked with infor-mation on the details of who made the change and when the change occurred. AFrank groups this information together.

2.2.1 Relationships

Class Description Notes# FrankModel §4.2#:Realized by

2.2.2 Operations

Responsible performedBy() performedBy

4

The party which made the change. Return the party responsible for the creationof the Frank.

Datestamp performedOn() performedOn

Processing date of change. Returns the processing date on which this changewas made. Note that the processing date may not be the same as the actual date.

Timestamp performedAt() performedAt

Time of change. Returns the date and time at which the change occurred.

String action() action

The action that created this Frank. Returns a string description of the changeperformed.

2.3 Keyable

Keyable objects have a unique key that can be used to retrieve an object from aDepot §3.1or to see whether two objects refer to the same logical object or familyof objects.

Each keyable object is associated with a Domain §2.1 that acts as an authorityfor the object’s key. Domains allow key spaces to be partitioned.

2.3.1 Relationships

Class Description Notes* PartiallyOrdered+ Version §2.4*:Inherits+:Inherited by

2.3.2 Operations

Domain domain() domain

Domain of the supplied key. Returns the domain that this key was issued under.

Integer key() key

The object key. Returns the integer that, within the domain that supplied thekey, uniquely identifies that object or versioned family.

5

Boolean equals(Comparable arg) equals

arg: Comparable The object to compare this object against.The equality relationship. Two Keyables are equal if their domains and keys

are equal.

Boolean lessThanOrEqualTo(PartiallyOrdered arg) lessThanOrE-qualToarg: PartiallyOrdered The object to compare this object against.

The less than or equal to relationship. Keyables from different domains are notorderable. Within a single domain, Keyables are ordered by identifier number.

2.4 Version

A Version represents a group of objects, each representing a sequence of versionsof that object. An example is a deal, with each deal modification creating a newversion.

2.4.1 Relationships

Class Description Notes* Keyable §2.3# VersionModel §4.3$ DepotModel §5.1 store �

*:Inherits #:Realized by $:Association !:Navigable�:Aggregate�:Composite

2.4.2 Operations

Integer versionNumber() versionNumber

Version number. Returns the version number associated with this object.

Version predecessor() predecessor

Previous version to this version. Returns the previous version to this version,or nil if this is the first version.

Version successor() successor

Next version to this version. Returns the next version to this version, or nil ifthis is the most recent version.

Boolean isCurrent() isCurrent

6

Current version? Returns true if this is the current version of the object. Thecurrent version is the version with the largest version number.

Frank created() created

Creation frank. Returns the Frank for the first version of this family of objects.

Frank modified() modified

Modification frank. Returns the Frank associated with the creation of this ver-sion of the family of objects. If this is the first version, then this frank is the sameas the creation frank.

Boolean equals(Comparable arg) equals

arg: Comparable The object to compare this object against.The equality relationship. Two Versions are equal if their domains, keys and

version numbers are equal.

Boolean lessThanOrEqualTo(PartiallyOrdered arg) lessThanOrE-qualToarg: PartiallyOrdered The object to compare this object against.

The less than or equal to relationship. Versions from different domains are notorderable. Within a single domain,Versions are ordered by key and then by versionnumber.

3 Architectural Service Interfaces

3.1 Depot

A Depot object is one that maintains a cache of versionable objects so that the latestversion of that object can be returned.

Depots implicitly act as an intermediary between whatever persistent storescheme is used and the object model. Requests to the cache can cascade as re-quests to persistent store, updates to the cache can be written through to the store.The exact implementation of Depots (and their subclasses) is dependent upon theunderlying architecture of the system. This specification provides the Depot inter-face from the point of view of objects within theelements object model; a placewhere objects can be stored and retrieved.

7

3.1.1 Relationships

Class Description Notes# DepotModel §5.1$ VersionModel §4.3 depository#:Realized by $:Association !:Navigable�:Aggregate�:Composite

3.1.2 Operations

Version currentVersion(Keyable key) currentVersion

key: Keyable The key associated with this versioned family of objects.Raises:NotFoundException

Current version of an object. Returns the most current version of the objectwith this key. A NotFoundException is raised if the key can not be found.

Version previousVersion(Keyable key) previousVersion

key: Keyable The key of the object in cache.Raises:NotFoundException

Pre-current version of object. Returns the version previous to the most currentversion of the object keyed by key. A NotFoundException is raised if there is nosuch version.

Version nextVersion(Keyable key) nextVersion

key: Keyable The key of the object in cache.New version of object. Returns the object that would be the next version to the

most current version of the object. A copy of the current version of the object isreturned, with the version number updated.

initializeFamily(Version unversioned) initializeFamily

unversioned: Version The object to which a new version should be as-signed.

Create a new version family. Get a new version with a new unique key for thecurrent domain and a suitable initial version number and assign it to unversioned.

add(Version newVersion, String action, Responsible performer) add

newVersion: VersionThe new version to add to the cache.action: String The action that has caused the new version to be created orupdated.performer: ResponsibleThe party responsible for the update.Raises:OutOfOrderException

8

Add a new version to the depot. Adds a new version of the object to the depot.This object is associated with an updated frank containing the performer, action,the current processing date and now timestamp. If this is the first version of thisobject, then the object is associated with a created frank identical to the updatedfrank.

An OutOfOrderException is raised if the newVersion has an earlier versionthan the current version.

Reportable validate() validate

Validate the depot.A depot is valid if: for each object with a common identifier held by the depot,

the only object which returns true to isCurrent() is the object with the maximumversion number.

4 Classes

4.1 DomainModel

The DomainModel class provides a concrete implementation of the Domain inter-face. Domains can be viewed as dot-separated strings, with the leftmost domain in-dicating the most general domain1. For example RoboBank.Asia.Singapore refersto the Singapore office of the Asia region of the RoboBank organization.

4.1.1 Relationships

Class Description Notes" Domain §2.1" Validatable$ VersionModel §4.3 within 0..n":Realizes $:Association !:Navigable�:Aggregate�:Composite

4.1.2 Attributes

domainId: String A string giving the domain identifier. A valid domain attributeis a string which matches the following regular expression:

1Domains are similar in structure to Rendezvous[1] subjects.

9

[A-Za-z_][A-Za-z0-9_]*(.[A-Za-z_][A-Za-z0-9_]*)*

4.1.3 Operations

Domain parent() parent

The parent domain. The parent domain is computed by removing the rightmoststring matching the regular expression .[A-Za-z_][A-Za-z0-9_]* from the domainattribute and constructing a new domain with the reduced attribute.

If there is no string that can be removed (ie. we are at a top-level domain) thennil is returned.

Reportable validate() validate

Validate the domain. A domain is valid if the domain attribute matches theregular expression given in the domainId attribute documentation.

4.2 FrankModel

The FrankModel class is a concrete implementation of the Frank interface.

4.2.1 Relationships

Class Description Notes" Frank §2.2" Validatable$ Responsible performer 1..1 !

$ VersionModel §4.3 created 1..n$ VersionModel §4.3 modified 1..1":Realizes $:Association !:Navigable�:Aggregate�:Composite

4.2.2 Attributes

action: String The action that caused this frank to come into being.

performedOn: Datestamp = Datestamp.currentProcessingDate()The process-ing date on which the object was created or modified.

performedAt: Timestamp = Timestamp.now() The date and time at which thefranked object was created or updated.

10

4.2.3 Operations

Responsible performedBy() performedBy

The party responsible for the update. Return the associated performer.

Reportable validate() validate

Validate the object. A FrankModel is valid if all of the action, dates and timesand performer are available. If the time the update was performed at comes beforethe date the update was performed on, then a warning should be issued.

4.3 VersionModel

A VersionModel is a concrete implementation of the Version interface.Any class that uses versions should hold a VersionModel attribute. The class

should also implement the Version interface itself, with the methods simply passingthrough to the attribute.

4.3.1 Relationships

Class Description Notes" Version §2.4" Validatable$ FrankModel §4.2 created 1..1 !

$ FrankModel §4.2 modified 1..1 !

$ DomainModel §4.1 within 1..1 !

$ Depot §3.1 depository !

":Realizes $:Association !:Navigable�:Aggregate�:Composite

4.3.2 Attributes

key: Integer The key for the object family.

versionNumber: Integer The version number for this object.

4.3.3 Operations

Version predecessor() predecessor

Previous version to this version. Get the previous version of this object fromthe associated depot.

11

Version successor() successor

Next version to this version. Get the successor of this version from the associ-ated depot.

Boolean isCurrent() isCurrent

Current version? Return true if the associated depot returns this object as thecurrent version of this object family.

Frank created() created

Creation frank. Return the associated creation Frank.

Frank modified() modified

Modification frank. Return the associated modified Frank.

Domain domain() domain

Domain of identification. Return the associated domain that this object iswithin.

Reportable validate() validate

Check for for a valid object. A VersionModel is valid if the creation processingdate and timestamp are the same as or earlier than the modification processing dateand timestamp.

5 Architectural Services

5.1 DepotModel

The DepotModel class is an implementation of the Depot interface and providesbasic caching services for objects that use the Version §2.4 interface. The Versionobjects accessed by the cache are the actual objects that the version is attached to,rather than the versions themselves.

The exact implementation of the operations defined in Depot is a functionof the underlying architecture of the system — something not addressed by theelements object model. As a result, no semantics have been defined for theDepot operations.

12

5.1.1 Relationships

Class Description Notes" Depot §3.1$ Version §2.4 store !

":Realizes $:Association !:Navigable�:Aggregate�:Composite

6 Exceptions

6.1 OutOfOrderException

An exception raised when a versioned object appears to have an incorrect version.

6.1.1 Operations

Version updatingVersion() updatingVersion

Version attempting an update. Returns the object that was being presented asthe newest version.

Version existingVersion() existingVersion

The existing version which the updating version clashes with. Returns the ex-isting version that is on or after the updating version.

7 Associations

Table 1: Object Identity— Associations

AssociationRole Class Card. Notes

performerperformer Responsible 1..1 !

frank FrankModel §4.2 0..ncreated

creator FrankModel §4.2 1..1 !

version VersionModel §4.3 1..nmodified

modifier FrankModel §4.2 1..1 !

13

Table 1: . . . continued

AssociationRole Class Card. Notesversion VersionModel §4.3 1..1

storedepositor Version §2.4 !

depot DepotModel §5.1 �

withindomain DomainModel §4.1 1..1 !

version VersionModel §4.3 0..ndepository

depot Depot §3.1 !

depositor VersionModel §4.3!:Navigable�:Aggregate�:Composite

7.1 performer

Role: performer NavigableResponsible, 1..1.Role: frank FrankModel, 0..n.

The party responsible for the change.

7.2 created

Role: creator NavigableFrankModel, 1..1.Role: version VersionModel, 1..n.

The creation action for this family of objects.

7.3 modified

Role: modifier NavigableFrankModel, 1..1.Role: version VersionModel, 1..1.

The modification frank for this version of the object family.

7.4 store

Role: depositor NavigableVersion.Role: depot AggregateDepotModel.

The objects that make up the depot.

14

7.5 within

Role: domain NavigableDomainModel, 1..1.Role: version VersionModel, 0..n.

The domain that was the authority for the identifier for this version.

7.6 depository

Role: depot NavigableDepot.Role: depositor VersionModel.

The depot that holds these objects.

15

Co

mp

ara

ble

(fro

m U

tilit

ies

)

<<I

nter

face

>>

Fra

nk

pe

rfo

rme

dB

y()

pe

rfo

rme

dO

n()

pe

rfo

rme

dA

t()

act

ion(

)

<<I

nter

face

>>

Va

lida

tab

le

(fro

m U

tilit

ies

)

Re

spo

nsi

ble

(fro

m U

tilit

ies

)

<<I

nter

face

>>

Fra

nkM

odel

act

ion

: Str

ing

pe

rfo

rme

dO

n : D

ate

sta

mp

= D

ate

sta

mp

.cur

rent

Pro

cess

ing

Da

te()

pe

rfo

rme

dA

t : T

ime

sta

mp

= T

ime

sta

mp

.no

w()

pe

rfo

rme

dB

y()

valid

ate

()

1..1

0..*

1..1

0..*

pe

rfo

rme

r

Figure 1: Class Diagram— Franking

16

Pa

rtia

llyO

rde

red

(fro

m U

tiliti

es)

<<

Inte

rfa

ce

>>

Do

ma

in

do

ma

inId

()p

are

nt(

)e

qu

als

()

<<

Inte

rfa

ce

>>

Ke

yab

le

do

ma

in()

ke

y()

eq

ua

ls()

les

sT

ha

nO

rEq

ua

lTo

()

<<

Inte

rfa

ce

>>

Va

lida

tab

le

(fro

m U

tilit

ies

)

Va

lida

tab

le

(fro

m U

tilit

ies

)

Co

mp

ara

ble

(fro

m U

tilit

ies

)

<<

Inte

rfa

ce

>>

Ve

rsio

n

vers

ion

Nu

mb

er(

)p

red

ec

es

so

r()

su

cc

es

so

r()

isC

urr

en

t()

cre

ate

d()

mo

dif

ied

()e

qu

als

()le

ss

Th

an

OrE

qu

alT

o()

<<

Inte

rfa

ce

>>

De

po

tMo

de

l<

<A

rch

ite

ctu

ral S

erv

ice

>>

sto

re

Fra

nk

Mo

de

l

Fra

nk

Mo

de

l

Do

ma

inM

od

el

do

ma

inId

: S

trin

g

pa

ren

t()

valid

ate

()

De

po

t

cu

rre

ntV

ers

ion

()p

revi

ous

Ve

rsio

n()

ne

xtV

ers

ion

()in

itia

lize

Fa

mily

()a

dd

()va

lida

te()

<<

Arc

hit

ec

tura

l Se

rvic

e In

terf

ac

e>

>

Ve

rsio

nM

od

el

ke

y :

Inte

ge

rve

rsio

nN

um

be

r :

Inte

ge

r

pre

de

ce

ss

or(

)s

uc

ce

ss

or(

)is

Cu

rre

nt(

)c

rea

ted

()m

od

ifie

d()

do

ma

in()

valid

ate

()

1..

11

..*

1..

11

..*

cre

ate

d

1..

1

1..

1

1..

1

1..

1m

od

ifie

d

1..

10

..*

1..

10

..*

with

in

depo

sito

ry

Figure 2: Class Diagram— Keying and Storage

17

Ne w Ob je ct

Edit Object

Get Ob je ct

C ompute D elta

Figure

3:C

lassD

iagram—

Exam

ples

18

References

[1] TIB/Rendezvous.http://www.rv.tibco.com/index.html.

19