This document provides tips and tricks for persisting object models using Voyage, an abstraction layer for mapping objects to databases. It discusses how Voyage ensures object identity and error handling while implementing a connection pool. The document emphasizes thinking in objects when modeling data and allows missing references between objects. It also provides examples of querying objects and adapting data schemes when the database schema differs from the object model. Finally, it outlines upcoming features for Voyage 2.0 including root detection, cyclic detection, and a Riak backend.

1. Voyage by example
tips and tricks on persisting object models

2. Esteban Lorenzano
Pharo core developer
INRIA - RMoD
http://smallworks.eu

3. Why?
• You already know about Voyage
• You already attended to a tutorial last year
• But there are some recurrent problems people find
when trying to use it
• And I’m still seeing a lot of people that could be
using it and they chose other solutions

4. What is Voyage? (1)
• Simple abstraction layer to map objects into a database
- Very well suited for document databases, but in theory,
the approach will work for other kind of repositories
‣ There was (long time ago) a Voyage-GLORP backend
‣ There was (even more time ago) a Voyage-
ImageSegment backend
- Voyage-Memory, Voyage-Mongo

5. What is Voyage? (2)
• Did I said is simple?
• it ensures object identity
• it provides error handling
• it implements a connection pool

6. Voyage principles
• Behavioural complete (for common usage), but
decoupled approach also possible.
• Same design for different backends, but not a
common abstraction
- There is no such thing as a “voyage query
language”, etc.
- is a bit more work for users who want to switch,
but a lot more happiness for the program itself

7. Voyage ultimate goal
To be the GLORP for NoSQL databases

8. The problem to solve

9. Impedance mistmatch
Table BTable A Table C
Class A Class B Class C
1..*
*..*
Ideal relational model

10. Impedance mistmatch
anObject otherObject
aColection
firstObject
secondObject
thirdObject
Real object model

11. Impedance mistmatch
Real object model
anObject otherObject
aColection
firstObject
secondObject
thirdObject

12. Impedance mistmatch
Real object model
anObject otherObject
aColection
firstObject
secondObject
thirdObject

13. So, what about those tips?

14. Think in objects

15. A simple model
Hero Power
*..*

16. Persist
(Hero named: ‘Groot’)
addPower: ((Power named: ‘Plant Control’)
level: #epic;
yourself);
save.

17. Persist
{
_id: OID(…),
#version: …,
#instanceOf: ‘Hero’,
name: ‘Groot’,
powers: [ { #collection: ‘Power’, __id: OID(…) } ]
}
!
{
_id: OID(…),
#version: …,
#instanceOf: ‘Power’,
name: ‘Plant Control’,
level: #epic,
heroes: [ #collection: ‘Hero’, __id: OID(…) ]
}

18. Take control

19. A simple model
(a bit more complete)
Hero Power
*..*
Equipment
1..*
Container Pistol
1..*

20. Persist
(Hero named: ‘Star-lord’)
addEquipment: (Container
addItem: Pistol new;
yourself);
save.

21. Persist (1)
{
_id: OID(…),
#version: …,
#instanceOf: ‘Hero’,
name: ‘Star-lord’,
powers: [],
equipment: [ {
#instanceOf: ‘Container’,
‘items’, [
{ #instanceOf: ‘Pistol’ } ] } ]
}

22. Persist (2)
{
_id: OID(1),
#version: …,
#instanceOf: ‘Hero’,
name: ‘Star-lord’,
powers: [],
equipment: [ { #collection: ‘Equipment’, __id: OID(2) } ]
}
!
{
_id: OID(2),
#version: …,
#instanceOf: ‘Container’,
items: [ { #collection: ‘Equipment’, __id: OID(3) } ]
}
!
{
_id: OID(3),
#version: …,
#instanceOf: ‘Pistol’,
}

23. Integrity is a
consequence

24. Allowing missing content
• We do not have foreign keys
- So we cannot do things like “ON DELETE
CASCADE”
- Even delete validations are difficult
‣ Imagine “hero” has a “power”,and I remove the
“power”. How can the hero notice it?

25. Persist
mongoContainer
<mongoContainer>
!
^ VOMongoContainer new
collectionName: ‘powers’;
enableMissingContent;
yourself

26. Querying smart

27. Query (1)
Hero
selectMany: [ :each | … ]
sortBy: { #name -> VOOrder ascending } asDictionary
limit: 100
offset: 100

28. Query (2)
Hero
selectMany: {
‘name’ -> {
‘$regexp’ -> ‘^G.*’.
‘$options’ -> ‘i’
} asDictionary
} asDictionary

29. Adapt schemes

30. The “scheme is not mine”
problem
• You can move meta-information to your program
• Magritte-Voyage gives you a lot of power
• You can extend/modify parts of the updating
system too (like versioning)

31. Meta-information
{
_id: OID(…),
#version: …,
#instanceOf: ‘Hero’,
name: ‘Star-lord’,
powers: [],
equipment: [ {
#instanceOf: ‘Container’,
‘items’, [
{ #instanceOf: ‘Pistol’ } ] } ]
}

32. Meta-information
{
_id: OID(…),
#version: …,
#instanceOf: ‘Hero’,
name: ‘Star-lord’,
powers: [],
equipment: [ {
#instanceOf: ‘Container’,
‘items’, [
{ #instanceOf: ‘Pistol’ } ] } ]
}

33. Meta-information
{
_id: OID(…),
name: ‘Star-lord’,
powers: [],
equipment: [ {
‘items’, [ {} ] } ]
}

34. Voyage 2.0
• Root detection (enhance save & update)
• Cyclic detection
- Add strategy to persist cycles even without roots (It has some
consequences (in querying, etc.), so it will be optional)
• integrity validations
- #removeWithDependencies
• Materialisation customisations
- #readRaw
• Add backend: Riak

35. Use it today!
Gofer it
smalltalkhubUser: ‘Pharo’ project: ’MetaRepoForPharo30’;
configurationOf: ‘VoyageMongo’;
loadStable.
Thanks!!
Esteban Lorenzano - 2014