View Javadoc

1   /*
2    * Copyright 2005 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at 
7    * 
8    *     http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software 
11   * distributed under the License is distributed on an "AS IS" BASIS, 
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
13   * See the License for the specific language governing permissions and 
14   * limitations under the License.
15   */
16  
17  package org.apache.jdo.model.jdo;
18  
19  import org.apache.jdo.model.ModelException;
20  
21  /***
22   * JDORelationship is the super interface for all interfaces representing 
23   * JDO relationship metadata of a managed field of a persistence-capable class.
24   * 
25   * @author Michael Bouschen
26   */
27  public interface JDORelationship 
28      extends JDOElement 
29  {
30      /***
31       * Constant representing the cardinality zero used for lower and upper 
32       * bounds.
33       */
34      public static final int CARDINALITY_ZERO = 0;
35  
36      /***
37       * Constant representing the cardinality one used for lower and upper bounds.
38       */
39      public static final int CARDINALITY_ONE = 1;
40  
41      /***
42       * Constant representing the cardinality n used for lower and upper bounds.
43       */
44      public static final int CARDINALITY_N = java.lang.Integer.MAX_VALUE;
45  
46      /*** 
47       * Get the lower cardinality bound for this relationship element.
48       * @return the lower cardinality bound
49       */
50      public int getLowerBound();
51  
52      /*** 
53       * Set the lower cardinality bound for this relationship element.
54       * @param lowerBound an integer indicating the lower cardinality bound
55       * @exception ModelException if impossible
56       */
57      public void setLowerBound(int lowerBound)
58          throws ModelException;
59      
60      /*** 
61       * Get the upper cardinality bound for this relationship element.
62       * @return the upper cardinality bound
63       */
64      public int getUpperBound();
65  
66      /*** 
67       * Set the upper cardinality bound for this relationship element.
68       * @param upperBound an integer indicating the upper cardinality bound
69       * @exception ModelException if impossible
70       */
71      public void setUpperBound(int upperBound)
72          throws ModelException;
73  
74      /*** 
75       * Get the declaring field of this JDORelationship.
76       * @return the field that owns this JDORelationship, or <code>null</code>
77       * if the element is not attached to any field
78       */
79      public JDOField getDeclaringField();
80  
81      /*** 
82       * Set the declaring field of this JDORelationship.
83       * @param declaringField the declaring field of this relationship element
84       * @exception ModelException if impossible
85       */
86      public void setDeclaringField(JDOField declaringField)
87          throws ModelException;
88  
89      /***
90       * Get the JDOClass corresponding to the type or element of this 
91       * relationship.
92       * @return the related class
93       */
94      public JDOClass getRelatedJDOClass();
95  
96      /*** 
97       * Get the mappedBy relationship. If there is no mappedBy relationship
98       * set, the method checks the mappedBy name as specified in the declaring
99       * field and resolves the relationship. The method return
100      * <code>null</code> if there is no mappedBy relationship set and there
101      * is no mappedBy name specified on the declaring field.
102      * @return the mappedBy relationship if available; <code>null</code>
103      * otherwise.
104      */
105     public JDORelationship getMappedBy();
106 
107     /***
108      * Set the mappedBy relationship for this relationship. This method
109      * automatically updates the mappedBy name of the declaring field of this
110      * relationship.
111      * @param mappedBy the mappedBy relationship.
112      * @exception ModelException if impossible
113      */
114     public void setMappedBy(JDORelationship mappedBy) throws ModelException;
115 
116     /*** 
117      * Get the relative name of the inverse relationship field for this
118      * relationship.  In the case of two-way relationships, the two
119      * relationships involved are inverses of each other.  If this
120      * relationship element does not participate in a two-way relationship,
121      * this returns <code>null</code>.  Note that it is possible to have
122      * this method return a value, but because of the combination of
123      * related class and lookup, there may be no corresponding
124      * JDORelationship which can be found.
125      * @return the relative name of the inverse JDORelationship
126      * @see #getInverseRelationship
127      */
128     public String getInverseRelationshipName();
129 
130     /***
131      * Get the inverse JDORelationship in the case of a two-way relationship.
132      * @return the inverse relationship
133      */
134     public JDORelationship getInverseRelationship();
135 
136     /***
137      * Set the inverse JDORelationship in the case of a two-way relationship.
138      * The two relationship elements involved are set as inverses of each 
139      * other and the old inverse is unset.
140      * @param inverseRelationship the inverse relationship
141      * @exception ModelException if impossible
142      * @deprecated - call setMappedBy instead
143      */
144     public void setInverseRelationship(JDORelationship inverseRelationship)
145         throws ModelException;
146 
147     /***
148      * Determines whether this side of a two-way relationship is the
149      * owning side.
150      * @return <code>true</code> if this side is the owning side;
151      * <code>false</code> otherwise. 
152      */
153     public boolean isOwner();
154 
155     /***
156      * Determines whether this JDORelationship represents a reference
157      * relationship or not. A return of <code>true</code> means this
158      * JDORelationship is a JDOReference instance.
159      * @return <code>true</code> if this JDORelationship represents a
160      * reference relationship; <code>false</code> otherwise.
161      */
162     public boolean isJDOReference();
163     
164     /***
165      * Determines whether this JDORelationship represents a collection
166      * relationship or not. A return of <code>true</code> means this
167      * JDORelationship is a JDOCollection instance.
168      * @return <code>true</code> if this JDORelationship represents a
169      * collection relationship; <code>false</code> otherwise.
170      */
171     public boolean isJDOCollection();
172 
173     /***
174      * Determines whether this JDORelationship represents an array
175      * relationship or not. A return of <code>true</code> means this
176      * JDORelationship is a JDOArray instance.
177      * @return <code>true</code> if this JDORelationship represents an 
178      * array relationship; <code>false</code> otherwise.
179      */
180     public boolean isJDOArray();
181 
182     /***
183      * Determines whether this JDORelationship represents a map 
184      * relationship or not. A return of <code>true</code> means this
185      * JDORelationship is a JDOMap instance.
186      * @return <code>true</code> if this JDORelationship represents a
187      * map relationship; <code>false</code> otherwise.
188      */
189     public boolean isJDOMap();
190 
191 }