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>DataProvider is an interface that describes a single set of data
046: * elements, each identified by a {@link FieldKey}. Applications may retrieve
047: * a list of available {@link FieldKey}s supported by a particular
048: * {@link DataProvider} instance, or acquire a {@link FieldKey} for a
049: * particular canonical name (whose intrinsic meaning is defined by the
050: * particular {@link DataProvider} implementation in use). For each
051: * supported <code>{@link FieldKey}</code>, the corresponding data element's
052: * value may be retrieved, and (optionally) modified, or its data type
053: * and read-only status may be acquired.</p>
054: *
055: * <p>The base {@link DataProvider} interface describes access to individual
056: * data elements. In addition, specialized subinterfaces are defined for
057: * access to multiple data elements.</p>
058: *
059: * <p>{@link TableDataProvider} provides access to tabular data, with
060: * multiple rows each containing data elements corresponding to the same set
061: * of {@link FieldKey}s.</p>
062: *
063: * <p>{@link DataProvider} imposes no requirements or limitations related to
064: * whether it is legal to access the same {@link DataProvider} instance from
065: * multiple threads that are operating simultaneously. Thread safety
066: * considerations are a feature of particular implementations.</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: * DataProvider 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 DataProvider
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: */
079: public interface DataProvider {
080:
081: //--------------------------------------------------------- FieldKey Methods
082:
083: /**
084: * @return An array of all {@link FieldKey}s supported by this
085: * {@link DataProvider}. If the set of valid {@link FieldKey}s cannot
086: * be determined, return <code>null</code> instead.
087: * @throws DataProviderException Implementations may wish to surface
088: * internal exceptions (nested in DataProviderException) rather
089: * than simply returning null or an empty array. Consult the
090: * documentation of the specific DataProvider implementation for
091: * details on what exceptions might be wrapped by a DPE.
092: */
093: public FieldKey[] getFieldKeys() throws DataProviderException;
094:
095: /**
096: * <p>Returns the {@link FieldKey} associated with the specified data
097: * element canonical id, if any; otherwise, return <code>null</code>.</p>
098: *
099: * @param fieldId Canonical id of the requested {@link FieldKey}
100: * @return the {@link FieldKey} associated with the specified data
101: * element canonical id, if any; otherwise, return
102: * <code>null</code>
103: * @throws DataProviderException Implementations may wish to surface
104: * internal exceptions (nested in DataProviderException) rather
105: * than simply returning null. A DPE may also indicate that the
106: * passed fieldId is not valid. Consult the documentation of the
107: * specific DataProvider implementation for details on what
108: * exceptions might be wrapped by a DPE.
109: */
110: public FieldKey getFieldKey(String fieldId)
111: throws DataProviderException;
112:
113: //------------------------------------------------------ Data Element Access
114:
115: /**
116: * <p>Returns the data type of the data element referenced by the
117: * specified data key.</p>
118: *
119: * @param fieldKey <code>FieldKey</code> identifying the data element
120: * whose type is to be returned
121: * @return the data type of the data element referenced by the
122: * specified data key
123: * @throws DataProviderException Implementations may wish to surface
124: * internal exceptions (nested in DataProviderException) rather
125: * than simply returning null. A DPE may also indicate that the
126: * passed fieldKey is not valid. Consult the documentation of the
127: * specific DataProvider implementation for details on what
128: * exceptions might be wrapped by a DPE.
129: */
130: public Class getType(FieldKey fieldKey)
131: throws DataProviderException;
132:
133: /**
134: * <p>Return a flag indicating whether the value of the data element
135: * represented by the specified {@link FieldKey} can be modified via the
136: * <code>setValue()</code> method.</p>
137: *
138: * @param fieldKey <code>FieldKey</code> identifying the data element
139: * whose settable status is to be returned
140: * @return a flag indicating whether the value of the data element
141: * represented by the specified {@link FieldKey} can be modified
142: * via the <code>setValue()</code> method
143: * @throws DataProviderException Implementations may wish to surface
144: * internal exceptions (nested in DataProviderException) rather
145: * than simply returning true. A DPE may also indicate that the
146: * passed fieldKey is not valid. Consult the documentation of the
147: * specific DataProvider implementation for details on what
148: * exceptions might be wrapped by a DPE.
149: */
150: public boolean isReadOnly(FieldKey fieldKey)
151: throws DataProviderException;
152:
153: /**
154: * <p>Returns value of the data element referenced by the specified
155: * {@link FieldKey}.</p>
156: *
157: * @param fieldKey <code>FieldKey</code> identifying the data element
158: * whose value is to be returned
159: * @return value of the data element referenced by the specified
160: * {@link FieldKey}
161: * @throws DataProviderException Implementations may wish to surface
162: * internal exceptions (nested in DataProviderException) rather
163: * than simply returning null. A DPE may also indicate that the
164: * passed fieldKey is not valid. Consult the documentation of the
165: * specific DataProvider implementation for details on what
166: * exceptions might be wrapped by a DPE.
167: */
168: public Object getValue(FieldKey fieldKey)
169: throws DataProviderException;
170:
171: /**
172: * <p>Set the value of the data element represented by the specified
173: * {@link FieldKey} to the specified new value.</p>
174: *
175: * @param fieldKey <code>FieldKey</code> identifying the data element
176: * whose value is to be modified
177: * @param value New value for this data element
178: * @throws DataProviderException Implementations may wish to surface
179: * internal exceptions (nested in DataProviderException) rather
180: * than simply returning null. A DPE may also indicate that the
181: * passed fieldKey is not valid. Consult the documentation of the
182: * specific DataProvider implementation for details on what
183: * exceptions might be wrapped by a DPE.
184: */
185: public void setValue(FieldKey fieldKey, Object value)
186: throws DataProviderException;
187:
188: //----------------------------------------------- Event Registration Methods
189:
190: /**
191: * <p>Register a new {@link DataListener} to this DataProvider
192: * instance.</p>
193: *
194: * @param listener New {@link DataListener} to register
195: */
196: public void addDataListener(DataListener listener);
197:
198: /**
199: * <p>Deregister an existing {@link DataListener} from this
200: * DataProvider instance.</p>
201: *
202: * @param listener Old {@link DataListener} to deregister
203: */
204: public void removeDataListener(DataListener listener);
205:
206: /**
207: * @return An array of the {@link DataListener}s currently
208: * registered on this DataProvider. If there are no registered
209: * listeners, a zero-length array is returned.
210: */
211: public DataListener[] getDataListeners();
212: }
|