View Javadoc

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