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