diff --git a/Chapters/Voyage/Voyage.pillar b/Chapters/Voyage/Voyage.pillar index 700e1de..bd81ce6 100644 --- a/Chapters/Voyage/Voyage.pillar +++ b/Chapters/Voyage/Voyage.pillar @@ -8,7 +8,7 @@ In this chapter we will do a tour of Voyage API. In Voyage, all persistent objects are stored in a repository. The kind of repository that is used determines the storage backend for the objects. -To use the in-memory layer for Voyage, an instance of ==VOMemoryRepository== needs to be created, as follows: +To use the in-memory layer for Voyage for testing purpose, an instance of ==VOMemoryRepository== needs to be created, as follows: [[[ repository := VOMemoryRepository new @@ -33,8 +33,8 @@ this can be done using the message Voyage can work in two different modes: -- Singleton mode: There is an unique repository in the image, which works as a singleton keeping all the data. When you use this mode, you can program using a "behavioral complete" approach where instances respond to a certain vocabulary (see below for more details about vocabulary and usage). -- Instance mode: You can have an undetermined number of repositories living in the image. Of course, this mode requires you to make explicit which repositories you are going to use. +- Singleton mode: There is an unique repository in the image, which works as a singleton keeping all the data. When you use this mode, you program by using a "behavioral complete" approach where instances respond to a certain vocabulary (see below for more details about vocabulary and usage). +- Instance mode: You can have an undetermined number of repositories living in the image. Of course, this mode requires you to make it explicit which repositories you are going to use. By default, Voyage works in instance mode: the returned instance has to be passed as an argument to all database API operations. Instead of having to keep this @@ -50,7 +50,8 @@ repository enableSingleton. !!! Voyage API The following two tables show a representative subset of the API of Voyage. These methods are defined on ==Object== and ==Class==, but will only truly perform -work if (instances of) the receiver of the message is a Voyage root. See the ==voyage-model-core-extensions== persistence protocol on both classes for the full +work if (instances of) the receiver of the message is a Voyage root. From the example of SuperHero, ==Hero selectAll==, Hero must set up as a Voyage root. +See the ==voyage-model-core-extensions== persistence protocol on both classes for the full API of Voyage. First we show Singleton mode: @@ -62,7 +63,7 @@ First we show Singleton mode: | ==selectMany:== | retrieves all objects that matches the argument -Second is Instance mode. In Instance mode, the receiver is always the repository on which to perform the operation. +Second is Instance mode. In Instance mode, the receiver is always the repository on which to perform the operation. For exampel, ==aRepository selectAll: Hero== | ==save:== | stores an object into repository (insert or update) | ==remove:== | removes an object from repository | ==removeAll:== | removes all objects of class from repository @@ -75,7 +76,7 @@ Second is Instance mode. In Instance mode, the receiver is always the repository In a deployed application, there should be no need to close or reset the connection to the database. Also, Voyage re-establishes the connection when the image is closed and later reopened. -However, when developing, resetting the connection to the database may be needed to reflect changes. This is foremost required when changing storage options of +However, when developing or resetting the connection to the database, it may be needed to reflect changes. This is foremost required when changing storage options of the database (see section *@enhancing*). Performing a reset is achieved as follows: [[[ @@ -90,10 +91,10 @@ VORepository setRepository: nil. !!! Testing and Singleton -When we want to test that actions are really saving or removing an object from a Voyage repository we should take care that running the tests are not touching a database that may be in use. This is important since we are in presence of Singleton, which is acting as a global variable. -We should make sure that the tests are run against a repository especially set up for the tests and that they do not affect another repository. +When we want to test that actions are really saving or removing an object from a Voyage repository we should be aware of not touching the productive database meanwhile running the tests. This is important since we are in presence of Singleton, which is acting as a global variable. +We should make sure that the tests are run against a repository which especially set up for the tests and which will not affect another repository. -Here is a typical solution: during the setup, we store the current repository, set a new one and this is this new temporary repository that will be used for the tests. +Here is a typical solution: during the setup, we store the current repository, set a new one and this is the new temporary repository that will be used for the tests. [[[ diff --git a/Chapters/Voyage/VoyageIntro.pillar b/Chapters/Voyage/VoyageIntro.pillar index f1deb4a..4ae767c 100644 --- a/Chapters/Voyage/VoyageIntro.pillar +++ b/Chapters/Voyage/VoyageIntro.pillar @@ -1,4 +1,4 @@ -!! Voyage +!! Voyage @cha:voyageintro @@ -44,7 +44,7 @@ This booklet has several chapters !!! Load Voyage -To install Voyage, including support for the MongoDB database, go to the Configurations Browser (in the World Menu/Tools) and load ConfigurationOfVoyageMongo. Or alternatively execute in a workspace: +To install Voyage, including support for the MongoDB database, go to Configurations Browser (in the World Menu/Tools) and load ConfigurationOfVoyageMongo. Or alternatively execute in a workspace: [[[ Gofer it diff --git a/Chapters/VoyageTutorial/VoyageTutorial.pillar b/Chapters/VoyageTutorial/VoyageTutorial.pillar index a7f2386..36fb941 100644 --- a/Chapters/VoyageTutorial/VoyageTutorial.pillar +++ b/Chapters/VoyageTutorial/VoyageTutorial.pillar @@ -1,4 +1,4 @@ -!! A Simple Tutorial with Super Heroes +!! A Simple Tutorial with Super Heroes This chapter describes a step by step tutorial showing the possibilities offered by Voyage (an object to document mapper) We will use a simple but not trivial domain: super heroes, super powers and their equipments. @@ -8,7 +8,7 @@ You will learn how to save and retrieve objects. !!! Creating a connection -One you installed MongoBD, we can start to connect to the database as follows: +Once you installed MongoBD, we can start to connect to the database as follows: [[[ | repository | @@ -260,7 +260,8 @@ Hero removeAll. “Beware of this!” !!! Adding a new root -Now we will change our requirement and show that we want to be able to query another class of objects: the powers. Note that when you add a root, it is important that you either flush your database or perform a migration by for example loading old objects are republishing them. +Now we will change our requirement and show that we want to be able to query another class of objects: the powers. Note that when you add a root, it is important that you either delet your +database or perform a migration by ,for example, loading old objects and republishing them. Each time you change the database 'schema', you should reset the database using the following expression: [[[ @@ -308,7 +309,7 @@ Now saving your objects and checking the mongo db again should show Power ]]] -Now we can save a hero and its superpowers. To fully test we flush the heroes in the database +Now we can save a hero and its superpowers. To fully test we remove the heroes in the database executing ==Hero removeAll== and we execute the following: [[[