Serialization and Persistence in CogTool

grapedraughtSoftware and s/w Development

Dec 2, 2013 (3 years and 9 months ago)

91 views

© 2006 CogTool, HCII, CMU

1

12/2/2013


Serialization

and Persistence in CogTool


Introduction


CogTool uses custom
-
built object serialization to support project persistence and
cut/copy/paste using the standard system clipboard.


The result of a serialization is a string in XML format.

The roo
t XML element
(
<per
sist ...> ...

</persist>
)
contains a sequence of CogTool elements
.
When used for adding CogTool model objects to the clipboard, the sequence represents
the set of objects cut or copied.

When used for persistence, the sequence contains
a
single element representing the CogTool project.


When used for persistence, the XML

string is stored in a file named “PERSIST”, which
is
stored

in

a
standard zip format archive
file. This file is given a “.cgt” extension so
that
the operating system ca
n know that the CogTool application is associated with such files.


Said another way, a stored CogTool project resides in a file with a “.cgt” extension. This
file is actually a standard zip archive with one file in it named “PERSIST”. This file is in
XM
L format.


The rest of this documentation addresses the CogTool XML in more detail. Then, it
presents how programmers use the provided serialization and data evolution mechanisms.


XML

Serialization

DTD


As stated earlier, the root XML element must be:


<
persist ...> ...

</persist>


The attributes for the
persist

XML element are as follows:




version
: the version of the DTD being used



cogtool_version
: the version of the CogTool application that created the
serialization



cogtool_revision
: the last Trac chang
elist used to build the CogTool
application that created the serialization



cogtool_buildtime
: the date/time when the CogTool application that
created the serialization

was built



java_version
: the version of Java used to compile the CogTool application
that

created the serialization



os_name
: the operating system on which the CogTool application that created
the serialization was compiled



Serialization and Persistence in CogTool

© 2006 CogTool, HCII, CMU

2

12/2/2013



os_version
: the version of the operating on which the CogTool application
that created the serialization was compiled


Exa
mple:



<persist version="2"



cogtool_version="1.0b14"



cogtool_revision="1157"



cogtool_buildtime="03/23/2006
-
01:53"



java_version="1.4.2_03"



os_name="Windows 2000"



os_version="5.0">


...


</persist>

CogTool Elements


Also, as noted above, a seque
nce of CogTool elements is nested within the outermost
persist

element.
Each
nested
element
is one of the following:




obj
: This element represents an instance of a programmer
-
defined class. Nested
elements

consist of zero or more “superclass” elements (d
escribed below)
followed by zero or more CogTool elements (i.e., elements being described in this
section
)
.


Attributes

for the
obj

element include:

o

var
: The value of this optional attribute specifies the instance variable for
which this object is the valu
e. This attribute must be specified if this
element is directly nested within another
obj

element. It should not be
specified if this element is a top
-
level CogTool element or part of an
aggregate CogTool element (i.e.,
arr
,
map
, or
elts
).

o

id
:

The value
of this required attribute is a unique integer (that is, unique
across all other
id

attribute values in the serialization). The integer value
may be used to identify later references to this same object value (that is,
if there are multiple references to
this object
; see the
ref

element
).

o

class
:

The value of this required attribute is the Java name of the actual
class of this element’s value.

o

version
:

The value of this required attribute is the version of the
persistence format used for this object’s class

when the serialization was
created. Effectively, the version reflects what information was stored in
the serialization.


Top
-
level example:


<obj id="1"


class="edu.cmu
.cs.hcii.cogtool.model.Project"


version="0">
...
</obj>



Serialization and Persistence in CogTool

© 2006 CogTool, HCII, CMU

3

12/2/2013

Instance
-
variable example:


<o
bj var="origin"


id="11"


class="edu.cmu.cs.hcii.cogtool.model.DoublePoint"


version="0">


<dbl var="x" val="16.0"/>


<dbl var="y" val="16.0"/>

</obj>




ref
:

This element represents a reference to an object instance
(see elements
obj
,
byte
,
arr
,
map
, and
elts
)
that was specified earlier in the serialization. This
element may not have any nested elements.


Attributes for the
ref

element include:

o

var
: The value of this optional attribute specifies the instance variable for
which this object is the value. T
his attribute must be specified if this
element is directly nested within an
obj

element. It should not be
specified if this element is a top
-
level CogTool element or part of an
aggregate CogTool element (i.e.,
arr
,
map
, or
elts
).

o

id
ref
: The value of this

required attribute is
an

integer given as the
value of the id attribute for an object specified earlier in the serialization.


Top
-
level example:


<ref idref="19"/>


Instance
-
variable example:


<ref var="design" idref="3"/>




null
:

This element represents
a null object reference, for any type of object
(including
String
; see below
). This element may not have any nested elements.


Attributes for the
null

element include:

o

var
: The value of this optional attribute specifies the instance variable for
which
nul
l

is the value. This attribute must be specified if this element
is directly nested within another
obj

element. It should not be specified
if this element is a top
-
level CogTool element or part of an aggregate
CogTool element (i.e.,
arr
,
map
, or
elts
).


Top
-
level example:


<
null
/>


Instance
-
variable example:


<
null

var="
background
"/>



Serialization and Persistence in CogTool

© 2006 CogTool, HCII, CMU

4

12/2/2013




int
:

This element represents an integer value. Both normal Java
int

values and
Integer

values are represented using this XML element. If the context expects
a true object
value,
an

Integer

instance

is
constructed when the serialization is
reconstituted.
Technically, although Java
Integer

