001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2007 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041:
042: package com.sun.data.provider;
043:
044: /**
045: * <p>TableDataProvider is a specialized subinterface of {@link DataProvider}
046: * that provides access to a scrollable set of "rows" of data elements, with
047: * each row being identified by a {@link RowKey}. Access to the underlying
048: * data elements may be done in a random fashion by using the methods defined
049: * in this interface, or you can set the cursor row and use the
050: * <code>getType()</code>, <code>getValue()</code>, <code>isReadOnly()</code>,
051: * and <code>setValue()</code> methods from the base {@link DataProvider}
052: * interface to access data elements for the cursor row specified by calling
053: * <code>setCursorRow(RowKey)</code>.</p>
054: *
055: * <p>The set of {@link FieldKey}s returned by <code>getFieldKeys()</code>
056: * <strong>MUST</strong> be available on every row supported by this
057: * {@link TableDataProvider}. This implies a rectangular (matrix) dataset.</p>
058: *
059: * <p>The set of {@link RowKey}s returned by <code>getRowKeys(...)</code> are
060: * expected to uniquely represent the rows contained in the underlying data
061: * source. The RowKey objects should remain valid as long as the set of rows
062: * in the TableDataProvider has not been re-fetched. Once a re-fetch has
063: * happened (by whatever means are supplied by specific TableDataProvider
064: * implementations), the previously fetched RowKeys may become invalid. Consult
065: * the documentation of the specific TableDataProvider implementation for
066: * details on the expected valid lifespan of a RowKey.</p>
067: *
068: * <p>Most methods throw {@link DataProviderException}, which is a generic
069: * runtime exception indicating something is amiss in the internal state of the
070: * TableDataProvider implementation. Because DPE is a runtime exception, method
071: * calls are not required to be wrapped in a try...catch block, but it is
072: * advised to check the documentation of the particular TableDataProvider
073: * implementation to see what conditions will cause a DataProviderException to
074: * be thrown. It is recommended to always wrap calls to this interface in
075: * try...catch blocks in case an unforseen error condition arises at runtime.</p>
076: *
077: * @author Joe Nuxoll
078: * @author Matthew Bohm
079: */
080: public interface TableDataProvider extends DataProvider {
081:
082: // ---------------------------------------------------------- RowKey Methods
083:
084: /**
085: * @return the number of rows represented by this
086: * {@link TableDataProvider} if this information is available;
087: * otherwise, return -1 (indicating unknown row count)
088: * @throws DataProviderException Implementations may wish to surface
089: * internal exceptions (nested in DataProviderException) rather
090: * than simply returning -1. Consult the documentation of the
091: * specific TableDataProvider implementation for details on what
092: * exceptions might be wrapped by a DPE.
093: */
094: public int getRowCount() throws DataProviderException;
095:
096: /**
097: * Returns an array of {@link RowKey} objects representing the requested
098: * batch of RowKeys. If <code>null</code> is passed as the afterRow
099: * parameter, the returned batch of RowKeys will start with the first one.
100: *
101: * @param count The desired count of RowKeys to fetch. If this number
102: * exceeds the total number of rows available, the return array
103: * will contain the available number, and no exception will be
104: * thrown. Consider this an optimistic request of the
105: * TableDataProvider.
106: * @param afterRow The RowKey that represents the last row before the set
107: * of desired RowKeys to be returned. Typically, this is the last
108: * RowKey from the previously fetched set of RowKeys. If
109: * <code>null</code> is passed, the returned set will begin with the
110: * first row.
111: * @return An array of RowKey objects representing the requested batch of
112: * rows.
113: * @throws DataProviderException Implementations may wish to surface
114: * internal exceptions (nested in DataProviderException) rather
115: * than simply returning null or an empty array. Consult the
116: * documentation of the specific TableDataProvider implementation
117: * for details on what exceptions might be wrapped by a DPE.
118: */
119: public RowKey[] getRowKeys(int count, RowKey afterRow)
120: throws DataProviderException;
121:
122: /**
123: * Returns a RowKey for the specified rowId. This allows a RowKey to be
124: * stored off as a simple string, which can be resolved into an instance
125: * of a RowKey at a later date.
126: *
127: * @param rowId The cannoncial string ID of the desired RowKey
128: * @return A RowKey object representing the desired row, or
129: * <code>null</code> if the specified rowId does not correspond to
130: * a row in this TableDataProvider
131: * @throws DataProviderException Implementations may wish to surface
132: * internal exceptions (nested in DataProviderException) rather
133: * than simply returning null. Consult the documentation of the
134: * specific TableDataProvider implementation for details on what
135: * exceptions might be wrapped by a DPE.
136: */
137: public RowKey getRowKey(String rowId) throws DataProviderException;
138:
139: /**
140: * Returns <code>true</code> if the specified {@link RowKey} represents
141: * data elements that are supported by this {@link TableDataProvider};
142: * otherwise, return <code>false</code>
143: *
144: * @param rowKey RowKey specifying row to be tested
145: * @return <code>true</code> if the row is available, <code>false</code> if
146: * not
147: * @throws DataProviderException Implementations may wish to surface
148: * internal exceptions (nested in DataProviderException) rather
149: * than simply returning false. Consult the documentation of the
150: * specific TableDataProvider implementation for details on what
151: * exceptions might be wrapped by a DPE.
152: */
153: public boolean isRowAvailable(RowKey rowKey)
154: throws DataProviderException;
155:
156: // --------------------------------------------------- Random Access Methods
157:
158: /**
159: * <p>Return value of the data element referenced by the specified
160: * {@link FieldKey} and {@link RowKey}.</p>
161: *
162: * @param fieldKey <code>FieldKey</code> identifying the data element
163: * whose value is to be returned
164: * @param rowKey <code>RowKey</code> identifying the data row whose value
165: * is to be returned
166: * @return value of the data element referenced by the specified
167: * {@link FieldKey} and {@link RowKey}
168: * @throws DataProviderException Implementations may wish to surface
169: * internal exceptions (nested in DataProviderException) rather
170: * than simply returning null. A DPE may also indicate that this
171: * <code>FieldKey</code> or <code>RowKey</code> does not represent
172: * a data element provided by this TableDataProvider. Consult the
173: * documentation of the specific TableDataProvider implementation
174: * for details on what exceptions might be wrapped by a DPE.
175: */
176: public Object getValue(FieldKey fieldKey, RowKey rowKey)
177: throws DataProviderException;
178:
179: /**
180: * <p>Sets the value of the data element represented by the specified
181: * {@link FieldKey} and {@link RowKey} to the specified new value.</p>
182: *
183: * @param fieldKey <code>FieldKey</code> identifying the data element
184: * whose value is to be modified
185: * @param rowKey <code>RowKey</code> indentifying the data row whose value
186: * is to be modified
187: * @param value New value for this data element
188: * @throws DataProviderException Implementations may wish to surface
189: * internal exceptions (nested in DataProviderException). A DPE
190: * may also indicate that this <code>FieldKey</code> or
191: * <code>RowKey</code> does not represent a data element provided
192: * by this TableDataProvider. Consult the documentation of the
193: * specific TableDataProvider implementation for details on what
194: * exceptions might be wrapped by a DPE.
195: */
196: public void setValue(FieldKey fieldKey, RowKey rowKey, Object value)
197: throws DataProviderException;
198:
199: // -------------------------------------------------------- Resizing Methods
200:
201: /**
202: * <p>This method is called to test if this TableDataProvider supports
203: * resizability. If objects can be inserted and removed from the list,
204: * this method should return <code>true</code>. If the data provider is
205: * not resizable, this method should return <code>false</code>.</p>
206: *
207: * <p>The following methods will only be called if this method returns
208: * <code>true</code>:
209: * <ul><li><code>insertRow(RowKey beforeRow)</code>
210: * <li><code>appendRow()</code>
211: * <li><code>removeRow(RowKey rowKey)</code>
212: * </ul>
213: *
214: * @param beforeRow The desired location to insert the new row in front of
215: * @return <code>true</code> if the data provider is resizable, or
216: * <code>false</code> if not.
217: * @throws DataProviderException Implementations may wish to surface
218: * internal exceptions (nested in DataProviderException) rather
219: * than simply returning false. A DPE may also indicate that this
220: * <code>RowKey</code> does not represent a row provided by this
221: * TableDataProvider. Consult the documentation of the specific
222: * TableDataProvider implementation for details on what exceptions
223: * might be wrapped by a DPE.
224: * @see #insertRow(RowKey)
225: */
226: public boolean canInsertRow(RowKey beforeRow)
227: throws DataProviderException;
228:
229: /**
230: * <p>Inserts a new row at the specified row.</p>
231: *
232: * <p>NOTE: The method should only be called after testing the
233: * <code>canInsertRow(RowKey beforeRow)</code> to see if this
234: * TableDataProvider supports resizing.</p>
235: *
236: * @param beforeRow The desired location to insert the new row in front of
237: * @return A RowKey representing the address of the newly inserted row
238: * @throws DataProviderException Implementations may wish to surface
239: * internal exceptions (nested in DataProviderException). A DPE
240: * may also indicate that this <code>RowKey</code> does not
241: * represent a row provided by this TableDataProvider. Consult the
242: * documentation of the specific TableDataProvider implementation
243: * for details on what exceptions might be wrapped by a DPE.
244: * @see #canInsertRow(RowKey)
245: */
246: public RowKey insertRow(RowKey beforeRow)
247: throws DataProviderException;
248:
249: /**
250: * <p>This method is called to test if this TableDataProvider supports
251: * the append operation. If rows can be appended to the list, this method
252: * should return <code>true</code>. If the data provider is not resizable,
253: * or cannot support an append operation, this method should return
254: * <code>false</code>.</p>
255: *
256: * @return <code>true</code> if the data provider supports the append
257: * operation, or <code>false</code> if not.
258: * @throws DataProviderException Implementations may wish to surface
259: * internal exceptions (nested in DataProviderException). A DPE
260: * may also indicate that this <code>RowKey</code> does not
261: * represent a row provided by this TableDataProvider. Consult the
262: * documentation of the specific TableDataProvider implementation
263: * for details on what exceptions might be wrapped by a DPE.
264: * @see #appendRow()
265: */
266: public boolean canAppendRow() throws DataProviderException;
267:
268: /**
269: * <p>Appends a new row at the end of the list and returns the row key for
270: * the newly appended row.</p>
271: *
272: * <p>NOTE: The method should only be called after testing the
273: * <code>canAppendRow()</code> method to see if this TableDataProvider
274: * supports the append operation.</p>
275: *
276: * @return The row key for the newly appended row
277: * @throws DataProviderException Implementations may wish to surface
278: * internal exceptions (nested in DataProviderException). Consult
279: * the documentation of the specific TableDataProvider
280: * implementation for details on what exceptions might be wrapped
281: * by a DPE.
282: * @see #canAppendRow()
283: */
284: public RowKey appendRow() throws DataProviderException;
285:
286: /**
287: * <p>This method is called to test if this TableDataProvider supports
288: * the removeRow operation. If rows can be removed from the table, this
289: * method should return <code>true</code>. If the data provider is does
290: * not support removing rows, this method should return <code>false</code>.
291: * </p>
292: *
293: * @param rowKey The desired row to remove
294: * @return <code>true</code> if the data provider supports removing rows,
295: * or <code>false</code> if not.
296: * @throws DataProviderException Implementations may wish to surface
297: * internal exceptions (nested in DataProviderException). A DPE
298: * may also indicate that this <code>RowKey</code> does not
299: * represent a row provided by this TableDataProvider. Consult
300: * the documentation of the specific TableDataProvider
301: * implementation for details on what exceptions might be wrapped
302: * by a DPE.
303: * @see #removeRow(RowKey)
304: */
305: public boolean canRemoveRow(RowKey rowKey)
306: throws DataProviderException;
307:
308: /**
309: * <p>Removes the specified row.</p>
310: *
311: * <p>NOTE: The method should only be called after testing the
312: * <code>canRemoveRow(RowKey)</code> method to see if this TableDataProvider
313: * supports removing rows.</p>
314: *
315: * @param rowKey The desired row key to remove
316: * @throws DataProviderException Implementations may wish to surface
317: * internal exceptions (nested in DataProviderException). A DPE
318: * may also indicate that this <code>RowKey</code> does not
319: * represent a row provided by this TableDataProvider. Consult
320: * the documentation of the specific TableDataProvider
321: * implementation for details on what exceptions might be wrapped
322: * by a DPE.
323: * @see #canRemoveRow(RowKey)
324: */
325: public void removeRow(RowKey rowKey) throws DataProviderException;
326:
327: // ----------------------------------- Table Data Event Registration Methods
328:
329: /**
330: * <p>Register a new {@link TableDataListener} to this TableDataProvider
331: * instance.</p>
332: *
333: * @param listener New {@link TableDataListener} to register
334: */
335: public void addTableDataListener(TableDataListener listener);
336:
337: /**
338: * <p>Deregister an existing {@link TableDataListener} from this
339: * TableDataProvider instance.</p>
340: *
341: * @param listener Old {@link TableDataListener} to deregister
342: */
343: public void removeTableDataListener(TableDataListener listener);
344:
345: /**
346: * @return An array of the {@link TableDataListener}s currently registered
347: * on this TableDataProvider. If there are no registered listeners,
348: * a zero-length array is returned.
349: */
350: public TableDataListener[] getTableDataListeners();
351:
352: // ----------------------------------------------------------- Cursor Access
353:
354: /**
355: * @return the {@link RowKey} of the current cursor row position
356: * @throws DataProviderException Implementations may wish to surface
357: * internal exceptions (nested in DataProviderException). Consult
358: * the documentation of the specific TableDataProvider
359: * implementation for details on what exceptions might be wrapped
360: * by a DPE.
361: */
362: public RowKey getCursorRow() throws DataProviderException;
363:
364: /**
365: * <p>Sets the cursor to the row represented by the passed {@link RowKey}.
366: * </p>
367: *
368: * @param rowKey New {@link RowKey} to move the cursor to.
369: * @throws TableCursorVetoException if a TableCursorListener decides to
370: * veto the cursor navigation
371: * @throws DataProviderException Implementations may wish to surface
372: * internal exceptions (nested in DataProviderException). A DPE
373: * may also indicate that this <code>RowKey</code> does not
374: * represent a row provided by this TableDataProvider. Consult
375: * the documentation of the specific TableDataProvider
376: * implementation for details on what exceptions might be wrapped
377: * by a DPE.
378: */
379: public void setCursorRow(RowKey rowKey)
380: throws TableCursorVetoException;
381:
382: /**
383: * <p>Move the cursor to the first row in this TableDataProvider.</p>
384: *
385: * @return <code>true</code> if the cursor row was successfully changed;
386: * else <code>false</code>
387: * @throws DataProviderException Implementations may wish to surface
388: * internal exceptions (nested in DataProviderException) rather
389: * than simply returning false. Consult the documentation of the
390: * specific TableDataProvider implementation for details on what
391: * exceptions might be wrapped by a DPE.
392: */
393: public boolean cursorFirst() throws DataProviderException;
394:
395: /**
396: * <p>Move the cursor to the row before the current cursor row, unless
397: * the cursor is currently at the first row.</p>
398: *
399: * @return <code>true</code> if the cursor row was successfully changed;
400: * else <code>false</code>
401: * @throws DataProviderException Implementations may wish to surface
402: * internal exceptions (nested in DataProviderException) rather
403: * than simply returning false. Consult the documentation of the
404: * specific TableDataProvider implementation for details on what
405: * exceptions might be wrapped by a DPE.
406: */
407: public boolean cursorPrevious() throws DataProviderException;
408:
409: /**
410: * <p>Move the cursor to the row after the current cursor row, unless the
411: * cursor is currently at the last row {@link TableDataProvider}.</p>
412: *
413: * @return <code>true</code> if the cursor row was successfully changed;
414: * else <code>false</code>
415: * @throws DataProviderException Implementations may wish to surface
416: * internal exceptions (nested in DataProviderException) rather
417: * than simply returning false. Consult the documentation of the
418: * specific TableDataProvider implementation for details on what
419: * exceptions might be wrapped by a DPE.
420: */
421: public boolean cursorNext() throws DataProviderException;
422:
423: /**
424: * <p>Move the cursor to the last row in this TableDataProvider.</p>
425: *
426: * @return <code>true</code> if the cursor row was successfully changed;
427: * else <code>false</code>
428: * @throws DataProviderException Implementations may wish to surface
429: * internal exceptions (nested in DataProviderException) rather
430: * than simply returning false. Consult the documentation of the
431: * specific TableDataProvider implementation for details on what
432: * exceptions might be wrapped by a DPE.
433: */
434: public boolean cursorLast() throws DataProviderException;
435:
436: // --------------------------------- Table Cursor Event Registration Methods
437:
438: /**
439: * <p>Register a new {@link TableCursorListener} to this TableDataProvider
440: * instance.</p>
441: *
442: * @param listener New {@link TableCursorListener} to register
443: */
444: public void addTableCursorListener(TableCursorListener listener);
445:
446: /**
447: * <p>Deregister an existing {@link TableCursorListener} from this
448: * TableDataProvider instance.</p>
449: *
450: * @param listener Old {@link TableCursorListener} to deregister
451: */
452: public void removeTableCursorListener(TableCursorListener listener);
453:
454: /**
455: * @return An array of the {@link TableCursorListener}s currently registered
456: * on this TableDataProvider. If there are no registered listeners,
457: * a zero-length array is returned.
458: */
459: public TableCursorListener[] getTableCursorListeners();
460: }
|