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

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

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

Modified Files:
	DefiningaModel.tex 
Log Message:
PyModel doc: added doc. for Association

Index: DefiningaModel.tex
===================================================================
RCS file: /cvsroot/modeling/ProjectModeling/Modeling/doc/UserGuide/DefiningaModel.tex,v
retrieving revision 1.33
retrieving revision 1.34
diff -C2 -d -r1.33 -r1.34
*** DefiningaModel.tex	30 Aug 2003 16:16:53 -0000	1.33
--- DefiningaModel.tex	30 Aug 2003 16:42:44 -0000	1.34
***************
*** 880,883 ****
--- 880,885 ----
  \end{itemize}
  
+ We now examines those subclasses and their defaults.
+ 
  %%
  \subsubsection{ADateTime\label{pymodel-attribute-props-datetime}}
***************
*** 1002,1005 ****
--- 1004,1011 ----
  to~\ref{attributes-props}.
  \end{notice}
+ \begin{notice}[warning]
+ If you want to make your primary keys class properties, please be sure to read
+ the dedicated ''FAQ'' entry (\ref{design-faq}).
+ \end{notice}
  
  Every entity must define a primary key. However, most of the times, you do not
***************
*** 1036,1041 ****
  \end{notice}
  
! If you want to make your foreign keys class properties, please be sure to read
! the dedicated ''FAQ'' entry (\ref{design-faq}).
  
  %%
--- 1042,1049 ----
  \end{notice}
  
! \begin{notice}[warning]
! Foreign keys should not be marked as class properties. For a full discussion
! on this topic, please refer to the dedicated ''FAQ'' entry (\ref{design-faq}).
! \end{notice}
  
  %%
***************
*** 1313,1316 ****
--- 1321,1370 ----
  \subsection{Association\label{pymodel-association-props}}
  
+ \class{Association}s are a pratical shortvut for defining a relationship and
+ its inverse in a single python statement.
+ 
+ Suppose that we want to design the two relationships already discussed above
+ between entities \code{Employee} and \code{Store}:
+ \begin{verbatim}
+   Employee <<-toEmployees------toStore-> Store
+ \end{verbatim}
+ 
+ We could define the appropriate \class{RToOne} and \class{RToMany} objects in
+ their respective entities. Now we can also define them like this:
+ 
+ \begin{verbatim}
+ model.entities = [ Entity('Employee'), Entity('Store') ]
+ model.associations = [
+   Association('Employee', 'Store'),
+   ]
+ \end{verbatim}
+ (We've only left in the example the necessary declarations for demonstration
+ --the full pymodel is exposed in~\ref{pymodel-sample}).
+ 
+ This automatically creates the two relationships, along with the necessay
+ foreign key.\\
+ 
+ {\bf \sc Important}: \class{Association} objects \emph{always} define a to-one
+    association from the first entity to the second entity, and an inverse
+    to-many relationship from the second entity to the first one.
+ 
+ Here is an equivalent declaration, where some of the defaults are explictly
+ exposed:
+ 
+ \begin{verbatim}
+   Association('Employee', 'Store',
+               relations=['toStore', 'toEmployees'],
+               multiplicity=[ [0, 1], [0, None] ],
+               delete=['nullify', 'deny'])
+ \end{verbatim}
+ 
+ Here again and as a general rule, we suggest that you provide at least the
+ names and the multiplicity of both relationships, so that it is clear which
+ one is the to-one/to-many relationship.
+ 
+ 
+ Now here are the defaults that \class{Association} uses. As you see, it uses
+ the same defaults then \class{RToOne} and \class{RToMany}:
+ 
  \begin{longtableiv}{p{3cm}p{1.5cm}p{4cm}p{5.5cm}}{code}{Prop.}{Type}{Default}{Comment}
  \lineiv{src}{\code{string}}{\emph{no default}}{The source entity's name. This
***************
*** 1318,1336 ****
  \lineiv{dst}{\code{string}}{\emph{no default}}{The destination entity's
  name. This parameter is mandatory when creating a \class{Association}}
! \lineiv{multiplicity}{sequence}{\code{[ [0,1], [0,None] ]}}{}
! \lineiv{relations}{sequence}{~}{~}
! \lineiv{keys}{\code{sequence}}{\code{[None, None]}}{~}
  \lineiv{delete}{sequence}{\code{[ RToOne.defaults['delete'],
!   RToMany.defaults['delete'] ]}}{~}
  \lineiv{isClassProperty}{sequence}{\code{[ RToOne.defaults['isClassProperty'],
!   RToMany.defaults['isClassProperty'] ]}}{~}
  \lineiv{joinSemantic}{sequence}{\code{[ RToOne.defaults['joinSemantic'],
!   RToMany.defaults['joinSemantic'] ]}}{~}
  \lineiv{displayLabel}{sequence}{\code{[ RToOne.defaults['displayLabel'],
!   RToMany.defaults['displayLabel'] ]}}{~}
  \lineiv{doc}{sequence}{\code{[ RToOne.defaults['doc'],
!   RToMany.defaults['doc'] ]}}{~}
  \end{longtableiv}
  
  
  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
--- 1372,1405 ----
  \lineiv{dst}{\code{string}}{\emph{no default}}{The destination entity's
  name. This parameter is mandatory when creating a \class{Association}}
! \lineiv{multiplicity}{sequence}{\code{[ [0,1], [0,None] ]}}{The multiplicity
! for each rel.}
! \lineiv{relations}{sequence}{\code{['to<Dst>', 'to<Src>s']}}{The names for the relationships}
! \lineiv{keys}{\code{sequence}}{\code{[None, None]}}{The two attributes'names
! that both relationships refer to as source/destination attributes}
  \lineiv{delete}{sequence}{\code{[ RToOne.defaults['delete'],
!   RToMany.defaults['delete'] ]}}{the delete rule for each rel.}
  \lineiv{isClassProperty}{sequence}{\code{[ RToOne.defaults['isClassProperty'],
!   RToMany.defaults['isClassProperty'] ]}}{Whether each rel. is a class property}
  \lineiv{joinSemantic}{sequence}{\code{[ RToOne.defaults['joinSemantic'],
!   RToMany.defaults['joinSemantic'] ]}}{The join semantic for each rel.}
  \lineiv{displayLabel}{sequence}{\code{[ RToOne.defaults['displayLabel'],
!   RToMany.defaults['displayLabel'] ]}}{the \code{displayLabel} for each rel.}
  \lineiv{doc}{sequence}{\code{[ RToOne.defaults['doc'],
!   RToMany.defaults['doc'] ]}}{A comment assigned to each rel.}
  \end{longtableiv}
  
+ Last, an \class{Association} can be used to define a directional association
+ (where only one of the two relationships is defined), by setting one of the
+ \code{relations} to \code{None}, such as in:
+ 
+ \begin{verbatim}
+   Association('Writer', 'Writer',
+               relations=['pygmalion', None],
+               delete=['nullify', None],
+               keys=['FK_Writer_id', 'id']),
+ \end{verbatim}
+ 
+ (extracted from \file{testPackages/AuthorBooks/pymodel_AuthorBooks.py},
+ corresponding to the model defined in~\ref{model-author-books})
  
  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%