DataObject


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.cache.Cacheable;
68  import com.jcorporate.expresso.core.db.DBException;
69  import org.apache.oro.text.regex.Pattern;
70  
71  import java.util.ArrayList  ;
72  import java.util.Map  ;
73  
74  /**
75   * This interface represents the basic needs of a dataobject, namely to
76   * add, update and delete itself, set it's own fields, and deal with things
77   * accordingly
78   * <p>It is currently  considered <b><i>BETA</i></b>
79   * code at this time.  It's intention is to provide a refactoring launching point.  Until
80   * then it is recommended that by and large you use the DBObject class directly
81   * unless there is a specific feature that the DataObject interface provides that
82   * you need.  However, be forewarned that the interface <b>will</b> change.  For example,
83   * Exceptions will eventually be refactored from DBExceptions to DataExceptions. </p>
84   *
85   * @author Michael Rimov
86   * @since Expresso 5.0
87   */
88  public interface DataObject extends Cacheable, ContextNested {
89  
90  
91      /**
92       * Constant describing that this dbobject is new.
93       */
94      static final String   STATUS_NEW = "NEW";
95  
96      /**
97       * Status constant indicating that this dbobject currently reflects what's
98       * in the database back end.
99       */
100     static final String   STATUS_CURRENT = "CURRENT";
101 
102     /**
103      * Status constant indicating that this dbobject has been modified and
104      * does not match the back-end database.
105      */
106     static final String   STATUS_UPDATED = "UPDATED";
107 
108     /**
109      * Status indicating that this DBObject has been deleted.
110      */
111     static final String   STATUS_DELETED = "DELETED";
112 
113 
114     /**
115      * Returns the object embedded within the field keyed by the fieldName
116      * parameter.  The DataField object maintains metadata and other key items
117      * about the field.  Its state should not be messed with by the typical program.
118      *
119      * @param fieldName The name of the field to get
120      * @return The object if it isn't null for the data value or null.
121      * @throws DBException upon error
122      */
123     DataField getDataField(String   fieldName) throws DBException;
124 
125 
126     /**
127      * Retrieve the database object's metadata.  Metadata is a description of the
128      * database object, so it contains static information such as as description,
129      * field names, field types.  Etc.
130      * <p>For implementers of this interface:  It is best to store the metadata
131      * somewhere rather than recreating it each and every time.  For low-memory
132      * requirements, a WeakHashMap is recommended</p>
133      *
134      * @return a built DataObjectMetaData for this database object
135      */
136     DataObjectMetaData getMetaData();
137 
138     /**
139      * Retrieves the metadata for a particular field name
140      *
141      * @param fieldName The name of the field to retrieve the metadata for.
142      * @return <?ode>DataFieldMetaData</code> the metadata associated with this
143      *         field.
144      * @throws IllegalArgumentException if the fieldName does not exist.
145      */
146     DataFieldMetaData getFieldMetaData(String   fieldName);
147 
148 
149     /**
150      * Directly gets the DataField Data without having to deal with the DataField
151      * itself
152      *
153      * @param fieldName the name of the field to get
154      * @return Object or null.
155      */
156     Object   get(String   fieldName) throws DataException;
157 
158     /**
159      * Directly sets the field value without getting the datafield object
160      *
161      * @param fieldName the name of the field to set
162      * @param o         the object value to set it to.
163      */
164     void set(String   fieldName, Object   o) throws DataException;
165 
166     /**
167      * Sets the fields of this object with the default values defined in
168      * the metadata.  The behavior of this function is such that it only
169      * populates fields if there is no current value set.  This is
170      * the same behavior that existed previously in DefaultAutoElement.
171      *
172      * @throws DataException upon setField error.
173      * @since Expresso 5.6
174      */
175     void setFieldsWithDefaults() throws DataException;
176 
177     /**
178      * Checks to see if two data objects are equal.  This is extremely important
179      * in conflict resolution.
180      *
181      * @param otherObject the other object to compare to.
182      * @return true if the two objects are considered equal
183      */
184     boolean equals(Object   otherObject);
185 
186     /**
187      * Adds the record to the defined data source.
188      */
189     void add() throws DBException;
190 
191 
192     /**
193      * Updates the record to the defined datasource
194      */
195     void update() throws DBException;
196 
197     /**
198      * Deletes this defined record.
199      */
200     void delete() throws DBException;
201 
202 
203     /**
204      * Clears all currently loaded fields
205      */
206     void clear() throws DBException;
207 
208 
209     /**
210      * Returns the name of the physical database that we're talking with.  This
211      * is opposed to getDataContext() which returns the security context as well.
212      * getMappedDataContext() is strictly used to get at the low level database
213      * connection.
214      *
215      * @return java.lang.String... the context we've mapped to.
216      */
217     String   getMappedDataContext();
218 
219 
220     /**
221      * Set an attribute. Attributes are temporary (e.g. not stored in the DBMS) values
222      * associated with this particular DB object instance.
223      *
224      * @param attributeName  The name of the attribute being defined
225      * @param attributeValue The object to store under this attribute name
226      */
227     void setAttribute(String   attributeName, Object   attributeValue);
228 
229     /**
230      * Return an "attribute". Attributes are temporary (e.g. not stored in the DBMS)
231      * values associated with this particular DB object instance.
232      *
233      * @param attributeName The attribute name to check
234      * @return the object associated with this attribute
235      */
236     Object   getAttribute(String   attributeName);
237 
238     /**
239      * Returns a <b>Read Only</b> Map containing all the current attributes set
240      * for this particular data object instance.
241      *
242      * @return Read Only <code>java.util.Map</code>
243      */
244     Map   getAllAttributes();
245 
246 
247     /**
248      * Retrieve the field value as a String
249      *
250      * @param fieldName the name of the field to retrieve
251      * @return Object or null if the field was null
252      * @throws DBException              upon error
253      * @throws IllegalArgumentException if fieldname is invalid
254      */
255     String   getField(String   fieldName) throws DBException;
256 
257     /**
258      * Use this function to acquire the Executor interface that is associated
259      * with this data object
260      *
261      * @return DataExecutorInterface or null if no Executor has been associated
262      *         with this object
263      */
264     DataExecutorInterface getExecutor();
265 
266     /**
267      * Use this function to acquire the DataQueryInterface that is associated
268      * with this data object [Currently unsupported]
269      *
270      * @return DataQueryInterface or null if no QueryInterface has been
271      *         associated with this object
272      */
273     DataQueryInterface getQueryInterface();
274 
275     /**
276      * Check that a given value is valid for a given field.
277      * This method is overriden by specific DBObjects to do their own field-level
278      * validations - they should also call super in order to do the
279      * standard stuff. Every field is automatically checked by this method before the
280      * database is updated.
281      *
282      * @param fieldName  Name of the field to verify
283      * @param fieldValue Value of the field to be evaluated
284      * @throws DBException If the value is not valid
285      */
286     void checkField(String   fieldName, String   fieldValue) throws DBException;
287 
288 
289     /**
290      * Retrieve the status code of the dataobject.
291      *
292      * @return java.lang.String
293      */
294     String   getStatus();
295 
296 
297     /**
298      * Sets the status of the object.
299      *
300      * @param statusValue the new status code.
301      */
302     void setStatus(String   statusValue);
303 
304     /**
305      * Retrieve a list of valid value object for this particular dbobject
306      *
307      * @param fieldName name of the field to retrieve the list for.
308      * @return java.util.List of valid values
309      * @throws DBException upon error
310      */
311     java.util.List   getValidValuesList(String   fieldName) throws DBException;
312 
313 
314     /**
315      * Sets the DataObject's locale
316      *
317      * @param newLocale the New locale object
318      */
319     void setLocale(java.util.Locale   newLocale);
320 
321     /**
322      * Retrieve the DBObject's current locale
323      *
324      * @return java.util.Locale
325      */
326     java.util.Locale   getLocale();
327 
328 
329     /**
330      * Specify a maximum number of records to be retrieved in any subsequent
331      * searchAndRetrieve() call. Records will be retrieved (in the specified
332      * sort order) until the specified maximum is reached, then the remainder
333      * of the result set is discarded. Specifying zero indicates that all
334      * records are to be retrieved.
335      *
336      * @param newMax The maximum number of records to retrieve.
337      * @throws DBException If the max number is less than 0
338      */
339     void setMaxRecords(int newMax) throws DBException;
340 
341 
342     /**
343      * A DB Object can be told to only retrieve a certain number of records. If a
344      * "max records" value has been specified, this method provides access to it.
345      *
346      * @return The maximum number of records that should be retrieved, or zero
347      *         if no max has been set
348      */
349     int getMaxRecords();
350 
351 
352     /**
353      * Specifies the number of records that should be skipped over
354      * before any data from the <code>ResultSet</code>
355      * is retrieved in any subsequent
356      * searchAndRetrieve() call. Records will be skipped over (in the specified
357      * sort order) until the record counts is equal to or greater
358      * than the offset record. Specifying zero indicates that no
359      * records should be skipped over and the
360      * <code>ResultSet</code> immediately from the start.
361      *
362      * @param newOffset The maximum number of records to retrieve.
363      * @throws DBException If the max number is less than 0
364      *                     <p/>
365      *                     author Peter Pilgrim <peterp  at  xenonsoft dot demon dot co dot  uk>
366      */
367     void setOffsetRecord(int newOffset) throws DBException;
368 
369 
370     /**
371      * Gets the number of records that be skipped. The offset records.
372      * A DB Object can be told to skip a certain number of
373      * records, before reading records from the <code>ResultSet</code>.
374      * <p/>
375      * author Peter Pilgrim, Thu Jun 21 10:30:59 BST 2001
376      *
377      * @return The maximum number of records that should be
378      *         skipped over before reading the data records.
379      * @see #setOffsetRecord(int)
380      */
381     int getOffsetRecord();
382 
383     /**
384      * Performs a datasource search so that the criteria set in the DataObject
385      * is used.
386      *
387      * @param sortOrder A pipe delimited string specifying the field(s) to be sorted upon.
388      *                  May be a single field without any pipes.
389      * @return <code>java.util.List</code> of objects.  May be an empty list if no
390      *         objects were found.
391      * @throws DBException upon error performing the search
392      */
393     ArrayList   searchAndRetrieveList(String   sortOrder) throws DBException;
394 
395     /**
396      * Performs a datasource search so that the criteria set in the DataObject
397      * is used.  There is no specified sort order for this version of the method
398      *
399      * @return <code>java.util.List</code> of objects.  May be an empty list if no
400      *         objects were found.
401      * @throws DBException upon error performing the search
402      */
403     ArrayList   searchAndRetrieveList() throws DBException;
404 
405 
406     /**
407      * Finds a single record based upon the criteria specified by the <code>DataTransferObject</code>
408      *
409      * @return boolean true if a record was found, and the <i>criteria</i> parameter
410      *         is filled with the first data object found.
411      * @throws DBException upon error performing the search
412      */
413     boolean find() throws DBException;
414 
415     /**
416      * Just like find, but only retrieves the count, not the records themselves.
417      *
418      * @return integer Count of the records matching the criteria
419      * @throws DBException If the search could not be completed
420      */
421     int count() throws DBException;
422 
423     /**
424      * Sets the DataObject's global mask
425      *
426      * @param newGlobalMask the New global mask object
427      */
428     void setGlobalMask(Pattern newGlobalMask);
429 
430     /**
431      * Retrieve the DBObject's current global mask
432      *
433      * @return String
434      */
435     Pattern getGlobalMask();
436 
437     /**
438      * Return boolean if the data object has a mask set
439      *
440      * @return True if the data object mask is set, else false if it is not
441      */
442     boolean isGlobalMasked();
443 }
444
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags