| Title: Relationships |
| |
| |
| |
| <P>Relationships are special <A href="http://objectstyle.org/cayenne/api/cayenne/org/objectstyle/cayenne/DataObject.html" class="external-link" rel="nofollow">DataObject</A> properties that reference other "related" objects. Semantically there are two types of relationships - to-one pointing to just a single DataObjects (e.g. Painting.toArtist), and to-many pointing to a collection of DataObjects of the same base type (e.g. Artist.paintingArray).</P> |
| |
| <H3><A name="Relationships-ToOneRelationships"></A>To-One Relationships</H3> |
| |
| <P>"Get" methods for to-one relationships return the target DataObject. If the object is not in memory yet, it will be fetched on demand. Modifying to-one relationships is no different from modifying attributes - just a simple call to a "set" method:</P> |
| <DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> |
| <PRE class="code-java">Painting painting; |
| |
| <SPAN class="code-comment">// obtain artist <SPAN class="code-keyword">for</SPAN> a given painting |
| </SPAN>Artist originalArtist = painting.getToArtist(); |
| |
| <SPAN class="code-comment">// replace with a <SPAN class="code-keyword">new</SPAN> artist |
| </SPAN>Artist newArtist = (Artist)context.createAndRegisterNewObject(Artist.class); |
| painting.setToArtist(newArtist); |
| |
| <SPAN class="code-comment">// or remove Artist at all... |
| </SPAN><SPAN class="code-comment">// painting.setToArtist(<SPAN class="code-keyword">null</SPAN>);</SPAN> |
| </PRE> |
| </DIV></DIV> |
| <DIV class="panelMacro"><TABLE class="infoMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="http://cayenne.apache.org/docs/1.2/images/icons/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD>When adding or removing an object from any kind of relationship, Cayenne will locate and modify an existing reverse relationship as appropriate.</TD></TR></TABLE></DIV> |
| |
| <H3><A name="Relationships-ToManyRelationships"></A>To-Many Relationships</H3> |
| |
| <P>"Get" methods for to-many relationships return Lists of DataObjects. Just like individual DataObjects, such lists are also resolved on demand (e.g. when a user tries to read an element from the list). For modification there are special "addTo..." and "removeFrom..." methods:</P> |
| <DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> |
| <PRE class="code-java">Artist artist; |
| |
| <SPAN class="code-comment">// obtain a list of paintings |
| </SPAN>List paintings = artist.getPaintingArray(); |
| |
| <SPAN class="code-comment">// remove the first painting |
| </SPAN><SPAN class="code-keyword">if</SPAN>(paintings.size() > 0) { |
| Painting firstPainting = (Painting)paintings.get(0); |
| artist.removeFromPaintingArray(firstPainting); |
| } |
| |
| <SPAN class="code-comment">// add a <SPAN class="code-keyword">new</SPAN> painting |
| </SPAN>Painting newPainting = (Painting)context.createAndRegisterNewObject(Painting.class); |
| artist.addToPaintingArray(newPainting); |
| </PRE> |
| </DIV></DIV> |
| <DIV class="panelMacro"><TABLE class="infoMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="http://cayenne.apache.org/docs/1.2/images/icons/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD>While to-many relationships in Cayenne are represented by Lists, they are really ordered Sets, as they are not allowed to contain the same object more than once.</TD></TR></TABLE></DIV> |
