[Modeling-cvs] ProjectModeling/Modeling/doc/UserGuide ManipulatingGraphOfObjects.tex,1.12,1.13

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/modeling/ProjectModeling/Modeling/doc/UserGuide
In directory sc8-pr-cvs1:/tmp/cvs-serv12689/doc/UserGuide

Modified Files:
	ManipulatingGraphOfObjects.tex 
Log Message:
Documentation for fetching raw rows part 1 --to be continued

Index: ManipulatingGraphOfObjects.tex
===================================================================
RCS file: /cvsroot/modeling/ProjectModeling/Modeling/doc/UserGuide/ManipulatingGraphOfObjects.tex,v
retrieving revision 1.12
retrieving revision 1.13
diff -C2 -d -r1.12 -r1.13
*** ManipulatingGraphOfObjects.tex	10 Jul 2003 11:57:55 -0000	1.12
--- ManipulatingGraphOfObjects.tex	16 Jul 2003 23:32:17 -0000	1.13
***************
*** 50,55 ****
    To create an \class{EditingContext}, simply use the statements:
  \begin{verbatim}
!       from Modeling.EditingContext import EditingContext
!       ec=EditingContext()
  \end{verbatim}

--- 50,55 ----
    To create an \class{EditingContext}, simply use the statements:
  \begin{verbatim}
!         >>> from Modeling.EditingContext import EditingContext
!         >>> ec=EditingContext()
  \end{verbatim}

***************
*** 73,78 ****
      'insertObject()':
  \begin{verbatim}
!        newBook=Book()
!        ec.insertObject(newBook)
  \end{verbatim}

--- 73,78 ----
      'insertObject()':
  \begin{verbatim}
!         >>> newBook=Book()
!         >>> ec.insertObject(newBook)
  \end{verbatim}

***************
*** 82,89 ****

  \begin{verbatim}
!        newBook=Book()
!        ec.insert(newBook)
  \end{verbatim}

  \section{Fetching objects\label{ec-fetch-object}}

--- 82,140 ----

  \begin{verbatim}
!        >>> newBook=Book()
!        >>> ec.insert(newBook)
  \end{verbatim}

+ \section{Updating objects\label{ec-update-object}}
+ 
+     As explained in section \ref{basics-CustomObject}, 
+     the getters and setters take care of informing the
+     \class{EditingContext} of any changes made to an object. Thus, except for
+     the \method{willRead} and \method{willChange} methods in the getters and
+     setters, you do not need to take any particular other action.
+ 
+ 
+     We will see in section~\ref{ec-fetch-object} how to retrieve objects from
+     the database.
+ 
+ \section{Deleting an object\label{ec-delete-object}}
+ 
+     (We suppose here we already know how to get objects --this is covered by
+     the next section)
+ 
+ 
+     When you want an object to be deleted, you inform it with the
+     \method{deleteObject} message:
+ \begin{verbatim}
+         >>> ec.deleteObject(aBook)
+ \end{verbatim}
+ 
+     Alternatively, you can use the method \method{delete} ; both
+     \method{delete} and \method{deleteObject} are completely equivalent, and
+     depending on your own feeling you may prefer one or the other.
+ 
+     You can also discard the insertion of an object you've just added:
+ 
+ \begin{verbatim}
+        >>> newBook = Book()
+        >>> ec.insert(newBook)
+        [... then at some point you can change your mind]
+        >>> ec.delete(newBook)
+ \end{verbatim}
+ 
+     Note that, before a deleted object is about to be made persistent (i.e. when
+     its corresponding row in the database is about to be deleted), some logic
+     is triggered. For example, if this object still has some relationships but
+     these relationships are marked as \constant{CASCADE_DELETE}, the objects
+     in relations will be deleted as well (given that their own validation
+     logic allows them to be deleted, of course). Or, if it is marked as
+     \constant{DELETE_DENY}, the deletion will be denied and for that object to
+     be deleted, you will need to remove any object in relation with it.
+ 
+     You can refer to the next section, \ref{ec-save-changes}, and to
+     relationships' properties described in section~\ref{design-rels} for
+     further details.
+ 
+ 
  \section{Fetching objects\label{ec-fetch-object}}

***************
*** 168,172 ****
  You can also use the operator \code{'caseInsensitiveLike'}:
  \begin{verbatim}
