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  import org.apache.jdo.model.java.JavaField;
21  import org.apache.jdo.model.java.JavaType;
22  
23  
24  /***
25   * A JDOField instance represents the JDO metadata of a managed field 
26   * of a persistence-capable class.
27   *
28   * @author Michael Bouschen
29   */
30  public interface JDOField 
31      extends JDOMember 
32  {
33      /***
34       * Get the persistence modifier of this JDOField.
35       * @return the persistence modifier, one of 
36       * {@link PersistenceModifier#UNSPECIFIED}, 
37       * {@link PersistenceModifier#NONE}, 
38       * {@link PersistenceModifier#PERSISTENT},
39       * {@link PersistenceModifier#TRANSACTIONAL},
40       * {@link PersistenceModifier#POSSIBLY_PERSISTENT}.
41       */
42      public int getPersistenceModifier();
43  
44      /*** 
45       * Set the persistence modifier for this JDOField.
46       * @param persistenceModifier an integer indicating the persistence 
47       * modifier, one of: {@link PersistenceModifier#UNSPECIFIED}, 
48       * {@link PersistenceModifier#NONE}, 
49       * {@link PersistenceModifier#PERSISTENT},
50       * {@link PersistenceModifier#TRANSACTIONAL},
51       * {@link PersistenceModifier#POSSIBLY_PERSISTENT}.
52       * @exception ModelException if impossible
53       */
54      public void setPersistenceModifier (int persistenceModifier)
55          throws ModelException;
56      
57      /*** 
58       * Determines whether this JDOField is a key field or not.  
59       * @return <code>true</code> if the field is a key field, 
60       * <code>false</code> otherwise
61       */
62      public boolean isPrimaryKey();
63  
64      /*** 
65       * Set whether this JDOField is a key field or not.
66       * @param primaryKey if <code>true</code>, the JDOField is marked 
67       * as a key field; otherwise, it is not
68       * @exception ModelException if impossible
69       */
70      public void setPrimaryKey(boolean primaryKey)
71          throws ModelException;
72  
73      /***
74       * Gets the null value treatment indicator of this JDOField.
75       * @return the null value treatment of this JDOField, one of 
76       * {@link NullValueTreatment#NONE}, {@link NullValueTreatment#EXCEPTION} or
77       * {@link NullValueTreatment#DEFAULT}
78       */
79      public int getNullValueTreatment();
80  
81      /***
82       * Sets the null value treatment indicator for this JDOField.
83       * @param nullValueTreament an integer indicating the null value treatment, 
84       * one of: {@link NullValueTreatment#NONE}, 
85       * {@link NullValueTreatment#EXCEPTION} or 
86       * {@link NullValueTreatment#DEFAULT}
87       * @exception ModelException if impossible
88       */
89      public void setNullValueTreatment(int nullValueTreament)
90          throws ModelException;
91  
92      /***
93       * Determines whether this JDOField is part of the default fetch group or 
94       * not.
95       * @return <code>true</code> if the field is part of the default fetch 
96       * group, <code>false</code> otherwise
97       */
98      public boolean isDefaultFetchGroup();
99  
100     /***
101      * Set whether this JDOField is part of the default fetch group or not.
102      * @param defaultFetchGroup if <code>true</code>, the JDOField is marked  
103      * as beeing part of the default fetch group; otherwise, it is not
104      * @exception ModelException if impossible
105      */
106     public void setDefaultFetchGroup(boolean defaultFetchGroup)
107         throws ModelException;
108 
109     /***
110      * Determines whether the field should be stored if possible as part of
111      * the instance instead of as its own instance in the datastore.
112      * @return <code>true</code> if the field is stored as part of the instance;
113      * <code>false</code> otherwise
114      */
115     public boolean isEmbedded();
116 
117     /***
118      * Set whether the field should be stored if possible as part of
119      * the instance instead of as its own instance in the datastore.
120      * @param embedded <code>true</code> if the field is stored as part of the 
121      * instance; <code>false</code> otherwise
122      * @exception ModelException if impossible
123      */
124     public void setEmbedded(boolean embedded)
125         throws ModelException;
126     
127     /***
128      * Determines whether this JDOField is serializable or not.  
129      * @return <code>true</code> if the field is serializable,
130      * <code>false</code> otherwise
131      */
132     public boolean isSerializable();
133 
134     /*** 
135      * Set whether this JDOField is serializable or not.
136      * @param serializable if <code>true</code>, the JDOField is serializable;
137      * otherwise, it is not
138      * @exception ModelException if impossible
139      */
140     public void setSerializable(boolean serializable)
141         throws ModelException;
142 
143     /*** 
144      * Get the name of the field specified in a mappedBy attribute in the
145      * metadata. The method returns <code>null</code> if the metadata for this
146      * field does not specify the mappedBy attribute.  Note that this 
147      * can be provided at the field level to help population of the model, 
148      * but should only be specified on a field that has a corresponding
149      * relationship.
150      * @return the mappedBy field name if available; <code>null</code>
151      * otherwise.
152      */
153     public String getMappedByName();
154 
155     /***
156      * Set the name of the field specified in a mappedBy attribute in the
157      * metadata.  Note that this can be provided at the field level to 
158      * help population of the model, but should only be specified on a 
159      * field that has a corresponding relationship.
160      * @param mappedByName the mappedBy field name.
161      * @exception ModelException if impossible
162      */
163     public void setMappedByName(String mappedByName) throws ModelException;
164 
165     /***
166      * Get the corresponding Java field representation for this JDOField.
167      * @return the corresponding Java field representation
168      */
169     public JavaField getJavaField();
170 
171     /***
172      * Sets the corresponding Java field representation for this JDOField.
173      * @param javaField the corresponding Java field representation
174      * @exception ModelException if impossible
175      */
176     public void setJavaField (JavaField javaField)
177         throws ModelException;
178 
179     /***
180      * Get the relationship information for this JDOField. The method 
181      * returns null if the field is not part of a relationship 
182      * (e.g. it is a primitive type field).
183      * @return relationship info of this JDOField or <code>null</code> if 
184      * this JDOField is not a relationship
185      */
186     public JDORelationship getRelationship();
187 
188     /***
189      * Set the relationship information for this JDOField.
190      * @param relationship the JDORelationship instance
191      * @exception ModelException if impossible
192      */
193     public void setRelationship(JDORelationship relationship)
194         throws ModelException;
195 
196     /***
197      * Creates and returns a new JDOReference instance. 
198      * This method automatically binds the new JDOReference to this JDOField. 
199      * It throws a ModelException, if this JDOField is already bound to 
200      * another JDORelationship instance. Otherwise the following holds true:
201      * <ul>
202      * <li> Method {@link #getRelationship} returns the new created instance
203      * <li> <code>this.getRelationship().getDeclaringField() == this</code>
204      * </ul> 
205      * @return a new JDOReference instance bound to this JDOField
206      * @exception ModelException if impossible
207      */
208     public JDOReference createJDOReference()
209         throws ModelException;
210 
211     /***
212      * Creates and returns a new JDOCollection instance. 
213      * This method automatically binds the new JDOCollection to this JDOField. 
214      * It throws a ModelException, if this JDOField is already bound to 
215      * another JDORelationship instance. Otherwise the following holds true:
216      * <ul>
217      * <li> Method {@link #getRelationship} returns the new created instance
218      * <li> <code>this.getRelationship().getDeclaringField() == this</code>
219      * </ul> 
220      * @return a new JDOCollection instance bound to this JDOField
221      * @exception ModelException if impossible
222      */
223     public JDOCollection createJDOCollection()
224         throws ModelException;
225 
226     /***
227      * Creates and returns a new JDOArray instance. 
228      * This method automatically binds the new JDOArray to this JDOField. 
229      * It throws a ModelException, if this JDOField is already bound to 
230      * another JDORelationship instance. Otherwise the following holds true:
231      * <ul>
232      * <li> Method {@link #getRelationship} returns the new created instance
233      * <li> <code>this.getRelationship().getDeclaringField() == this</code>
234      * </ul> 
235      * @return a new JDOArray instance bound to this JDOField
236      * @exception ModelException if impossible
237      */
238     public JDOArray createJDOArray()
239         throws ModelException;
240 
241     /***
242      * Creates and returns a new JDOMap instance. 
243      * This method automatically binds the new JDOMap to this JDOField. 
244      * It throws a ModelException, if this JDOField is already bound to 
245      * another JDORelationship instance. Otherwise the following holds true:
246      * <ul>
247      * <li> Method {@link #getRelationship} returns the new created instance
248      * <li> <code>this.getRelationship().getDeclaringField() == this</code>
249      * </ul> 
250      * @return a new JDOMap instance bound to this JDOField
251      * @exception ModelException if impossible
252      */
253     public JDOMap createJDOMap()
254         throws ModelException;
255 
256     /***
257      * Convenience method to check the persistence modifier from this JDOField.
258      * @return <code>true</code> if this field has the  
259      * {@link PersistenceModifier#PERSISTENT} modifier; <code>false</code> 
260      * otherwise
261      */
262     public boolean isPersistent();
263 
264     /***
265      * Convenience method to check the persistence modifier from this JDOField.
266      * @return <code>true</code> if this field has the  
267      * {@link PersistenceModifier#TRANSACTIONAL} modifier; <code>false</code> 
268      * otherwise
269      */
270     public boolean isTransactional();
271 
272     /***
273      * Convenience method to check the persistence modifier from this JDOField.
274      * A field is a managed field, if it has the persistence-modifier 
275      * {@link PersistenceModifier#PERSISTENT} or
276      * {@link PersistenceModifier#TRANSACTIONAL}.
277      * @return <code>true</code> if this field is a managed field; 
278      * <code>false</code> otherwise     
279      */
280     public boolean isManaged();
281 
282     /***
283      * Convenience method to check whether this field is a relationship field.
284      * @return <code>true</code> if this field is a relationship; 
285      * <code>false</code> otherwise
286      */
287     public boolean isRelationship();
288 
289     /***
290      * Convenience method to check whether this field represents a property.
291      * @return <code>true</code> if this field represents a property; 
292      * <code>false</code> otherwise
293      */
294     public boolean isProperty();
295 
296     /***
297      * Get the JavaType representation of the type of the field.
298      * @return JavaType representation of the type of this field.
299      */
300     public JavaType getType();
301 
302     /***
303      * Returns the absolute field number of this JDOField.
304      * @return the absolute field number
305      */
306     public int getFieldNumber();
307 
308     /***
309      * Returns the relative field number of this JDOField.
310      * @return the relative field number
311      */
312     public int getRelativeFieldNumber();
313 
314 }