values may be shared, this
serialization does not assign
id

attributes. Good programming practice dictates
the use of
.equals()

when com
paring
Integer

objects.
This element may
not have any nested elements.


Attributes for the
int

element include:

o

var
: The value of this optional attribute specifies the instance variable for
which this integer is the value. This attribute must be specifie
d if this
element is directly nested within an
obj

element. It should not be
specified if this element is a top
-
level CogTool element or part of an
aggregate CogTool element (i.e.,
arr
,
map
, or
elts
).

o

val
: The value of this required attribute is an intege
r
constant understood
by
Integer.parseInt

that
repre
sents

the integer value being stored.


Top
-
level example:


<int val
="19
18
"/>


Instance
-
variable example:


<int

var="
widgetColor
"
val="

16744448
"/>




dbl
: This element represents a double
floating point
val
ue. Both normal Java
double

values and
Double

values are represented using this XML element. If
the context
expects a true object value, a

Double

instance

is
constructed when
the serialization is reconstituted.
Technically, although Java
Double

values m
ay
be shared, this serialization does not assign
id

attributes. Good programming
practice dictates the use of
.equals()

when comparing
Double

objects.
This
element may not have any nested elements.


Attributes for the
dbl

element include:

o

var
: The value
of this optional attribute specifies the instance variable for
which this double is the value. This attribute must be specified if this
element is directly nested within an
obj

element. It should not be
specified if this element is a top
-
level CogTool el
ement or part of an
aggregate CogTool element (i.e.,
arr
,
map
, or
elts
).

o

val
: The value of this required attribute is a floating point constant
understood by
Double.parseDouble

that represents the double value
being stored.





Serialization and Persistence in CogTool

© 2006 CogTool, HCII, CMU

5

12/2/2013

Top
-
level example:


<dbl val
="
3.14159
"/>


Instance
-
variable example:


<dbl

var="
xCoord
"
val="
16
.0
"/>




bool
: This element represents a Boolean value. Both normal Java
boolean

values and
Boolean

values are represented using this XML element. If the
context exp
ects an actual object valu
e, a

Boolean

inst
ance is
constructed when
the serialization is reconstituted.
Technically, although Java
Boolean

values
may be shared, this serialization does not assign
id

attributes. Good
programming practice dictates the use of
.equals()

when comparin
g
Boolean

objects.
This element may not have any nested elements.


Attributes for the
bool

element include:

o

var
: The value of this optional attribute specifies the instance variable for
which this Boolean is the value. This attribute must be specified if

this
element is directly nested within an
obj

element. It should not be
specified if this element is a top
-
level CogTool element or part of an
aggregate CogTool element (i.e.,
arr
,
map
, or
elts
).

o

val
: The value of this required attribute is either the le
tter ‘t’,
representing the Boolean value
true
, or ‘f’, representing the Boolean
value
false
.


Top
-
level example:


<bool val
="
t
"/>


Instance
-
variable example:


<bool

var="
handStartsOnMouse
"
val="
f
"/>




str
: This XML element represents a Java
String

value.
T
echnically, a
lthough
Java strings may be shared, this serialization does not assign
id

attributes
. Good
programming practice dictates the use of
.equals()

when comparing strings.
This element may not have any nested elements
, but should contain text (whi
ch
could be a
<![CDATA[
...

]]>

section)
that

represents the
String

value
.

T
he CogTool serializing mechanism always uses a
CDATA

section
.


B
ecause the SAX parser
used by CogTool’s implementation
to read serialized
data has a bug,
the element’s text

must h
ave

one extra character at the end (not a
‘]’; the CogTool code uses an ‘@’).

[
For those who care, the SAX parser
generates a parse error if the last character in the
CDATA

section is a ‘]’ because


Serialization and Persistence in CogTool

© 2006 CogTool, HCII, CMU

6

12/2/2013

it doesn’t see
a ‘
>’
after two

‘]]’

(i.e.,

it ends as ‘]]]
>’
)
.
]


Attributes for the
str

element include:

o

var
: The value of this optional attribute specifies the instance variable for
which this
string

is the value. This attribute must be specified if this
element is directly nested within an
obj

element. It sho
uld not be
specified if this element is a top
-
level CogTool element or part of an
aggregate CogTool element (i.e.,
arr
,
map
, or
elts
).

o

size
: The value of this required attribute is
an integer constant reflecting
the length of the serialized string value

(i
.e.,
not

including the extra
character at the end of the text)
.


Top
-
level example:


<str size="34">


<![CDATA[Time

0.050: Module :VIS
ION running
@]]>

</str>


Instance
-
variable example:


<str var="name" size="7"><![CDATA[Frame 1@]]></str>




char
:
This elemen
t represents a character value. Both normal Java
char

values
and
Character

values are represented using this XML element. If the context
expects a true object value, a

Character

instance is constructed when the
serialization is reconstituted.
Technicall
y, although Java
Character

values
may be shared, this serialization does not assign
id

attributes. Good
programming practice dictates the use of
.equals()

when comparing
Character

objects.
This element may not have any nested elements, but
should contain

text (which could be a
<![CDATA[
...

]]>

section) that
represents the character

value.

The CogTool serializing mechanism always uses a
CDATA

section.


Because the SAX parser used by CogTool’s implementation to read serialized
data has a bug, the element’
s text must have one extra character (not a ‘]’; the
CogTool code uses an ‘@’).

Thus, the text must contain two character values.

[
For those who care, the SAX parser generates a parse error if the last character
in the
CDATA

section is a ‘]’ because it d
oesn’t see a ‘>’ after two ‘]]’ (i.e., it
ends as ‘]]]>’).
]