!     object=ec.fetch('Writer', qualifier='lastName caseInsensitiveLike "hu?o"')
  \end{verbatim}
  will match: \code{'Hugo'}, \code{'Hulo'}, \code{'HUGO'}, \code{'hUXO'}, ...
--- 219,223 ----
  You can also use the operator \code{'caseInsensitiveLike'}:
  \begin{verbatim}
!     objects=ec.fetch('Writer', qualifier='lastName caseInsensitiveLike "hu?o"')
  \end{verbatim}
  will match: \code{'Hugo'}, \code{'Hulo'}, \code{'HUGO'}, \code{'hUXO'}, ...
***************
*** 175,179 ****
  \code{caseInsensitiveLike}: \code{ilike}
  \begin{verbatim}
!     object=ec.fetch('Writer', qualifier='lastName ilike "hu?o"')
  \end{verbatim}

--- 226,230 ----
  \code{caseInsensitiveLike}: \code{ilike}
  \begin{verbatim}
!     objects=ec.fetch('Writer', qualifier='lastName ilike "hu?o"')
  \end{verbatim}

***************
*** 357,397 ****
  \end{itemize}

! \section{Updating objects\label{ec-update-object}}

!     As explained in section \ref{basics-CustomObject}, 
!     the getters and setters take care of informing the
!     \class{EditingContext} of any changes made to an object. Thus, except for
!     the \method{willRead} and \method{willChange} methods in the getters and
!     setters, you do not need to take any particular other action.

! \section{Deleting an object\label{ec-delete-object}}

-     When you want an object to be deleted, you inform it with the
-     \method{deleteObject} message:
  \begin{verbatim}
!         ec.deleteObject(aBook)
  \end{verbatim}

!     Alternatively, you can use the method \method{delete} ; both
!     \method{delete} and \method{deleteObject} are completely equivalent, and
!     depending on your own feeling you may prefer one or the other.

  \begin{verbatim}
!        ec.delete(newBook)
  \end{verbatim}

!     Note that, before a deleted object is about to be made persistent (i.e. when
!     its corresponding row in the database is about to be deleted), some logic
!     is triggered. For example, if this object still has some relationships but
!     these relationships are marked as \constant{CASCADE_DELETE}, the objects
!     in relations will be deleted as well (given that their own validation
!     logic allows them to be deleted, of course). Or, if it is marked as
!     \constant{DELETE_DENY}, the deletion will be denied and for that object to
!     be deleted, you will need to remove any object in relation with it.

!     You can refer to the next section, \ref{ec-save-changes}, and to
!     relationships' properties described in section~\ref{design-rels} for
!     further details.

  \section{Saving Changes\label{ec-save-changes}}
--- 408,540 ----
  \end{itemize}

! \subsection{The influence of an EditingContext on fetchs\label{ec-fetch-inserted-deleted-objects}}

! TBD

! \subsection{Fetching raw rows\label{ec-fetch-raw-rows}}
! 
! Sometimes and for some reasons, you do not want to get a whole set of fully
! initialized objects.
! 
! For example, you need to get the data for a lot of objects to do some
! processing on some of its attributes, but you don't need the objects {\em per
! se}.
! 
! Or, building a GUI, you want to present a large list of items from which the
! user can e.g. choose one for, say, inspection or modification; here again, you
! do not need all the {\em objects} to build the list, and most of times you do
! not want it either since this would imply a too large memory footprint (along
! with a fetch taking too much time): all what you want is the raw data
! themselves, and the ability to turn them into real objects just when you need
! it (e.g. for modification).
! 
! In this section we'll see how to do these both things: fetching raw rows and
! turning a raw into a real object.
! 
! \subsubsection{Getting raw data\label{ec-fetch-get-raw-rows}}
! 
! The framework offers a specific API for this:

  \begin{verbatim}
