[Modeling-cvs] ProjectModeling/Modeling/doc/UserGuide FrameworkTypicalUsage.tex,1.4,1.5 NestedEditingContext.tex,1.3,1.4

[<ru...@us...>]

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

Modified Files:
	FrameworkTypicalUsage.tex NestedEditingContext.tex 
Log Message:
language corrections

Index: FrameworkTypicalUsage.tex
===================================================================
RCS file: /cvsroot/modeling/ProjectModeling/Modeling/doc/UserGuide/FrameworkTypicalUsage.tex,v
retrieving revision 1.4
retrieving revision 1.5
diff -C2 -d -r1.4 -r1.5
*** FrameworkTypicalUsage.tex	13 Mar 2003 18:01:30 -0000	1.4
--- FrameworkTypicalUsage.tex	21 Mar 2003 20:24:05 -0000	1.5
***************
*** 3,11 ****
  
  When writing an application using the framework, you normally do not care
! about any of its component except \class{EditingContext}s.
  
! An \class{EditingContext} is basically the place where your object lives,
! i.e. where they are inserted, fetched, deleted, or updated. This is an
! important object, like a container, holding your graph of objects as it gets
  changed, until the point where these changes are saved as a whole.
  
--- 3,11 ----
  
  When writing an application using the framework, you normally do not care
! about any of its components -- except \class{EditingContext}s.
  
! An \class{EditingContext} is the place where your objects live,
! i.e. where they are inserted, fetched, deleted, or updated. This 
! important container holds your graph of objects as it gets
  changed, until the point where these changes are saved as a whole.
  
***************
*** 14,18 ****
  pure-python application or within application servers like Zope or others.
  We suggest that you read the whole chapter, whatever your specific needs are:
! it contains important informations explaining how the framework reacts and how
  it can be used in standard situations.
  
--- 14,18 ----
  pure-python application or within application servers like Zope or others.
  We suggest that you read the whole chapter, whatever your specific needs are:
! it contains important information explaining how the framework reacts and how
  it can be used in standard situations.
  
***************
*** 31,37 ****
  point of the process. See chapter~\ref{nested-editing-context} for details.
  
! \paragraph*{Python ''batches'':} if you're designing python scripts
! fetching and manipulating a lot of objects, please also read
! section~\ref{ec-discard-changes} which enlightens valuable details about
  finalization of an \class{EditingContext}.
  
--- 31,37 ----
  point of the process. See chapter~\ref{nested-editing-context} for details.
  
! \paragraph*{Python ''batches'':} if you're designing python scripts that
! fetch and manipulate a lot of objects, please also read
! section~\ref{ec-discard-changes} that gives valuable details about
  finalization of an \class{EditingContext}.
  
***************
*** 48,52 ****
  application requires that an \class{EditingContext} is concurrently accessed
  by different threads, you have to make sure that you lock it before use (e.g.,
! before saving changes) ; methods \method{lock()} and
  \method{unlock()} are provided for that purpose. Typical usage follows:
  \begin{verbatim}
--- 48,52 ----
  application requires that an \class{EditingContext} is concurrently accessed
  by different threads, you have to make sure that you lock it before use (e.g.,
! before saving changes); methods \method{lock()} and
  \method{unlock()} are provided for that purpose. Typical usage follows:
  \begin{verbatim}
***************
*** 69,73 ****
  managed by two different threads can concurrently save their changes to their
  parent without explictly locking it --this is managed automatically. This is
! worth noticing, even if this is logical since the framework is supposed to
  ensure that any operations made on an \class{EditingContext} is safe in a
  multi-threaded environment (given that the \class{EditingContext} is not
--- 69,73 ----
  managed by two different threads can concurrently save their changes to their
  parent without explictly locking it --this is managed automatically. This is
! worth noting, even if this is logical since the framework is supposed to
  ensure that any operations made on an \class{EditingContext} is safe in a
  multi-threaded environment (given that the \class{EditingContext} is not
***************
*** 94,98 ****
  \end{enumerate}
  
! Each option has its counter-part ; some are inherently bound to what they are,
  some are due to specific features not being implemented yet. Let's look at
  the details.
--- 94,98 ----
  \end{enumerate}
  
! Each option has its drawbacks: some are inherently bound to what they are,
  some are due to specific features not being implemented yet. Let's look at
  the details.
***************
*** 115,119 ****
  \class{EditingContext} in this case, see chapter~\ref{nested-editing-context}.
  For the same reason, the \class{EditingContext} used for registering and
! saving the modifications should not be shared by
  
  
--- 115,119 ----
  \class{EditingContext} in this case, see chapter~\ref{nested-editing-context}.
  For the same reason, the \class{EditingContext} used for registering and
! saving the modifications should not be shared by different users.
  
  
***************
*** 122,126 ****
  up. The main problem with such an approach is that you will probably end up
  with all your objects being loaded in the shared \class{EditingContext} after
! some hours or days (depending on the number of hits your app. receives, the
  number of objects that a request can load, etc.). If your database is quite
  big and/or if it quickly grows, your application is likely to end with
--- 122,126 ----
  up. The main problem with such an approach is that you will probably end up
  with all your objects being loaded in the shared \class{EditingContext} after
! some hours or days (depending on the number of hits your application receives, the
  number of objects that a request can load, etc.). If your database is quite
  big and/or if it quickly grows, your application is likely to end with
***************
*** 128,132 ****
  
  
! What happens here is you do not have any mean to distinguish between the
  objects loaded by session $S_1$ and objects loaded by session $S_2$ ; as a
  consequence you cannot clean up the shared \class{EditingContext} when a
--- 128,132 ----
  
  
! What happens here is you do not have any means to distinguish between the
  objects loaded by session $S_1$ and objects loaded by session $S_2$ ; as a
  consequence you cannot clean up the shared \class{EditingContext} when a
***************
*** 143,157 ****
  
  \begin{notice}
! At some point in the future it is possible that we change our mind and support
! such a configuration. This is related to a feature which is not implemented
! yet ; it is possible that we support in the future a special attribute for you
! to specify how many (unchanged) objects you want an \class{EditingContext} to
! contain at most. Then, when the maximum number of objects is reached, it would
  be possible to automatically clean the \class{EditingContext} (the oldest
  object would be re-faulted/invalidated, or ''ghostified'' in ZODB
! jargon).
! 
! There is no ETA for this feature however, it is just a TODO item. If you think
! you need the feature, please go ahead and let us know!
  \end{notice}
  
--- 143,155 ----
  
  \begin{notice}
! At some point in the future, with the implementation of the following 
! feature described below, this negative recommendation may change:
! We may support a special attribute for you to specify the maximum 
! number of (unchanged) objects you want an \class{EditingContext} to 
! contain. Then, when the maximum number of objects is reached, it would
  be possible to automatically clean the \class{EditingContext} (the oldest
  object would be re-faulted/invalidated, or ''ghostified'' in ZODB
! jargon). There is no ETA for this feature however, it is just a TODO item. 
! If you think you need the feature, please go ahead and let us know!
  \end{notice}
  
***************
*** 182,188 ****
  \begin{quote}
  This is due to a feature missing in the framework, where changes to an
! EditingContext are not broadcasted to others. This is a TODO, highly
! prioritary, which is planned to be solved in the release after 0.9 (ETA: end
! of march 2003).
  \end{quote}
  
--- 180,185 ----
  \begin{quote}
  This is due to a feature missing in the framework, where changes to an
! EditingContext are not broadcasted to others. This is a TODO with high 
! priority, planned to be solved in the release after 0.9.
  \end{quote}
  

Index: NestedEditingContext.tex
===================================================================
RCS file: /cvsroot/modeling/ProjectModeling/Modeling/doc/UserGuide/NestedEditingContext.tex,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** NestedEditingContext.tex	7 Mar 2003 17:59:57 -0000	1.3
--- NestedEditingContext.tex	21 Mar 2003 20:24:06 -0000	1.4
***************
*** 13,18 ****
  the modifications at any point in the sub-process. Most of the time, you
  also want all the changes made during these steps to be applied as a whole,
! or not at all--this is Atomicity. Now the question is: how can this be
! done?
  
  One possibility could be to use an other \EC. It might be suitable for very
--- 13,17 ----
  the modifications at any point in the sub-process. Most of the time, you
  also want all the changes made during these steps to be applied as a whole,
! or not at all--this is Atomicity. How can this be done?
  
  One possibility could be to use an other \EC. It might be suitable for very
***************
*** 31,35 ****
   changes in the first \EC) that were made but 
   not saved before the complex operation began. 
!  This, agains, is probably not what you would want. 
  
  \end{itemize}
--- 30,34 ----
   changes in the first \EC) that were made but 
   not saved before the complex operation began. 
!  This, again, is probably not what you would want. 
  
  \end{itemize}
***************
*** 60,64 ****
  
    A nested \EC\ is the solution for the problem. It provides a clean and
!   handful way of making changes on an other \EC, while exposing three of the
    four ACID properties at the object level:
  
--- 59,63 ----
  
    A nested \EC\ is the solution for the problem. It provides a clean and
!   convenient way of making changes on an other \EC, while exposing three of the
    four ACID properties at the object level:
  
***************
*** 80,90 ****
    In other words, you can think of a nested EditingContext as a transaction
    made at the object level.
! 
!   Last, since a nested \EC\ uses its parent \EC as its parent object store,
!   the objects you'll get when e.g. fetching will all reflect the state of
!   the parent. For example, inserted objects will show up in the result set
!   of a fetch, but deleted objects won't. Moreover, any object you will get
    in a nested \EC will reflect the changes made on it in its parent, even
!   the uncommitted/unsaved ones.
  
  % Declaration
--- 79,87 ----
    In other words, you can think of a nested EditingContext as a transaction
    made at the object level.
!   
!   Moreover, any object you will get
    in a nested \EC will reflect the changes made on it in its parent, even
!   the uncommitted/unsaved ones, e.g. inserted objects will show up in the 
!   result set of a fetch, but deleted objects won't. 
  
  % Declaration
***************
*** 171,175 ****
  \begin{description}
  \item[How to dynamically identify a nested \EC?]
! Simply invoke \method{parentObjectStore()} on it ; if the result is an
  another \EC, it is nested. Otherwise it is a regular \EC.
  \begin{verbatim}
--- 168,172 ----
  \begin{description}
  \item[How to dynamically identify a nested \EC?]
! Simply invoke \method{parentObjectStore()} on it ; if the result is 
  another \EC, it is nested. Otherwise it is a regular \EC.
  \begin{verbatim}
***************
*** 208,217 ****
  \section{Limitations with multiple child {\EC}s \label{nested-ec-limitations}}
  
! You may wonder how the child {\EC}s behave when changes in
! one of them is saved to its parent. The answer is, for now, quite simple:
  the other children won't notice anything. This leads to some
! problems, depending on their respective actions.
  
- In practice, this means two important things:
  \begin{enumerate}
  
--- 205,213 ----
  \section{Limitations with multiple child {\EC}s \label{nested-ec-limitations}}
  
! You may wonder how child {\EC}s behave when changes in any
! one of them is saved to its parent. The answer, for now, is quite simple:
  the other children won't notice anything. This leads to some
! problems, depending on the changes affected in the child {\EC}:
  
  \begin{enumerate}