Attributes for the
cha
r

element include:

o

var
: The value of this optional attribute specifies the instance variable for
which this
character

is the value. This attribute must be specified if this

element is directly nested within an
obj

element. It should not be
specified if this element is a top
-
level CogTool element or part of an
aggregate CogTool element (i.e.,
arr
,
map
, or
elts
).



Serialization and Persistence in CogTool

© 2006 CogTool, HCII, CMU

7

12/2/2013


Top
-
level example:


<char
><![CDATA[T
@]]>
</cha
r>


Instance
-
vari
able example:


<cha
r var="
separator
"><![CDATA[
,@]]></cha
r>




byte
:

This element represents a Java
byte
[]

array. This is valuable

because
CogTool represents images as a Java
byte
[]

array, depending on the SWT
image classes to determine the actual encoding (
e.g., JPEG vs. GIF)

from the
header information generally kept in the first bytes of the array
.

This element may
not have any nested elements, but should contain text (which could be a
<![CDATA[

...

]]>

section)
representing

the Bas
e64
-
encoding of the byte
s
.

(Because ‘]’ is never part of a Base64 encoding, no extra characters are needed.)


Attributes for the
byte

element include:

o

var
: The value of this optional attribute specifies the instance variable for
which this
byte

array is the value. This attribut
e must be specified if this
element is directly nested within an
obj

element. It should not be
specified if this element is a top
-
level CogTool element or part of an
aggregate CogTool element (i.e.,
arr
,
map
, or
elts
).

o

size
: The value of this required att
ribute is an integer constant reflecting
the length of the serialized Base64
-
encoded string.

o

id
: The value of this required attribute is a unique integer (that is, unique
across all other
id

attribute values in the serialization). The integer value
may be

used to identify later references to this same object value (that is,
if there are multiple references to this object
; see the
ref

element
).


Top
-
level example:


<
byte

id
="34"

size="4186"
>


<![CDATA[
. . .
]]>

</byte
>


Instance
-
variable example:


<byte name
="backgroundImage" id="34" size="4186">


<![CDATA[. . .
]]>

</byte
>




arr
: This element represents an arbitrary Java array. Nested elements consist of
zero or more CogTool elements (i.e., elements described in this section).
(Actually, the number of nested
elements is specified as an attribute.)





Serialization and Persistence in CogTool

© 2006 CogTool, HCII, CMU

8

12/2/2013

Attributes for the
arr

element include:

o

var
: The value of this optional attribute specifies the instance variable for
which this object is the value. This attribute must be specified if this
element is directly ne
sted within an
obj

element. It should not be
specified if this element is a top
-
level CogTool element or part of an
aggregate CogTool element (i.e.,
elts
,
map
, or

another

arr
).

o

id
: The value of this required attribute is a unique integer (that is, unique
across all other
id

attribute values in the serialization). The integer value
may be used to identify later references to this same object value (that is,
if there are multiple references to this object
; see the
ref

element
).

o

class
: The value of this requ
ired attribute is the Java name of the actual
class of this element’s value
’s component type (see the Java reflection
method
getComponentType()
)
.

o

size
: The value of this required attribute is an integer constant reflecting
the
number of components in the s
erialized array value
.


Top
-
level example:


<arr id="451" size="3" class="int">


<int val
="19
18
"/>


<int val
="
7538
"/>


<int val="
9
1
"/>

</arr
>


Instance
-
variable example:


<arr id="341"


size="2"


class="edu
.cmu
.cs.hcii.cogtool.model.IScriptStep"


var="s
criptSteps">


<obj id="642"



class="edu
.cmu
.cs.hcii.cogtool.model.ScriptStep"



version="0">. . .</obj>


<obj id="643"



class="edu
.cmu
.cs.hcii.cogtool.model.ScriptStep"



version="0">. . .</obj>

</arr
>




elts
: This element represents instances of
Co
llection

subclasses. Nested
elements consist of zero or more CogTool elements (i.e., elements described in
this section). (Actually, the number of nested elements is specified as an
attribute.)


Attributes for the
elts

element include:

o

var
: The value of t
his optional attribute specifies the instance variable for
which this object is the value. This attribute must be specified if this
element is directly nested within an
obj

element. It should not be
specified if this element is a top
-
level CogTool elemen
t or part of an
aggregate CogTool element (i.e.,
arr
,
map
, or another
elts
).



Serialization and Persistence in CogTool

© 2006 CogTool, HCII, CMU

9

12/2/2013

o

id
: The value of this required attribute is a unique integer (that is, unique
across all other
id

attribute values in the serialization). The integer value
may be used to identif
y later references to this same object value (that is,
if there are multiple references to this object
; see the
ref

element
).

o

size
: The value of this required attribute is an integer constant reflecting
the number of components in the serialized
Collection

value.


Top
-
level example:


<elts id="451" size="6">


<int val
="19
18
"/>


<int val
="
7538
"/>


<int val="
9
1
"/>


<int val="18
"/>


<int val
="
7
"/>


<int val="
9
1
"/>

</elts
>


Instance
-
variable example:


<elts name="scriptSteps" id="341" size="2">


<obj id=
"642"



class="edu
.cmu
.cs.hcii.cogtool.model.ScriptStep"



version="0">. . .</obj>


<obj id="643"



class="edu
.cmu
.cs.hcii.cogtool.model.ScriptStep"



version="0">. . .</obj>

</elts
>




map
:

This element represents instances of
Map

subclasses. Nested elem
ents
consist of zero or more element pairs; each pair consists of one
key

element
(described below) and one CogTool element (i.e., an element described in this
section). (Actually, the number of nested element pairs is specified as an
attribute.)


Attribut
es for the
map

element include:

o

var
: The value of this optional attribute specifies the instance variable for
which this object is the value. This attribute must be specified if this
element is directly nested within an
obj

element. It should not be
spec
ified if this element is a top
-
level CogTool element or part of an
aggregate CogTool element (i.e.,
arr
,
elts
, or another
map
).

o

id
: The value of this required attribute is a unique integer (that is, unique
across all other
id

attribute values in the serial
ization). The integer value
may be used to identify later references to this same object value (that is,
if there are multiple references to this object
; see the
ref

element
).

o

size
: The value of this required attribute is an integer constant reflecting
th
e number of components in the serialized
Map

value.




Serialization and Persistence in CogTool

© 2006 CogTool, HCII, CMU

10

12/2/2013

Top
-
level example:


<map id="451" size="3">


<key><int val="12"/></key>
<int val
="19
18
"/>


<key><int val="21"/></key>
<int val
="
7538
"/>


<key><int val="124"/></key>
<int val="
9
1
"/>

</map
>


Instance
-
varia
ble example:


<map var="results" id="124" size="2">


<key>


<obj id="19"


class="edu.cmu.cs.hci
i.cogtool.model.StandaloneAlgo"


version="0">
</obj>


</key>


<obj id="642"



class="edu
.cmu
.cs.hcii.cogtool.model.StandardResult"



version
="0">. . .</obj>


<key>


<ref idref="19"/>


</key>


<obj id="643"



class="edu
.cmu
.cs.hcii.cogtool.model.StandardResult"



version="0">. . .</obj>

</map
>




enum
:

This element represents instances of enumerated types. CogTool is
currently implemented

using Java 1.4.2, not Java 1.5, so enumerated type values
are instances of subclasses

of
PersistentEnum

(soon to be
XXX

when the
remaining traces of Hibernate are removed). Basically, an enumerated value is a
constant value; each has an associated unique

“persistence” value


either a string
or an integer.
(Note that there is no need to store an
id

value for enumerated
values; since each is a constant, each occurrence having the same value must lead
to the same actual instance.)
This element may not hav
e any nested elements.


Attributes for the
enum

element include:

o

var
: The value of this optional attribute specifies the instance variable for
which this object is the value. This attribute must be specified if this
element is directly nested within an
ob
j

element. It should not be
specified if this element is a top
-
level CogTool element or part of an
aggregate CogTool element (i.e.,
arr
,
elts
, or
map
).

o

val
: The value of this required attribute is an string representing the
unique “persistence” value of t
he represented
enum

instance
.

o

class
: The value of this required attribute is the Java name of the actual
class of this element’s value.

o

version
: The value of this required attribute is the version of the
persistence format used for this object’s class when

the serialization was
created. Effectively, the version controls what constant to use when
reconstituting the enumerated value.



Serialization and Persistence in CogTool

© 2006 CogTool, HCII, CMU

11

12/2/2013


Top
-
level example:


<enum val="1"


class="edu.cmu.cs
.hcii.cogtool.model.DeviceType"


version="0
"/>


Instance
-
variab
le example:


<enum val="1"


class="edu.cmu.cs
.hcii.cogtool.model.DeviceType"


version="0"

name="deviceType"
/>

Auxiliary Elements


There are two auxiliary CogTool
elements:
sup

reflects information held in an object’s
superclass and
key

identifies

the key portion of an entry in a
Map

instance.




sup
: This element represents the superclass information of a programmer
-
defined
class.
Superclass elements are presented in most abstract to more specific order.
(That is, if A inherits from B which inheri
ts from C, superclass C is presented
first, then superclass B.)
Nested elements
for
sup

consist of zero or more
CogTool elements (i.e., elements being described in the section above).


Attributes for the
sup

element include:

o

class
: The value of this requi
red attribute is the Java name of the actual
super
class of this element’s value.

o

version
: The value of this required attribute is the version of the
persistence format used for this
super
class when the serialization was
created. Effectively, the version r
eflects what information was stored in
the serialization.


Example
:


<obj id="14"


class="edu.
cmu.cs.hcii.cogtool.model.Task"


version="0">


<sup class="edu.cmu.cs.h
cii.cogtool.model.AUndertaking"


version="0">


<str var="name" size="6"><
![CDATA[Task 1@]]></str>


<bool var="group" val="f"/>


</sup>


</obj>



Serialization and Persistence in CogTool

© 2006 CogTool, HCII, CMU

12

12/2/2013




key
: This element
identifies the key portion of each

entry in a
Map

instance.
This element must have exactly one nested
non
-
aggregate
CogTool element (i.e.,
an element

described

in the section above
, except for
arr
,
elts
, and
map
).


There are no attributes for the
key

element.


Example:


<map var="results" id="124" size="2">


<key>


<obj id="19"


class="edu.cmu.cs.hci
i.cogtool.model.StandaloneAlgo"


version="0
">
</obj>


</key>


<obj id="642"



class="edu
.cmu
.cs.hcii.cogtool.model.StandardResult"



version="0">. . .</obj>


<key>


<ref idref="19"/>


</key>


<obj id="643"



class="edu
.cmu
.cs.hcii.cogtool.model.StandardResult"



version="0">. . .</obj>

</map
>


Actual DTD


The DTD, therefore, is as follows:


<!ELEMENT persist ((obj


| ref


| null


| int


| dbl


| bool


| str


| char



| byte


| enum


| arr


| map


| elts)*)>

<!ATTLIST persist


version CDATA #REQUIRED


cogtool_version CDATA #IMPLIED


cogtool_revision CDATA #IMPLIED


cogtool_buildtime CDATA #I
MPLIED


java_version CDATA #IMPLIED


os_name CDATA #IMPLIED


os_version CDATA #IMPLIED

>



Serialization and Persistence in CogTool

© 2006 CogTool, HCII, CMU

13

12/2/2013


<!ELEMENT obj (sup*, (obj


| ref


| null


| int


| dbl


| bool



| str


| char


| byte


| enum


| arr


| map


| elts)*)>

<!ATTLIST obj


var CDATA #IMPLIED


id CDATA #REQUIRED


class CDATA #
REQUIRED


version CDATA #REQUIRED

>


<!ELEMENT sup ((obj


| ref


| null


| int


| dbl


| bool


| str


| char


| byte


| enum



| arr


| map


| elts)*)>

<!ATTLIST
sup


class CDATA #REQUIRED


version CDATA #REQUIRED

>


<!ELEMENT ref EMPTY>

<!ATTLIST ref


var CDATA #IMPLIED


idref CDATA #REQUIRED

>


<!ELEMENT null EMPTY>

<!ATTLIST null


var CDA
TA #IMPLIED

>


<!ELEMENT int EMPTY>

<!ATTLIST int


var CDATA #IMPLIED


val CDATA #REQUIRED

>





Serialization and Persistence in CogTool

© 2006 CogTool, HCII, CMU

14

12/2/2013

<!ELEMENT dbl EMPTY>

<!ATTLIST dbl


var CDATA #IMPLIED


val CDATA #REQUIRED

>


<!ELEMENT bool EMPTY>

<!ATTLIST bool


var CDATA #IMPLIED


val (t | f) #REQUI
RED

>


