Java > Open Source Codes > com > jcorporate > expresso > core > dataobjects > DataObjectMetaData


1 /* ====================================================================
2 * The Jcorporate Apache Style Software License, Version 1.2 05-07-2002
3 *
4 * Copyright (c) 1995-2002 Jcorporate Ltd. All rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions
8 * are met:
9 *
10 * 1. Redistributions of source code must retain the above copyright
11 * notice, this list of conditions and the following disclaimer.
12 *
13 * 2. Redistributions in binary form must reproduce the above copyright
14 * notice, this list of conditions and the following disclaimer in
15 * the documentation and/or other materials provided with the
16 * distribution.
17 *
18 * 3. The end-user documentation included with the redistribution,
19 * if any, must include the following acknowledgment:
20 * "This product includes software developed by Jcorporate Ltd.
21 * (http://www.jcorporate.com/)."
22 * Alternately, this acknowledgment may appear in the software itself,
23 * if and wherever such third-party acknowledgments normally appear.
24 *
25 * 4. "Jcorporate" and product names such as "Expresso" must
26 * not be used to endorse or promote products derived from this
27 * software without prior written permission. For written permission,
28 * please contact info@jcorporate.com.
29 *
30 * 5. Products derived from this software may not be called "Expresso",
31 * or other Jcorporate product names; nor may "Expresso" or other
32 * Jcorporate product names appear in their name, without prior
33 * written permission of Jcorporate Ltd.
34 *
35 * 6. No product derived from this software may compete in the same
36 * market space, i.e. framework, without prior written permission
37 * of Jcorporate Ltd. For written permission, please contact
38 * partners@jcorporate.com.
39 *
40 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
41 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
42 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
43 * DISCLAIMED. IN NO EVENT SHALL JCORPORATE LTD OR ITS CONTRIBUTORS
44 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
45 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
46 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
47 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
48 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
49 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
50 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
51 * SUCH DAMAGE.
52 * ====================================================================
53 *
54 * This software consists of voluntary contributions made by many
55 * individuals on behalf of the Jcorporate Ltd. Contributions back
56 * to the project(s) are encouraged when you make modifications.
57 * Please send them to support@jcorporate.com. For more information
58 * on Jcorporate Ltd. and its products, please see
59 * <http://www.jcorporate.com/>.
60 *
61 * Portions of this software are based upon other open source
62 * products and are subject to their respective licenses.
63  */
64
65 package com.jcorporate.expresso.core.dataobjects;
66
67 import com.jcorporate.expresso.core.db.DBException;
68
69 import java.util.ArrayList ;
70 import java.util.HashMap ;
71 import java.util.Set ;
72
73 /**
74  * This interface contains the "definition" of the DBObject, while the DBObject
75  * itself contains only the data itself.
76  * One DBObjectDef object is stored in a static HashMap in the DBObject class,
77  * and is looked up and referenced for all definitions of the structure of the given object.
78  * <p/>
79  * since this class is not threadsafe for adding information, it is imperitive
80  * that all information addition, typically done when the first instance
81  * of a DBObject is instantiated, is done in a synchronized context.
82  *
83  * @author Michael Rimov
84  */
85 public interface DataObjectMetaData extends java.io.Serializable {
86
87     /**
88      * Retreive the default value of a particular field for when it is first
89      * instantiated
90      *
91      * @param fieldName the name of the field to retrieve
92      * @return java.lang.String
93      */
94     public String getDefaultValue(String fieldName);
95
96
97     /**
98      * Retrieve a list of all the detail objects
99      *
100      * @return java.util.Set
101      */
102     public Set getDetailSet();
103
104     /**
105      * Retrieve the local key fields.
106      *
107      * @param detailName the name of the detail dbobject
108      * @return java.lang.String
109      */
110     public String getDetailFieldsLocal(String detailName);
111
112     /**
113      * Retrieve the foreign key fields
114      *
115      * @param detailName the name of the detail dbobject
116      * @return java.lang.String
117      */
118     public String getDetailFieldsForeign(String detailName);
119
120
121     /**
122      * Returns whether the field allows null values or not.
123      *
124      * @param fieldName name of the field
125      * @return true if the field allows null
126      */
127     public boolean isAllowsNull(String fieldName) throws DBException;
128
129
130     /**
131      * Removes an attribute from the field.
132      *
133      * @param fieldName the name of the field to remove the attribute
134      * @param attribName the attribute name to remove
135      */
136     public void removeAttribute(String fieldName, String attribName);
137
138     /**
139      * @param fieldName the name of the field to set the attribute for
140      * @param attribName the name of the attribute to set
141      * @param attribValue the attribute to set
142      */
143     public void setAttribute(String fieldName, String attribName, Object attribValue)
144             throws DBException;
145
146     /**
147      * Gets an <code>Object</code> attribute from the field's metatdata
148      *
149      * @param fieldName the name of the field for the attribute
150      * @param attribName the name of the attribute
151      * @return java.lang.Object
152      */
153     public Object getAttribute(String fieldName, String attribName)
154             throws DBException;
155
156
157     /**
158      * Retrieve all the attributes so you can iterate through them.
159      *
160      * @param fieldName the name of the field to get all the attributes
161      * @return java.util.Set of all attributes.
162      */
163     public java.util.Set getAllAttributes(String fieldName);
164
165
166     /**
167      * Disable change logging of all objects of this type
168      */
169     public void disableLogging();
170
171     /**
172      * Enable logging of changes to this object. Change logging writes an entry to
173      * the ChangeLog object every time an add, update, or delete is made to this
174      * object. It is used to track important tables, such as user information,
175      * account information, etc.
176      */
177     public void enableLogging();
178
179
180     /**
181      * Retrieves whether or not change logging is enabled for a particular
182      * data object
183      *
184      * @return boolean true if logging is enabled.
185      */
186     public boolean isLoggingEnabled();
187
188     /**
189      * Check if a certain name is a field (of any kind) in this DBOBject
190      * since SQL is case insensitive, ignore case of field name for match,
191      * this method takes longer, so use isField if the field name is known precisely
192      *
193      * @param fieldName the name of the field to check
194      * @return internal format for field name if matched, or null if no match
195      */
196     public String isFieldIgnoreCase(String fieldName);
197
198     /**
199      * Check if a certain name is a field (of any kind) in this DBOBject
200      *
201      * @param fieldName the name of the field to check
202      * @return true if the field name exists
203      */
204     boolean isField(String fieldName);
205
206     /**
207      * Return the "allFields" Hashtable, which contains all of the DBField objects
208      * that make up this DB object.
209      *
210      * @return java.util.HashMap
211      */
212     public HashMap getAllFieldsMap();
213
214
215     /**
216      * Return the "allKeys" hash, containing the DBField objects that make up
217      * the primary key for this db object.
218      *
219      * @return java.util.HashMap
220      */
221     public HashMap getAllKeysMap();
222
223
224     /**
225      * return the current object's character set
226      *
227      * @return java.lang.String
228      */
229     public String getCharset();
230
231     /**
232      * Get the current Cache size of this object. or -2 if it hasn't been
233      * defined yet.
234      *
235      * @return current cache size value.
236      */
237     public int getCacheSize();
238
239     /**
240      * Sets the cache size for this DBObject
241      *
242      * @param newValue the new value. Must be >= -2
243      * @throws IllegalArgumentException if newValue < -2
244      */
245     public void setCacheSize(int newValue);
246
247
248     /**
249      * Return a description of this database object. If no explicit description has
250      * been set, return the class name.
251      *
252      * @return A string describing this database object
253      */
254     public String getDescription();
255
256     /**
257      * Return the long description of a field, if available
258      *
259      * @param fieldName The name of the field
260      * @return String: The long description of the field (user-readable)
261      * @throws DBException If there is no such field
262      */
263     public String getDescription(String fieldName)
264             throws DBException;
265
266     /**
267      * Retrieve an localized description as per the locale defined for the
268      * 'client'
269      *
270      * @param l the Locale to use. If null, will use the System default Locale
271      * @param fieldName the name of the field to retrieve the i18n'ized description
272      * for.
273      * @return the localized description of the field name
274      */
275     public String getDescription(java.util.Locale l, String fieldName);
276
277     /**
278      * Get the DBField object specified by the fieldname
279      *
280      * @param fieldName the name of the field to retrieve
281      * @return <code>DBField</code> object
282      */
283     public DataFieldMetaData getFieldMetadata(String fieldName);
284
285
286     /**
287      * Get a list of all of the fields in this object This is threadsafe in that
288      * it makes a new copy of the fieldNamesInOrder ArrayList
289      *
290      * @return An array of all of the fieldNames in this object
291      */
292     public ArrayList getFieldListArray();
293
294
295     /**
296      * Get a list of all of the names of the key fields in this object
297      *
298      * @return An ArrayList of all of the names of the key fields
299      */
300     public ArrayList getKeyFieldListArray();
301
302     /**
303      * Return the length of a field
304      *
305      * @param fieldName The name of the field
306      * @return String: The length of the field
307      * @throws DBException If there is no such field in this object
308      */
309     public String getLength(String fieldName) throws DBException;
310
311
312     /**
313      * Return the length of a field as an integer
314      *
315      * @param fieldName The name of the field
316      * @return integer: The length of the field
317      * @throws DBException If there is no such field in this object
318      */
319     public int getLengthInt(String fieldName) throws DBException;
320
321     /**
322      * Retrieve the precision of a particular field
323      *
324      * @param fieldName The name of the field
325      * @return integer for demcimal precision of the field
326      */
327     public int getPrecision(String fieldName)
328             throws DBException;
329
330
331     /**
332      * Get a field's lookup object - this is the name of another database
333      * object that can be used to look up valid values for this object. The lookup
334      * object for a field is set in the db objects setupFields method, and is used
335      * by the DBMaint servlet to provide automatic lookup links for fields.
336      *
337      * @param fieldName Field name to check
338      * @return String specifying the className of the lookup object
339      * @throws DBException If the specified field does not exist.
340      */
341     public String getLookupObject(String fieldName)
342             throws DBException;
343
344
345     /**
346      * When you get a lookup object, to perform a complete mapping between the
347      * two, you need to know what field name in the remote object maps to this
348      * field.
349      *
350      * @param fieldName the name of the field to look up.
351      * @return java.lang.String or null if there is no lookup field
352      * @throws IllegalArgumentException if the field name does not exist
353      */
354     public String getLookupField(String fieldName);
355
356     /**
357      * Get the name of this object
358      *
359      * @return String The database object name, or the table name if none
360      * has been assigned
361      */
362     public String getName();
363
364
365     /**
366      * Return the type of a field - this method returns the internal Expresso type
367      *
368      * @param fieldName The name of the field
369      * @return String: The type of the field
370      * @throws DBException If there is no such field in this object
371      */
372     public String getType(String fieldName)
373             throws DBException;
374
375
376     /**
377      * This method will return a boolean true if the field is defined in the DBOBject,
378      * false otherwise.
379      * Creation date: (8/8/00 11:04:32 AM)
380      *
381      * @param fieldName java.lang.String
382      * @return boolean
383      */
384     public boolean hasField(String fieldName);
385
386
387     /**
388      * Method called to determine if a particular field is multi-valued,
389      * that is does it have a set of specific values and descriptions
390      *
391      * @param fieldName Name of the field
392      * @return boolean True if the field is multi-valued, false if not
393      * @throws DBException If there is no such field
394      */
395     public boolean isMultiValued(String fieldName)
396             throws DBException;
397
398
399     /**
400      * Is a given field readOnly - these fields are not offered for entry
401      * when a form is produced by the generic database maintenance servlet
402      *
403      * @param fieldName name of the field to check
404      * @return true of the field is "read only", false if it is not
405      * @throws DBException Ff there is no such field
406      */
407     public boolean isReadOnly(String fieldName)
408             throws DBException;
409
410     /**
411      * Is a given field 'secret' - these fields are not shown
412      * when a list is produced by the generic database maintenance servlet (DBMaint).
413      * This means that only users with update permission to the record can see the
414      * value of the specified field.
415      *
416      * @param fieldName The name of the field to check
417      * @return True if the field is 'secret', false if it is not
418      * @throws DBException If there is no such field.
419      */
420     public boolean isSecret(String fieldName)
421             throws DBException;
422
423     /**
424      * Is a given field virtual? A virtual field is not stored in the target table
425      * for this object - it may be computed, or stored in another table.
426      *
427      * @param fieldName The name of the field to check
428      * @return True of the field is virtual, false if it is not
429      * @throws DBException If there is no such field
430      */
431     public boolean isVirtual(String fieldName)
432             throws DBException;
433
434
435     /**
436      * Turn on or off the facility to verify that when an update is made that at
437      * least one record got updated. If this flag is on, and no records get updated,
438      * the update() method throws an Exception. Note that for some databases, if the
439      * existing record is not changed (e.g. it was already identical to what
440      * was being updated) this counts "no update" (notably, mySQL does this).
441      *
442      * @param newFlag True to turn on checking, false to turn it off
443      */
444     public void setCheckZeroUpdate(boolean newFlag);
445
446
447     /**
448      * Retrieves whether or not checkZeroUpdate is enabled for this data object
449      *
450      * @return true if checkZeroUpdate() is enabled
451      */
452     public boolean checkZeroUpdate();
453
454
455     /**
456      * Retrieve the schema object's class name associated with this data object
457      *
458      * @return the className of the schema associated with this DBObject
459      */
460     public String getSchema();
461
462     /**
463      * <p>This convenience method iterates through all the
464      * fields belonging to this <code>DBObject</code>
465      * returns an array of field names ( <code>String</code> ).</p>
466      *
467      * @return String array of all field names in this object.
468      * @author Peter Pilgrim <peter.pilgrim@db.com>
469      * @see #getFieldList()
470      */
471     public String [] getFields();
472
473
474     /**
475      * Retrieve the table description in a localized way. If l == null, the
476      * function uses the system locale to generate the value. If unable to
477      * locate the key in the message bundle, the key becomes the return value.
478      *
479      * @param l the Locale to use for rendering the table description
480      * @return java.lang.String
481      */
482     public String getDescription(java.util.Locale l);
483 }
484

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags