[Modeling-cvs] ProjectModeling/Modeling/doc/UserGuide FrameworkTypicalUsage.tex,NONE,1.1

[<sbi...@us...>]

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

Added Files:
	FrameworkTypicalUsage.tex 
Log Message:
Added: doc/UserGuide/FrameworkTypicalUsage (to be continued)

--- NEW FILE: FrameworkTypicalUsage.tex ---
%%
\chapter{Integration in an application\label{framework-integration-hints}}

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.

However, depending on the kind of applications you are developing, you will
take different approaches. We'll see how this can be done, either in a
pure-python application or within application servers like Zope or others.

%%
\section{Pure python applications\label{framework-integration-pure-python}}

For a standard python application, you'll probably do not need more than one
\class{EditingContext}, containing all your objects. Typically, you will
delegate the building and servicing for that application-wide
\class{EditingContext} to some central manager all your
objects/widgets/whatever we have access to.

Additionally, you'll maybe need from time to time to create a child
\class{EditingContext}, for example if you need to make some changes and
processing in a pop-up window and want to propose a 'Cancel' button at any
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}.


%%
\section{Instructions of use in a multi-threaded environment\label{framework-integration-MT-considerations}}

The framework itself is designed to work in a multi-threaded environment, and
it makes sure that critical sections accessing shared variables are correctly
handled (such as when the module \module{Database} provides or updates the
globally cached database snapshots).

However, the \class{EditingContext} itself is not MT-safe by default. If your
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}
try:
  ec.lock()
  ec.saveChanges()
finally:
  ec.unlock()
\end{verbatim}

\begin{notice}[warning]
Locking an \class{EditingContext} does {\bf \sc not} lock the objects it
contains. If you want e.g. to be able to concurrently access \& update the
objects, you can take different approaches. For example, you might decide to
use the \class{EditingContext} lock as a global locking mechanism, or you'll
design your own locking scheme for your objects.
\end{notice}

Last, two nested \class{EditingContext} which have the same parent and are
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
shared between threads, obviously).

%%
\section{Application servers, Zope\label{framework-integration-applications-servers}}

For an application run by an application server, different approaches are
possible:

\begin{enumerate}

\item{}
you can choose to have the same configuration as in a standalone python app.,
i.e. an application-wide \class{EditingContext}. In this case you will
occasionally create a specific \class{EditingContext} on which the changes
will be made (you'll probably want to use a child
\class{EditingContext} in this case, see chapter~\ref{nested-editing-context}.
The reason for not using the the app.-wide EC is obviously that you do not
want your users to see the changes made by others until they are committed to
the database.

\item{}
You can also choose to assign a different \class{EditingContext} bound to each
(http-)session.

\end{enumerate}

\subsection{Sharing an \class{EditingContext} between session\label{framework-integration-shared-ec}}
The first solution requires that you take all appropriate actions to ensure
that your application is MT-safe, as described in paragraphs above. Then, you
must keep in mind that the shared \class{EditingContext} will receive all the
objects that can be possibly loaded by the sessions coming up. If your
database is quite big, 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.).


Moreover, 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 session is expired
and destroyed. The only thing you can do for clean-up is to detect that no
more sessions are available: at this point, you would probably drop the
existing \class{EditingContext} and create a brand new one.

%% Note: it is in situations like this where it would be nice to add the
%% following feature to an EC: like in ZODB/Zope, have a 'maximum number of
%% cached objects' trigger the invalidation of objects when needed

\subsection{Sessioning\label{framework-integration-sessioning-ec}}

TBD

\section{Zope\label{framework-integration-zope}}

TBD

\section{Others\label{framework-integration-others}}

- sessioning 

- cgi? --> do not think so (initialization process is probably too heavy)