! >>> from Modeling.EditingContext import EditingContext
! >>> import pprint, StoreEmployees
! >>> ec = EditingContext()
! >>> raw_employees = ec.fetch('Employee', isDeep=1, rawRows=1)
! >>> pprint.pprint(raw_employees)
! [{'firstName': 'Jeanne',
!   'fkStoreId': 1,
!   'id': 2,
!   'lastName': 'Cleese',
!   'storeArea': 'DE'},
!  {'firstName': 'John Jr.',
!   'fkStoreId': 1,
!   'id': 1,
!   'lastName': 'Cleese',
!   'storeArea': 'AB'},
!  {'firstName': 'John',
!   'fkStoreId': 1,
!   'id': 3,
!   'lastName': 'Cleese',
!   'officeLocation': '4XD7'}]
  \end{verbatim}

! As you can see, with parameter {\bf \code{rawRows}} you get the raw dictionary
! directly from the database. No object is initialized by such a fetch. However,
! you can use every functionality we already saw for fetching (inheritance with
! parameter \code{isDeep}, qualifiers), as is.
! 
! 
! The very same rule applies to raw fetch as to ``normal'' fetch, in particular,
! everything we saw in the section~\ref{ec-fetch-inserted-deleted-objects} is
! still valid. If your \class{EditingContext} contains some newly inserted
! objects, you'll them appear; and deleted objects won't appear. For example:

  \begin{verbatim}
! >>> from StoreEmployees.SalesClerk import SalesClerk
! >>> terry=SalesClerk()
! >>> terry.setFirstName('Terry'); terry.setLastName('Gilliam')
! >>> ec.insert(terry)
! >>> salesClerks=ec.fetch('SalesClerk', rawRows=1)
! >>> pprint.pprint(salesClerks)
! [{'firstName': 'Jeanne',
!   'fkStoreId': 1,
!   'id': 2,
!   'lastName': 'Cleese',
!   'storeArea': 'DE'},
!  {'firstName': 'John Jr.',
!   'fkStoreId': 1,
!   'id': 1,
!   'lastName': 'Cleese',
!   'storeArea': 'AB'},
!  {'firstName': 'Terry',
!   'fkStoreId': None,
!   'id': <Modeling.GlobalID.TemporaryGlobalID instance at 0x84fcc64>,
!   'lastName': 'Gilliam',
!   'storeArea': None}]
! >>> salesClerk.globalID()
! <Modeling.GlobalID.TemporaryGlobalID instance at 0x84fcc64>
  \end{verbatim}

! You probably already noticed the particular value associated to Terry's
! '\code{id}' field. Since this object is not saved in the database yet, its
! current \code{id} (the primary key for \class{SalesClerk} objects) is not
! determined yet either. Instead, the framework returns its identifier, which is
! a \class{TemporaryGlobalID}.

! The same phenomenon appear on foreign keys when an object is related to a
! newly inserted object; continuing the previous example:
! \begin{verbatim}
! >>> pprint.pprint(ec.fetch('Executive', rawRows=1)) # No modifications yet
! [{'firstName': 'John',
!   'fkStoreId': 1,
!   'id': 3,
!   'lastName': 'Cleese',
!   'officeLocation': '4XD7'}]
! >>> from StoreEmployees.Store import Store
! >>> parrot_store=Store()
! >>> parrot_store.setCorporateName('We sell parrots')
! >>> ec.insert(parrot_store)
! >>> john=ec.fetch('Executive', 'firstName=="John"')[0]
! >>> john.getToStore().removeFromEmployees(john)
! >>> john.setToStore(parrot_store) ; parrot_store.addToEmployees(john)
! >>> pprint.pprint(ec.fetch('Executive', rawRows=1))
! [{'firstName': 'John',
!   'fkStoreId': <Modeling.GlobalID.TemporaryGlobalID instance at 0x8364a0c>,
!   'id': 3,
!   'lastName': 'Cleese',
!   'officeLocation': '4XD7'}]
! >>> parrot_store.globalID()
! <Modeling.GlobalID.TemporaryGlobalID instance at 0x8364a0c>
! \end{verbatim}

+ We see clearly here that this time, \code{fkStoreId} gets a
+ \class{TemporaryGlobalID} corresponding to \code{parrot_store}'s global
+ id. Moreover, we also remark that even if the modifications are not saved into
+ the database yet, raw fetching returns the objects as they currently are in
+ the \class{EditingContext}, just as with normal fetching.
+ 
+ \subsubsection{Turning rows into real objects\label{ec-fetch-turn-raw-row-to-object}}
+ 
+ TBD 

  \section{Saving Changes\label{ec-save-changes}}