[Modeling-cvs] ProjectModeling/Modeling/doc/UserGuide DefiningaModel.tex,1.32,1.33

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

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

Modified Files:
	DefiningaModel.tex 
Log Message:
PyModel doc: added doc. for RToOne/RToMany being inverse to each other

Index: DefiningaModel.tex
===================================================================
RCS file: /cvsroot/modeling/ProjectModeling/Modeling/doc/UserGuide/DefiningaModel.tex,v
retrieving revision 1.32
retrieving revision 1.33
diff -C2 -d -r1.32 -r1.33
*** DefiningaModel.tex	30 Aug 2003 15:13:00 -0000	1.32
--- DefiningaModel.tex	30 Aug 2003 16:16:53 -0000	1.33
***************
*** 871,874 ****
--- 871,882 ----
  \end{notice}
  
+ Every attribute can be declared as a plain \class{Attribute} object. However,
+ the framework provides convenience subclasses for standard attributes:
+ \begin{itemize}
+ \item \class{ADateTime} for mapping dates,
+ \item \class{AFloat} for mapping floating-point numbers,
+ \item \class{AInteger} for mapping integers,
+ \item and \class{AString} for mapping strings.
+ \end{itemize}
  
  %%
***************
*** 975,979 ****
  \subsubsection{APrimaryKey\label{pymodel-attribute-props-primary-key}}
  
! The component \class{AFloat} redefines the following defaults:
  
  \begin{longtableiv}{p{3cm}p{1.5cm}p{4cm}p{5.5cm}}{code}{Prop.}{Type}{Default}{Comment}
--- 983,987 ----
  \subsubsection{APrimaryKey\label{pymodel-attribute-props-primary-key}}
  
! The component \class{APrimaryKey} redefines the following defaults:
  
  \begin{longtableiv}{p{3cm}p{1.5cm}p{4cm}p{5.5cm}}{code}{Prop.}{Type}{Default}{Comment}
***************
*** 995,998 ****
--- 1003,1018 ----
  \end{notice}
  
+ Every entity must define a primary key. However, most of the times, you do not
+ want to explicitly declare a primary key in each of your entities, since
+ they'll basically be the same. In this case, you'll simply add a primary key
+ to the \class{Entity}'s defaults:
+ \begin{verbatim}
+ Entity.defaults['properties'] = [
+   APrimaryKey('id', isClassProperty=0, isRequired=1, doc='PK')
+ ]
+ \end{verbatim}
+ Every declared entity will then automatically get its own primary key --a
+ clone of the default one.
+ 
  %%
  \subsubsection{AForeignKey\label{pymodel-attribute-props-foreign-key}}
***************
*** 1065,1069 ****
  \lineiv{displayLabel}{\code{string}}{\code{''}}{~}
  \lineiv{doc}{\code{string}}{\code{''}}{~}
! \lineiv{inverse}{\code{string}}{\code{''}}{~}
  \end{longtableiv}
  
--- 1085,1091 ----
  \lineiv{displayLabel}{\code{string}}{\code{''}}{~}
  \lineiv{doc}{\code{string}}{\code{''}}{~}
! \lineiv{inverse}{\code{string}}{\code{''}}{a valid relationship's name in the
! destination entity --see~\ref{pymodel-relationship-props-inverse}, ''Inverse
! relationships'' for a full discussion.}
  \end{longtableiv}
  
***************
*** 1208,1214 ****
  inverse of each other.
  
! \subsubsection{Inverse relationship\label{pymodel-relationship-props-inverse}}
  
  
  
  %%
--- 1230,1312 ----
  inverse of each other.
  
! \subsubsection{Inverse relationships\label{pymodel-relationship-props-inverse}}
! 
! Most of the times, a \class{RToOne} relationship is the inverse of a
! \class{RToMany}. That's why they both have a field \code{inverse}, which
! allows you to identify the inverse relationship.
! 
! When you define both \class{RToOne} and \class{RToMany} with \emph{explicit}
! source- and destination attributes (using the fields, resp., \code{src} and
! \code{dst}),  a PyModel does not need this information to know that the two
! relationships are inverse for each other: a simple inspection of the
! relationships makes it noticeable that their source/destination entity and
! attributes are the same, which allows it to deduce that they are inverse to
! each other.
  
+ However, when you use the automatic and \emph{implicit} declaration of source
+ and destination attributes, you must supply the \code{inverse} keyword,
+ otherwise you won't get what you expect. Suppose you declare something like
+ this:
  