<!ELEMENT str (#PCDATA)>

<!ATTLIST str


var CDATA #IMPLIED


size CDATA #REQUIRED

>


<!ELEMENT char (#PCDATA)>

<!ATTLIST char


var CDATA #IMPLIED

>


<!ELEMENT byte (#PCDATA)>

<!ATTLIST byte


var CDATA #IMPLIED


id CDATA #REQUIRED


size CDATA #R
EQUIRED

>


<!ELEMENT enum EMPTY>

<!ATTLIST enum


var CDATA #IMPLIED


val CDATA #REQUIRED


class CDATA #REQUIRED


version CDATA #REQUIRED

>


<!ELEMENT arr ((obj


| ref


| null


| int


| dbl



| bool


| str


| char


| byte


| enum


| arr


| map


| elts)*)>

<!ATTLIST arr


var CDATA #IMPLIED


id CDATA #REQUIRED


class CDATA #REQUIRED


size CDATA #REQU
IRED

>



Serialization and Persistence in CogTool

© 2006 CogTool, HCII, CMU

15

12/2/2013


<!ELEMENT elts ((obj


| ref


| null


| int


| dbl


| bool


| str


| char


| byte


| enum


| arr



| map


| elts)*)>

<!ATTLIST elts


var CDATA #IMPLIED


id CDATA #REQUIRED


size CDATA #REQUIRED

>


<!ELEMENT map ((key, (obj


| ref


| null


| int


| dbl



| bool


| str


| char


| byte


| enum


| arr


| map


| elts))*)>

<!ATTLIST map


var CDATA #IMPLIED


id CDATA

#REQUIRED


size CDATA #REQUIRED

>


<!ELEMENT key (obj


| ref


| null


| int


| dbl


| bool


| str


| char


| byte


| enum)>



Serialization and Persistence in CogTool

© 2006 CogTool, HCII, CMU

16

12/2/2013

CogTool Object Serial
ization


As
mentioned above, the sequence in

a serialization used for persistence contains
exactly
one

obj

element representing
a
CogTool
Project

instance.
This section describes the
actual data currently stored for CogTool objects. (Note “currently”: as

more functionality
is incorporated, the data stored will change!)


Each CogTool object is serialized using an
obj

element. Each description below
includes the class name and current serialization version for that class. Then,
descriptions of any supercl
asses are presented in most abstract to more specific order.
(That is, if A inherits from B which inherits from C, superclass C is presented first, then
superclass B.)


Finally, the data for the class itself is presented.

Each piece of data is associated

with its
instance variable identifier (i.e., the
var

attribute)
,

its “type”
, and a comment in square
brackets
. The “type” is given as its Java class. If the “type” is an aggregate, then the
component type
(
s
)

are given as well, using the following notati
on
s
:




If the aggregate type is a Java array (i.e., the
arr

element):


Array(<component
-
type>)




If the aggregate type is a subclass of the Java
Map

class (i.e., the
map

element):


Map(<key
-
type> :
-
> <value
-
type>)




If the aggregate type is any other su
bclass of the Java
Collection

class (i.e.,
the
elts

element):


Collection(<component
-
type>)


List(<component
-
type>
)


Set(<component
-
type>)


List

is used if the order of the component values must be maintained

and
Set

is
used if uniqueness is requi
red.

N
ote that it is the responsibility of the
ObjectLoader.IObjectLoader
’s
createObject()

method to ensure
that the proper kind of
Collection

subclass is provided.




Serialization and Persistence in CogTool

© 2006 CogTool, HCII, CMU

17

12/2/2013

Project

implements IProject
:


class="edu.cmu.cs.hcii.cogtool.model.Project"


version="0
"


Superclasses:


None currently


Nested CogTool elements:



name:

String

[the name of the

Project
]



designs:

List
(IDesign)

[
the designs held by the

Project
]



undertakings
:
List
(IUndertaking)


[
the

top
-
level
tasks

held by the

Project
]



taskApplications: Map(
Proj
ect.
TaskDesign :
-
> ITaskApplication)



[the
scripts and associated computed results
]



buildVersion: String

[the
CogTool version that saved the
Project
]




uuid: String

[
a unique identifier for the
Project
]



Task implements ITask extends IUndertaking
:


class=
"edu.cmu.cs.hcii.cogtool.model.
Task
"


version="0
"


Superclasses:

AUndertaking implements

IUndertaking


class="edu.cmu.cs.hcii.cogtool.model.
AUndertaking
"


version="0
"


Nested CogTool elements:



name: String

[the name of the

Task/TaskGroup
]



group
:
boolean

[
i
s this a
TaskGroup
;
false

in this case
]


Nested CogTool elements:


None currently



TaskGroup implements ITaskGroup extends IUndertaking
:


class="edu.cmu.cs.hcii.cogtool.model.
TaskGroup
"


version="0
"


Superclasses:

AUndertaking implements

IUndertaking


cla
ss="edu.cmu.cs.hcii.cogtool.model.
AUndertaking
"


version="0
"


Nested CogTool elements:



name: String

[the name of the

Task/TaskGroup
]



group
:
boolean

[
is this a
TaskGroup
;
true

in this case
]





Serialization and Persistence in CogTool

© 2006 CogTool, HCII, CMU

18

12/2/2013

Nested CogTool elements:



nature
:
GroupNature

[
enumerated value:
S
UM
,
MEAN
,
MIN
,
MAX
]



children:

List
(I
Undertaking
)

[
the

group’s

immediate child tasks
]



GroupNature
:


class="edu.c
mu.cs.hcii.cogtool.model.GroupNature
"


version="0
"


Enumeration persistence values
:



"S"


SUM



"M"


MEAN



"N"


MIN



"X"


MAX



Project
.TaskDesi
gn
:


class="edu.cmu.cs.hcii.cogtool.model.Project
$TaskDesign
"


version="0
"


Superclasses:


None


Nested CogTool elements:



design
:
IDesign

[the
Design

of the script(s)/result(s)
]



task:

IUndertaking

[the
Task

of the script(s)/result(s)
]



Design implements I
Design
:


class="edu.cmu.cs.hcii.cogtool.model.
Design
"


version="0
"


Superclasses:


None currently


Nested CogTool elements:



name: String

[the name of the

Design
]



deviceTypes:

Set
(DeviceType
)

[the de
vices this
Design

uses
]



frames
:
Set
(I
Frame
)

[
the frames

he
ld by the

Design
]



DeviceType
:


class="edu.c
mu.cs.hcii.cogtool.model.DeviceType
"


version="0
"


Enumeration persistence values:




1


Keyboard




2


Voice

[really, microphone]



Serialization and Persistence in CogTool

© 2006 CogTool, HCII, CMU

19

12/2/2013




4


Mouse




8


Touchscreen



16


Physical

[contains knobs, switches, etc.]



Frame

implements IFrame
:


class="edu.cmu.cs.hcii.cogtool.model.
Frame
"


version="1"


Superclasses:


None currently


Nested CogTool elements:



name: String

[the name of the

Frame
]



widgetColor: int

[the
RGB
for the color of contained
Widgets
]



widgets
: Collection(
IW
idget
)

[
LinkedHashS
et

of
widgets

in
this
Frame
]



devices
:
Map
(
DeviceType :
-
> InputDevice
)


[
Map

of
device transition sources

for this
Frame
]



origin
:
DoublePoint

[top left point of the

Frame

within the
Design
]



background
:
byte[]

[the
background image

of the

Frame
]



backgroundBounds
:
DoubleRectangle


[the
extent

of the

Frame
’s background image
]



incidentTransitions:
Set
(ITransition
)


[
the

transitions

whose target is this

Frame
]



DoublePoint
:


class="edu.c
mu.cs.hcii.cogtool.model.DoublePoint
"


version="0
"


Super
classes:


None


Nested CogTool elements:



x
:
double

[
the x coordinate of the point
]



y:

double

[
the y coordinate of the point
]



DoubleRectangle
:


class="edu.c
mu.cs.hcii.cogtool.model.DoubleRectangle
"


version="0
"


Superclasses:


None


Nested CogTool element
s:



x
:
double

[
the x coordinate of the top left point
]



y:

double

[
the y coordinate of the top left point
]



Serialization and Persistence in CogTool

© 2006 CogTool, HCII, CMU

20

12/2/2013



width:

double

[
the width of the rectangle
]



height:

double

[
the height of the rectangle
]



InputDevice

implements
I
InputDevice

extends
I
TransitionSource
:


class="edu.cmu.cs.hcii.cogtool.model.
InputDevice
"


version="0
"


Superclasses:

A
TransitionSource

implements

I
TransitionSource


class="edu.cmu.cs.hcii.cogtool.model.
ATransitionSource
"


version="0
"


Nested CogTool elements:



name: String

[the name of the

Wi
dget
/
InputDevice
]



transitions
:
Map(IAction :
-
> ITransition)


[
Map

of transitions whose source is this
]


Nested CogTool elements:



deviceType
:
DeviceType

[
enumerated value

of the device’s type
]



Widget implements IWidget extends ITransitionSource
:


class="e
du.cmu.cs.hcii.cogtool.model.
Widget
"


version="0
"


Superclasses:

A
TransitionSource

implements

ITransitionSource


class="edu.cmu.cs.hcii.cogtool.model.
ATransitionSource
"


version="0
"


Nested CogTool elements:



name: String

[the name of the

Widget/InputDevice
]



transitions
:
Map(IAction :
-
> ITransition)


[
Map

of transitions whose source is this
]


Nested CogTool elements:



title
:
String

[
display title for the
Widget
]



level
:
int

[
z
-
coordinate for
resolving
overlapping
]



renderWidget
:
boolean

[
whether to display the
Widget

accurately
]



widgetImage
:
byte[]

[
background image for the
Widget
]



widget
Type
:
WidgetType

[
type of

Widget
]



shape
:
IShape

[
shape of

the
Widget
]





Serialization and Persistence in CogTool

© 2006 CogTool, HCII, CMU

21

12/2/2013

WidgetType
:


class="edu.c
mu.cs.hcii.cogtool.model.WidgetType
"


version="0
"


Enumeration persistence valu
es:




0


Noninteractive

[suitable for look
-
at actions]




1


Button

[standard display button]




2


Menu

[region that pops up a menu]




3


Submenu

[menu item that cascades its own submenu]




4


MenuItem

[leaf menu item]




5


Text

[text box]




6


PullDownList

[region that pops a combo list]




7


PullDownItem

[combo list item]




8


ListBoxItem

[always visible list item]




9


Radio

[radio button]



10



Check

[
check
-
box
]



11


Graffiti

[Graffiti™ input area]



ShapeRectangle

implements
IShape
:


class="edu.cmu.cs.hc
ii.cogtool.model.
ShapeRectangle
"


version="0
"


Superclasses:

A
Shape

implements

IShape


class="edu.cmu.cs.hcii.cogtool.model.
AShape
"


version="0
"


Nested CogTool elements:



r
:
DoubleRectangle

[the
position and extent of the shape
]


Nested CogTool elements:


None currently



ShapeOval

implements
IShape
:


class="edu.cmu.cs.hcii.cogtool.model.
ShapeOval
"


version="0
"


Superclasses:

A
Shape

implements

IShape


class="edu.cmu.cs.hcii.cogtool.model.
AShape
"


version="0
"


Nested CogTool elements:



r
:
DoubleRectangle

[the

position and extent of the shape
]


Nested CogTool elements:


None currently



Serialization and Persistence in CogTool

© 2006 CogTool, HCII, CMU

22

12/2/2013



ShapeRoundedRectangle

implements
IShape
:


class="edu.cmu.cs.hcii.cogtool.model.
ShapeRoundedRectangle
"


version="0
"


Superclasses:

A
Shape

implements

IShape


class="edu.cmu.cs.hci
i.cogtool.model.
AShape
"


version="0
"


Nested CogTool elements:



r
:
DoubleRectangle

[the
position and extent of the shape
]


Nested CogTool elements:


None currently



Transition implements ITransition
:


class="edu.cmu.cs.hcii.cogtool.model.
Transition
"


versi
on="0
"


Superclasses:


None currently


Nested CogTool elements:



source
:
ITransitionSource

[source

Widget
/
InputD
evic
e
]



destination: IFrame

[
destination

Frame

of the

Transition
]



action
: I
Action

[
the
Set

of
frames

held by the

Design
]



IAction

instances repre
sent the actual action taken (e.g., right
-
mouse click). All
IAction

subclasses extend
AAction
:


AAction implements IAction
:


class="edu.cmu.cs.hcii.cogtool.model.
AAction
"


version="0
"


Nested CogTool elements:



actionType: ActionType

[
enumeration value ind
icating kind of action
]



All
A
Action

subclasses

have class names of the form:

edu.cmu.cs.hcii.cogtool.model.
CCC


In addition, they all currently use a version of 0 (zero).




Serialization and Persistence in CogTool

© 2006 CogTool, HCII, CMU

23

12/2/2013

The following table provides the
CCC

part of the class name and the associated
nes
ted
CogTool elements
,

if any
:


class

(
CCC

part)

nested elements

ButtonAction

-

button:
Mouse
ButtonState

-

pressType: MousePressType

-

m
odifiers: int

GraffitiAction

-

text: String

-

isCommand:
boolean

HomeKeyboardAction

none currently

HomeMouseAction

none current
ly

KeyAction

-

text: String

-

isCommand:
boolean

-

pressType: KeyPressType

-

modifiers: int

MouseHoverAction

none currently

MoveMouseAction

none currently

TapAction

-

tapPressType: TapPressType

VoiceAction

-

text: String

-

isCommand:
boolean


Notes
:

-

modifiers

is

a bitset OR’ing together modifier keys (e.g.,
SHIFT
,
ALT
)
.

-

“mental” operator insertion may depend on whether the action represents a



command or

an argument



ActionType
:


class="edu.c
mu.cs.hcii.cogtool.model.ActionType
"


version="0
"


Enume
ration persistence values:




0


Voice

[speaking; command or argument string]




1


ButtonPress

[mouse button press, release, click]




2


KeyPress

[keyboard key press, release, click]




3


Mouseover

[hover]




4


GraffitiStroke

[Graffiti™ command or argument
string]




5


MoveMouse

[mouse move or drag]




6


Tap

[touchscreen tap]




7


HomeKeyboard

[move hand to keyboard]




8


HomeMouse

[move hand to mouse]





Serialization and Persistence in CogTool

© 2006 CogTool, HCII, CMU

24

12/2/2013

MouseButtonState
:


class="edu.c
mu.cs.hcii.cogtool.model.
MouseButtonState
"


version="0
"


Enumeration pers
istence values:




0


Left

[
left mouse button
]




1


Right

[
right mouse button
]




2


Middle

[
middle mouse button
]



MousePressType
:


class="edu.c
mu.cs.hcii.cogtool.model.MousePressType
"


version="0
"


Enumeration persistence values:




0


Click

[single full cl
ick]




1


Down

[down click only]




2


Up

[up click only]




3


Double

[double full click]



KeyPressType
:


class="edu.c
mu.cs.hcii.cogtool.model.KeyPressType
"


version="0
"


Enumeration persistence values:




0


Click

[full click]




1


Down

[down click only]




2


Up

[up click only]



TapPressType
:


class="edu.c
mu.cs.hcii.cogtool.model.TapPressType
"


version="0
"


Enumeration persistence values:




0


Tap

[single full tap]




1


Down

[down tap only]




2


Up

[up tap only]




3


DoubleTap

[double full tap]





Serialization and Persistence in CogTool

© 2006 CogTool, HCII, CMU

25

12/2/2013

The foll
owing descri
be classes
as they

currently

exist
; the reader should note, however,

that
many of these
may change soon.


TaskApplication implements ITaskApplication
:


class="edu.cmu.cs.hcii.cogtool.model.
TaskApplication
"


version="0
"


Superclasses:


None curr
ently


Nested CogTool elements:



scripts
: Map(
IPredictionAlgo

:
-
>
IScript
)



[the
script
(
s
)

for a
Task
/
Design
]



results: Map(
IPredictionAlgo

:
-
>
IPredictionResult
)



[the
resul
t(s)
/trace(s)

for a
Task
/
Design
]



invalidAlgorithms
:
Set
(
IPredictionAlgo
)


[
which r
esult(s) need to be re
-
computed
]



Algorithms have no state; each class therefore acts like a singleton (i.e., no nested data).


StandaloneAlgo

extends APredictionAlgo
:


class="edu.cmu.cs.hcii.cogtool.model.

StandaloneAlgo
"


version="0
"


Superclasses:

A
Pre
dictionAlgo

implements

I
PredictionAlgo


class="edu.cmu.cs.hcii.cogtool.model.
A
PredictionAlgo
"


version="0
"


Nested CogTool elements:



None currently


Nested CogTool elements:


None currently



StandaloneAlgo
.StandaloneResult extends AResult
:


class="edu.c
mu.cs.hcii.cogtool.model.
StandaloneAlgo
"


version="0
"


Superclasses:

A
Result

implements

IPredictionResult


class="edu.cmu.cs.hcii.cogtool.model.
AResult
"


version="0
"


Nested CogTool elements:



None currently




Serialization and Persistence in CogTool

© 2006 CogTool, HCII, CMU

26

12/2/2013

Nested CogTool elements:



taskTime: double

[
tot
al analysis time
]



traceLines:
List
(String)

[
trace lines
]



errorLines:
List
(String)

[
error lines
]



Script implements IScript
:


class="edu.cmu.cs.hcii.cogtool.model.
Script
"


version="1"


Superclasses:


None currently


Nested CogTool elements:



design
:
IDesign

[the
Design

for the
Script
]



startFrame
:
I
Frame

[the
first
Frame

of

the
Script
]



handStartsOnMouse:
boolean

[if
false
, hand starts on keyboard]



scriptSteps
:
List
(
I
ScriptStep
)

[
the

individual steps of the
Script
]



IScriptStep

instances represent a step with
in a script. All
I
ScriptStep

subclasses extend
A
ScriptStep:


A
ScriptStep

implements I
ScriptStep
:


class="edu.cmu.cs.hcii.cogtool.model.
A
ScriptStep
"


version="1
"


Nested CogTool elements:



currentFrame
:
IFrame

[
the
Frame

context for the step
]



isParent
:
bool
ean

[
this step “owns” other steps, if
true
]



insertedByUser
:
boolean

[
an inserted step that involves no transition
]



validScriptStep
:
boolean

[
if
false
, step uses a deleted design component
]



resultState
:
IScriptStepGeneration.IScriptStepState


[
finite state
machine state for generating next step
]



All
AScriptStep

subclasses have class names of the form:

edu.cmu.cs.hcii.cogtool.model.
CCC


In addition, they all currently use a version of 0 (zero).


The following table provides the
CCC

part of the class name an
d the associated nested
CogTool elements, if any:



Serialization and Persistence in CogTool

© 2006 CogTool, HCII, CMU

27

12/2/2013


class (
CCC

part)

nested elements

ActionScriptStep

-

actionFocus
:
ITransitionSource

-

action
:
IAction

DelayScriptStep

-

delayDuration
:
double
(
in seconds
)

DriveScriptStep

none currently

LookAtScriptStep

-

lookAtTarget
:
IWidget

ThinkScriptStep

-

duration
:
double
(
in seconds
)



TapScriptStep extends ActionScriptStep
:


class="edu.cmu.cs.hcii.cogtool.model.
Tap
Script
Step
"


version="0
"


Superclasses:


See ActionScriptStep in the table above


Nested CogTool elemen
ts:



moveRequired
:
boolean

[
is a move required before the tap
]




Serialization and Persistence in CogTool

© 2006 CogTool, HCII, CMU

28

12/2/2013

Programming Object “Save” and “Load”

<to be completed>

Programming Evolution

<to be completed>