001: /* ====================================================================
002: * The Jcorporate Apache Style Software License, Version 1.2 05-07-2002
003: *
004: * Copyright (c) 1995-2002 Jcorporate Ltd. All rights reserved.
005: *
006: * Redistribution and use in source and binary forms, with or without
007: * modification, are permitted provided that the following conditions
008: * are met:
009: *
010: * 1. Redistributions of source code must retain the above copyright
011: * notice, this list of conditions and the following disclaimer.
012: *
013: * 2. Redistributions in binary form must reproduce the above copyright
014: * notice, this list of conditions and the following disclaimer in
015: * the documentation and/or other materials provided with the
016: * distribution.
017: *
018: * 3. The end-user documentation included with the redistribution,
019: * if any, must include the following acknowledgment:
020: * "This product includes software developed by Jcorporate Ltd.
021: * (http://www.jcorporate.com/)."
022: * Alternately, this acknowledgment may appear in the software itself,
023: * if and wherever such third-party acknowledgments normally appear.
024: *
025: * 4. "Jcorporate" and product names such as "Expresso" must
026: * not be used to endorse or promote products derived from this
027: * software without prior written permission. For written permission,
028: * please contact info@jcorporate.com.
029: *
030: * 5. Products derived from this software may not be called "Expresso",
031: * or other Jcorporate product names; nor may "Expresso" or other
032: * Jcorporate product names appear in their name, without prior
033: * written permission of Jcorporate Ltd.
034: *
035: * 6. No product derived from this software may compete in the same
036: * market space, i.e. framework, without prior written permission
037: * of Jcorporate Ltd. For written permission, please contact
038: * partners@jcorporate.com.
039: *
040: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
041: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
042: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
043: * DISCLAIMED. IN NO EVENT SHALL JCORPORATE LTD OR ITS CONTRIBUTORS
044: * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
045: * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
046: * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
047: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
048: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
049: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
050: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
051: * SUCH DAMAGE.
052: * ====================================================================
053: *
054: * This software consists of voluntary contributions made by many
055: * individuals on behalf of the Jcorporate Ltd. Contributions back
056: * to the project(s) are encouraged when you make modifications.
057: * Please send them to support@jcorporate.com. For more information
058: * on Jcorporate Ltd. and its products, please see
059: * <http://www.jcorporate.com/>.
060: *
061: * Portions of this software are based upon other open source
062: * products and are subject to their respective licenses.
063: */
064:
065: package com.jcorporate.expresso.core.dataobjects;
066:
067: import com.jcorporate.expresso.core.cache.Cacheable;
068: import com.jcorporate.expresso.core.db.DBException;
069: import org.apache.oro.text.regex.Pattern;
070:
071: import java.util.ArrayList;
072: import java.util.Map;
073:
074: /**
075: * This interface represents the basic needs of a dataobject, namely to
076: * add, update and delete itself, set it's own fields, and deal with things
077: * accordingly
078: * <p>It is currently considered <b><i>BETA</i></b>
079: * code at this time. It's intention is to provide a refactoring launching point. Until
080: * then it is recommended that by and large you use the DBObject class directly
081: * unless there is a specific feature that the DataObject interface provides that
082: * you need. However, be forewarned that the interface <b>will</b> change. For example,
083: * Exceptions will eventually be refactored from DBExceptions to DataExceptions. </p>
084: *
085: * @author Michael Rimov
086: * @since Expresso 5.0
087: */
088: public interface DataObject extends Cacheable, ContextNested {
089:
090: /**
091: * Constant describing that this dbobject is new.
092: */
093: static final String STATUS_NEW = "NEW";
094:
095: /**
096: * Status constant indicating that this dbobject currently reflects what's
097: * in the database back end.
098: */
099: static final String STATUS_CURRENT = "CURRENT";
100:
101: /**
102: * Status constant indicating that this dbobject has been modified and
103: * does not match the back-end database.
104: */
105: static final String STATUS_UPDATED = "UPDATED";
106:
107: /**
108: * Status indicating that this DBObject has been deleted.
109: */
110: static final String STATUS_DELETED = "DELETED";
111:
112: /**
113: * Returns the object embedded within the field keyed by the fieldName
114: * parameter. The DataField object maintains metadata and other key items
115: * about the field. Its state should not be messed with by the typical program.
116: *
117: * @param fieldName The name of the field to get
118: * @return The object if it isn't null for the data value or null.
119: * @throws DBException upon error
120: */
121: DataField getDataField(String fieldName) throws DBException;
122:
123: /**
124: * Retrieve the database object's metadata. Metadata is a description of the
125: * database object, so it contains static information such as as description,
126: * field names, field types. Etc.
127: * <p>For implementers of this interface: It is best to store the metadata
128: * somewhere rather than recreating it each and every time. For low-memory
129: * requirements, a WeakHashMap is recommended</p>
130: *
131: * @return a built DataObjectMetaData for this database object
132: */
133: DataObjectMetaData getMetaData();
134:
135: /**
136: * Retrieves the metadata for a particular field name
137: *
138: * @param fieldName The name of the field to retrieve the metadata for.
139: * @return <\u0441ode>DataFieldMetaData</code> the metadata associated with this
140: * field.
141: * @throws IllegalArgumentException if the fieldName does not exist.
142: */
143: DataFieldMetaData getFieldMetaData(String fieldName);
144:
145: /**
146: * Directly gets the DataField Data without having to deal with the DataField
147: * itself
148: *
149: * @param fieldName the name of the field to get
150: * @return Object or null.
151: */
152: Object get(String fieldName) throws DataException;
153:
154: /**
155: * Directly sets the field value without getting the datafield object
156: *
157: * @param fieldName the name of the field to set
158: * @param o the object value to set it to.
159: */
160: void set(String fieldName, Object o) throws DataException;
161:
162: /**
163: * Sets the fields of this object with the default values defined in
164: * the metadata. The behavior of this function is such that it only
165: * populates fields if there is no current value set. This is
166: * the same behavior that existed previously in DefaultAutoElement.
167: *
168: * @throws DataException upon setField error.
169: * @since Expresso 5.6
170: */
171: void setFieldsWithDefaults() throws DataException;
172:
173: /**
174: * Checks to see if two data objects are equal. This is extremely important
175: * in conflict resolution.
176: *
177: * @param otherObject the other object to compare to.
178: * @return true if the two objects are considered equal
179: */
180: boolean equals(Object otherObject);
181:
182: /**
183: * Adds the record to the defined data source.
184: */
185: void add() throws DBException;
186:
187: /**
188: * Updates the record to the defined datasource
189: */
190: void update() throws DBException;
191:
192: /**
193: * Deletes this defined record.
194: */
195: void delete() throws DBException;
196:
197: /**
198: * Clears all currently loaded fields
199: */
200: void clear() throws DBException;
201:
202: /**
203: * Returns the name of the physical database that we're talking with. This
204: * is opposed to getDataContext() which returns the security context as well.
205: * getMappedDataContext() is strictly used to get at the low level database
206: * connection.
207: *
208: * @return java.lang.String... the context we've mapped to.
209: */
210: String getMappedDataContext();
211:
212: /**
213: * Set an attribute. Attributes are temporary (e.g. not stored in the DBMS) values
214: * associated with this particular DB object instance.
215: *
216: * @param attributeName The name of the attribute being defined
217: * @param attributeValue The object to store under this attribute name
218: */
219: void setAttribute(String attributeName, Object attributeValue);
220:
221: /**
222: * Return an "attribute". Attributes are temporary (e.g. not stored in the DBMS)
223: * values associated with this particular DB object instance.
224: *
225: * @param attributeName The attribute name to check
226: * @return the object associated with this attribute
227: */
228: Object getAttribute(String attributeName);
229:
230: /**
231: * Returns a <b>Read Only</b> Map containing all the current attributes set
232: * for this particular data object instance.
233: *
234: * @return Read Only <code>java.util.Map</code>
235: */
236: Map getAllAttributes();
237:
238: /**
239: * Retrieve the field value as a String
240: *
241: * @param fieldName the name of the field to retrieve
242: * @return Object or null if the field was null
243: * @throws DBException upon error
244: * @throws IllegalArgumentException if fieldname is invalid
245: */
246: String getField(String fieldName) throws DBException;
247:
248: /**
249: * Use this function to acquire the Executor interface that is associated
250: * with this data object
251: *
252: * @return DataExecutorInterface or null if no Executor has been associated
253: * with this object
254: */
255: DataExecutorInterface getExecutor();
256:
257: /**
258: * Use this function to acquire the DataQueryInterface that is associated
259: * with this data object [Currently unsupported]
260: *
261: * @return DataQueryInterface or null if no QueryInterface has been
262: * associated with this object
263: */
264: DataQueryInterface getQueryInterface();
265:
266: /**
267: * Check that a given value is valid for a given field.
268: * This method is overriden by specific DBObjects to do their own field-level
269: * validations - they should also call super in order to do the
270: * standard stuff. Every field is automatically checked by this method before the
271: * database is updated.
272: *
273: * @param fieldName Name of the field to verify
274: * @param fieldValue Value of the field to be evaluated
275: * @throws DBException If the value is not valid
276: */
277: void checkField(String fieldName, String fieldValue)
278: throws DBException;
279:
280: /**
281: * Retrieve the status code of the dataobject.
282: *
283: * @return java.lang.String
284: */
285: String getStatus();
286:
287: /**
288: * Sets the status of the object.
289: *
290: * @param statusValue the new status code.
291: */
292: void setStatus(String statusValue);
293:
294: /**
295: * Retrieve a list of valid value object for this particular dbobject
296: *
297: * @param fieldName name of the field to retrieve the list for.
298: * @return java.util.List of valid values
299: * @throws DBException upon error
300: */
301: java.util.List getValidValuesList(String fieldName)
302: throws DBException;
303:
304: /**
305: * Sets the DataObject's locale
306: *
307: * @param newLocale the New locale object
308: */
309: void setLocale(java.util.Locale newLocale);
310:
311: /**
312: * Retrieve the DBObject's current locale
313: *
314: * @return java.util.Locale
315: */
316: java.util.Locale getLocale();
317:
318: /**
319: * Specify a maximum number of records to be retrieved in any subsequent
320: * searchAndRetrieve() call. Records will be retrieved (in the specified
321: * sort order) until the specified maximum is reached, then the remainder
322: * of the result set is discarded. Specifying zero indicates that all
323: * records are to be retrieved.
324: *
325: * @param newMax The maximum number of records to retrieve.
326: * @throws DBException If the max number is less than 0
327: */
328: void setMaxRecords(int newMax) throws DBException;
329:
330: /**
331: * A DB Object can be told to only retrieve a certain number of records. If a
332: * "max records" value has been specified, this method provides access to it.
333: *
334: * @return The maximum number of records that should be retrieved, or zero
335: * if no max has been set
336: */
337: int getMaxRecords();
338:
339: /**
340: * Specifies the number of records that should be skipped over
341: * before any data from the <code>ResultSet</code>
342: * is retrieved in any subsequent
343: * searchAndRetrieve() call. Records will be skipped over (in the specified
344: * sort order) until the record counts is equal to or greater
345: * than the offset record. Specifying zero indicates that no
346: * records should be skipped over and the
347: * <code>ResultSet</code> immediately from the start.
348: *
349: * @param newOffset The maximum number of records to retrieve.
350: * @throws DBException If the max number is less than 0
351: * <p/>
352: * author Peter Pilgrim <peterp at xenonsoft dot demon dot co dot uk>
353: */
354: void setOffsetRecord(int newOffset) throws DBException;
355:
356: /**
357: * Gets the number of records that be skipped. The offset records.
358: * A DB Object can be told to skip a certain number of
359: * records, before reading records from the <code>ResultSet</code>.
360: * <p/>
361: * author Peter Pilgrim, Thu Jun 21 10:30:59 BST 2001
362: *
363: * @return The maximum number of records that should be
364: * skipped over before reading the data records.
365: * @see #setOffsetRecord(int)
366: */
367: int getOffsetRecord();
368:
369: /**
370: * Performs a datasource search so that the criteria set in the DataObject
371: * is used.
372: *
373: * @param sortOrder A pipe delimited string specifying the field(s) to be sorted upon.
374: * May be a single field without any pipes.
375: * @return <code>java.util.List</code> of objects. May be an empty list if no
376: * objects were found.
377: * @throws DBException upon error performing the search
378: */
379: ArrayList searchAndRetrieveList(String sortOrder)
380: throws DBException;
381:
382: /**
383: * Performs a datasource search so that the criteria set in the DataObject
384: * is used. There is no specified sort order for this version of the method
385: *
386: * @return <code>java.util.List</code> of objects. May be an empty list if no
387: * objects were found.
388: * @throws DBException upon error performing the search
389: */
390: ArrayList searchAndRetrieveList() throws DBException;
391:
392: /**
393: * Finds a single record based upon the criteria specified by the <code>DataTransferObject</code>
394: *
395: * @return boolean true if a record was found, and the <i>criteria</i> parameter
396: * is filled with the first data object found.
397: * @throws DBException upon error performing the search
398: */
399: boolean find() throws DBException;
400:
401: /**
402: * Just like find, but only retrieves the count, not the records themselves.
403: *
404: * @return integer Count of the records matching the criteria
405: * @throws DBException If the search could not be completed
406: */
407: int count() throws DBException;
408:
409: /**
410: * Sets the DataObject's global mask
411: *
412: * @param newGlobalMask the New global mask object
413: */
414: void setGlobalMask(Pattern newGlobalMask);
415:
416: /**
417: * Retrieve the DBObject's current global mask
418: *
419: * @return String
420: */
421: Pattern getGlobalMask();
422:
423: /**
424: * Return boolean if the data object has a mask set
425: *
426: * @return True if the data object mask is set, else false if it is not
427: */
428: boolean isGlobalMasked();
429: }
|