+ \begin{verbatim}
+    self.model.entities = [
+      Entity('Employee',
+              properties=[ RToOne('toStore', 'Store'),
+                           ] ),
+       Entity('Store',
+              properties=[RToMany('toEmployees','Employee'),
+                           ] ),
+       ]
+ \end{verbatim}
+ 
+ Now see what happens (we suppose here that you have read how automatic binding
+ of source and destination attributes is done, as described
+ in~\ref{pymodel-relationship-props-toone}):
+ 
+ \begin{enumerate}
+ 
+ \item the PyModel examine the first \class{RToOne}; given that neither
+       \code{src} nor \code{dst} are supplied, its destination attribute is
+       automatically bound to the \code{Store}'s primary key, and a
+       \class{AForeignKey} is created, named \code{'fkStore'}, and assigned to
+       the source attribute.
+ 
+ \item Now the PyModel examine the other \class{RToMany} relationship. The
+       source attribute is automatically bound to \class{Store}'s primary
+       key. What about the destination attribute? As expected, a foreign key
+       should be created then bound; but since a attribute \code{'fkStore'}
+       already exists (created at the previous step), a foreign key named
+       \code{'fkStore1'} is created and bound to the destination attribute.
+ 
+ \end{enumerate}
+ 
+ So: two foreign keys were created in entity \code{Store}, one for each
+ relationship defined. As a consequence, and since the two relationships use
+ their own foreign key, they cannot be considered as inverse to each other.
+ 
+ This is why you must supply the \code{inverse} attribute when designing a
+ relationship and its inverse. When it is supplied, the automatic generation of
+ foreign key detects it and, rather than re-creating an other foreign key such
+ as above in step 2., re-uses the foreign key that was previously created in
+ step 1. Hence, the following declaration is correct:
+ 
+ \begin{verbatim}
+    self.model.entities = [
+      Entity('Employee',
+              properties=[ RToOne('toStore', 'Store', inverse='toEmployees'),
+                           ] ),
+       Entity('Store',
+              properties=[RToMany('toEmployees','Employee',inverse='toStore'),
+                           ] ),
+       ]
+ \end{verbatim}
+ 
+ \begin{notice}
+ It is not required that both relationships defines the \code{inverse}
+ attribute: it is sufficient to declare it in one of the two relationships
+ (either the \class{RToOne} or the \class{RToMany}). However and as a general
+ rule, we think that it makes a pymodel clearer if you define it in both
+ relationships, and we suggest that you do that.
+ \end{notice}
  
  %%
***************
*** 1243,1246 ****
--- 1341,1349 ----
  
  Before going into details, here is the skeleton of an xml-model:
+ 
+ %% this is ended before subsection Full Format
+ \makeatletter
+ \def\verbatim@font{\footnotesize\ttfamily}
+ \makeatother
  \begin{verbatim}
  <?xml version='1.0' encoding='iso-8859-1'?>
***************
*** 1268,1272 ****
  
  \begin{notice}
! Please note that every value associated to a xml attribute should be a string.
  \end{notice}
  
--- 1371,1376 ----
  
  \begin{notice}
! every value associated to a xml attribute should be a string. It is
! automatically converted to the right type when the model is loaded.
  \end{notice}
  
***************
*** 1396,1406 ****
  All these attributes are described in section~\ref{relationships-props}.
  
!  Possible values for delete rules are:
  \begin{description}
! \item[for \code{DELETE_NULLIFY}:] (default) \code{'0'}
! \item[for \code{DELETE_DENY}:] \code{'1'}
! \item[for \code{DELETE_CASCADE}:] \code{'2'}
! \item[for \code{DELETE_NOACTION}:] \code{'3'}
! \end{description}
  
  Note: in future it will be possible to enter the real names (such as
--- 1500,1512 ----
  All these attributes are described in section~\ref{relationships-props}.
  
! Here are the possible values for these attributes, and their meaning:
  \begin{description}
! \item[\code{isClassProperty}:] 
! \begin{itemize}
! \item{} code{'0'}: \code{DELETE NULLIFY}
! \item{} \code{'1'}: \code{DELETE DENY}
! \item{} \code{'2'}: \code{DELETE CASCADE} 
! \item{} \code{'3'}: \code{DELETE NOACTION}
! \end{itemize}
  
  Note: in future it will be possible to enter the real names (such as
***************
*** 1408,1412 ****
        module \module{ClassDescription}.
  
- \begin{description}
  \item[\code{isClassProperty}:] 
        Default value: \code{'1'} ({\em Yes}). \code{'0'} stands for {\em No}.
--- 1514,1517 ----
***************
*** 1488,1491 ****
--- 1593,1600 ----
  </relation>
  \end{verbatim}
+ %% This ends the redefinition  started at Xml Overview (beginning of section)
+ \makeatletter
+ \def\verbatim@font{\normalsize\ttfamily}
+ \makeatother
  
  \subsection{Full format of an xml-model\label{full-xml-format}}