001: /*
002: * $Id: DataType.java,v 1.14 2005/05/02 22:17:47 ahimanikya Exp $
003: * =======================================================================
004: * Copyright (c) 2002-2005 Axion Development Team. 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
011: * copyright notice, this list of conditions and the following
012: * disclaimer.
013: *
014: * 2. Redistributions in binary form must reproduce the above copyright
015: * notice, this list of conditions and the following disclaimer in
016: * the documentation and/or other materials provided with the
017: * distribution.
018: *
019: * 3. The names "Tigris", "Axion", nor the names of its contributors may
020: * not be used to endorse or promote products derived from this
021: * software without specific prior written permission.
022: *
023: * 4. Products derived from this software may not be called "Axion", nor
024: * may "Tigris" or "Axion" appear in their names without specific prior
025: * written permission.
026: *
027: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
028: * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
029: * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
030: * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
031: * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
032: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
033: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
034: * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
035: * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
036: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
037: * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
038: * =======================================================================
039: */
040:
041: package org.axiondb;
042:
043: import java.io.DataInput;
044: import java.io.DataOutput;
045: import java.io.IOException;
046: import java.io.Serializable;
047: import java.math.BigDecimal;
048: import java.math.BigInteger;
049: import java.net.URL;
050: import java.sql.Blob;
051: import java.sql.Clob;
052: import java.sql.Date;
053: import java.sql.Time;
054: import java.sql.Timestamp;
055: import java.util.Comparator;
056:
057: /**
058: * The type of a field (column) that can be stored in a {@link Table}.
059: * <p>
060: * Responsible for {@link #accepts testing}that a value is assignable to fields of this
061: * type, for {@link #convert converting}{@link Object Objects}to this type, and for
062: * {@link #read reading}values from and {@link #write writing}values to a stream.
063: *
064: * @version $Revision: 1.14 $ $Date: 2005/05/02 22:17:47 $
065: * @author Rodney Waldhoff
066: * @author Rob Oxspring
067: * @author Chuck Burdick
068: */
069: public interface DataType extends Comparator, Serializable {
070: /**
071: * Return <code>true</code> if a field of my type can be assigned the given non-
072: * <code>null</code> <i>value </i>, <code>false</code> otherwise.
073: *
074: * @param value non- <code>null</code> value
075: */
076: boolean accepts(Object value);
077:
078: /**
079: * Converts an {@link #accepts acceptable}value to one of the appropriate type.
080: *
081: * @throws AxionException
082: */
083: Object convert(Object value) throws AxionException;
084:
085: /**
086: * Value returned by {@link ResultSetMetaData#getColumnDisplaySize}for this data
087: * type.
088: *
089: * @see java.sql.ResultSetMetaData#getColumnDisplaySize
090: */
091: int getColumnDisplaySize();
092:
093: /**
094: * Returns the JDBC {@link java.sql.Types type code}most closely matching this type.
095: */
096: int getJdbcType();
097:
098: /**
099: * Prefix used to quote a literal to delimit value for this type when in SQL syntax or
100: * result display
101: *
102: * @see java.sql.DatabaseMetaData#getTypeInfo
103: */
104: String getLiteralPrefix();
105:
106: /**
107: * Suffix used to quote a literal to delimit value for this type when in SQL syntax or
108: * result display
109: *
110: * @see java.sql.DatabaseMetaData#getTypeInfo
111: */
112: String getLiteralSuffix();
113:
114: /**
115: * Code indicating that type does not accept, does accept, or does not disclose
116: * acceptance of <code>null</code> values
117: *
118: * @see java.sql.DatabaseMetaData#getTypeInfo
119: */
120: int getNullableCode();
121:
122: /**
123: * Value returned by {@link ResultSetMetaData#getPrecision}for this data type.
124: *
125: * @see java.sql.ResultSetMetaData#getPrecision
126: */
127: int getPrecision();
128:
129: /**
130: * Indicates radix used to compute maximum number of significant digits for this
131: * datatype, as returned by {@link #getPrecision}.
132: *
133: * @return radix used to compute value of {@link #getPrecision}, typically 2 or 10.
134: */
135: int getPrecisionRadix();
136:
137: /**
138: * Returns the "normal" type returned by {@link #convert}. Returns
139: * <tt>java.lang.Object</tt> if unknown.
140: *
141: * @see java.sql.ResultSetMetaData#getColumnClassName
142: */
143: String getPreferredValueClassName();
144:
145: /**
146: * Value returned by {@link ResultSetMetaData#getScale}for this data type.
147: *
148: * @see java.sql.ResultSetMetaData#getScale
149: */
150: int getScale();
151:
152: /**
153: * Code indicating how much <code>WHERE ... LIKE</code> support is available across
154: * a column of this type
155: *
156: * @see java.sql.DatabaseMetaData#getTypeInfo
157: */
158: short getSearchableCode();
159:
160: /**
161: * For character and string-related types, indicates whether type acknowledges case
162: * when storing and retrieving values
163: *
164: * @see java.sql.DatabaseMetaData#getTypeInfo
165: * @see java.sql.ResultSetMetaData#isCaseSensitive
166: */
167: boolean isCaseSensitive();
168:
169: /**
170: * @see java.sql.ResultSetMetaData#isCurrency
171: */
172: boolean isCurrency();
173:
174: /**
175: * For numeric types, indicates whether type stores only non-negative (>= 0) values
176: *
177: * @see java.sql.DatabaseMetaData#getTypeInfo
178: */
179: boolean isUnsigned();
180:
181: /**
182: * Instantiate an object of my type from the given {@link DataInput}. The next
183: * sequence of bytes to be read from the <code>DataInput</code> will have been
184: * written by {@link #write}.
185: */
186: Object read(DataInput in) throws IOException;
187:
188: /**
189: * Returns the successor for the given value. For example, the successor of the
190: * integer 1 is 2.
191: */
192: Object successor(Object value) throws UnsupportedOperationException;
193:
194: /**
195: * Returns <code>true</code> if the {@link #successor}method is supported, false
196: * otherwise.
197: */
198: boolean supportsSuccessor();
199:
200: /**
201: * Convert the given non- <code>null</code> <i>value </i> to a
202: * <code>BigDecimal</code>, or throw a {@link AxionException}.
203: *
204: * @see java.sql.ResultSet#getBigDecimal
205: */
206: BigDecimal toBigDecimal(Object value) throws AxionException;
207:
208: /**
209: * Convert the given non- <code>null</code> <i>value </i> to a
210: * <code>BigInteger</code>, or throw a {@link AxionException}.
211: *
212: * @see java.sql.ResultSet#getBigInteger
213: */
214: BigInteger toBigInteger(Object value) throws AxionException;
215:
216: /**
217: * Convert the given non- <code>null</code> <i>value </i> to a {@link Blob}, or
218: * throw a {@link AxionException}.
219: *
220: * @see java.sql.ResultSet#getBlob
221: */
222: Blob toBlob(Object value) throws AxionException;
223:
224: /**
225: * Convert the given non- <code>null</code> <i>value </i> to a <code>boolean</code>,
226: * or throw a {@link SQLException}.
227: *
228: * @see java.sql.ResultSet#getBoolean
229: */
230: boolean toBoolean(Object value) throws AxionException;
231:
232: /**
233: * Convert the given non- <code>null</code> <i>value </i> to a <code>byte</code>,
234: * or throw a {@link SQLException}.
235: *
236: * @see java.sql.ResultSet#getByte
237: */
238: byte toByte(Object value) throws AxionException;
239:
240: /**
241: * Convert the given non- <code>null</code> <i>value </i> to a <code>byte[]</code>,
242: * or throw a {@link AxionException}.
243: *
244: * @see java.sql.ResultSet#getBytes
245: */
246: byte[] toByteArray(Object value) throws AxionException;
247:
248: /**
249: * Convert the given non- <code>null</code> <i>value </i> to a {@link Clob}, or
250: * throw a {@link AxionException}.
251: *
252: * @see java.sql.ResultSet#getClob
253: */
254: Clob toClob(Object value) throws AxionException;
255:
256: /**
257: * Convert the given non- <code>null</code> <i>value </i> to a {@link java.sql.Date},
258: * or throw a {@link SQLException}.
259: *
260: * @see java.sql.ResultSet#getDate
261: */
262: Date toDate(Object value) throws AxionException;
263:
264: /**
265: * Convert the given non- <code>null</code> <i>value </i> to a <code>double</code>,
266: * or throw a {@link AxionException}.
267: *
268: * @see java.sql.ResultSet#getDouble
269: */
270: double toDouble(Object value) throws AxionException;
271:
272: /**
273: * Convert the given non- <code>null</code> <i>value </i> to a <code>float</code>,
274: * or throw a {@link AxionException}.
275: *
276: * @see java.sql.ResultSet#getFloat
277: */
278: float toFloat(Object value) throws AxionException;
279:
280: /**
281: * Convert the given non- <code>null</code> <i>value </i> to a <code>int</code>,
282: * or throw a {@link AxionException}.
283: *
284: * @see java.sql.ResultSet#getInt
285: */
286: int toInt(Object value) throws AxionException;
287:
288: /**
289: * Convert the given non- <code>null</code> <i>value </i> to a <code>long</code>,
290: * or throw a {@link AxionException}.
291: *
292: * @see java.sql.ResultSet#getLong
293: */
294: long toLong(Object value) throws AxionException;
295:
296: /**
297: * Convert the given non- <code>null</code> <i>value </i> to a <code>short</code>,
298: * or throw a {@link AxionException}.
299: *
300: * @see java.sql.ResultSet#getShort
301: */
302: short toShort(Object value) throws AxionException;
303:
304: /**
305: * Convert the given non- <code>null</code> <i>value </i> to a {@link String}, or
306: * throw a {@link AxionException}.
307: *
308: * @see java.sql.ResultSet#getString
309: */
310: String toString(Object value) throws AxionException;
311:
312: /**
313: * Convert the given non- <code>null</code> <i>value </i> to a {@link Time}, or
314: * throw a {@link AxionException}.
315: *
316: * @see java.sql.ResultSet#getTime
317: */
318: Time toTime(Object value) throws AxionException;
319:
320: /**
321: * Convert the given non- <code>null</code> <i>value </i> to a {@link Timestamp},
322: * or throw a {@link AxionException}.
323: *
324: * @see java.sql.ResultSet#getTimestamp
325: */
326: Timestamp toTimestamp(Object value) throws AxionException;
327:
328: /**
329: * Convert the given non- <code>null</code> <i>value </i> to a {@link URL}, or
330: * throw a {@link AxionException}.
331: *
332: * @see java.sql.ResultSet#getURL
333: */
334: URL toURL(Object value) throws AxionException;
335:
336: /**
337: * Write an object of my type to the given {@link DataOutput}.
338: *
339: * @param value the value to write, which must be {@link #accepts acceptable}to this
340: * <code>DataType</code>
341: */
342: void write(Object value, DataOutput out) throws IOException;
343:
344: /**
345: * Creates a new instance of this DataType implementation.
346: *
347: * @return new instance of this DataType implementation.
348: */
349: DataType makeNewInstance();
350:
351: /**
352: * Extension of DataType to indicate that the precision of the implementing class is
353: * not fixed by the implementation, but rather can be declared by the user.
354: *
355: * @author Jonathan Giron
356: */
357: public static interface NonFixedPrecision extends DataType {
358: /**
359: * Overrides the default precision with the given value.
360: *
361: * @param newSize new precision value. The appropriate value depends on the
362: * precision radix, which is fixed for each implementing type.
363: */
364: void setPrecision(int newSize);
365: }
366:
367: /**
368: * Extension of NonFixedPrecision to indicate that the scale of the implementing class
369: * is not fixed by the implementation, but rather can be declared by the user.
370: *
371: * @author Jonathan Giron
372: */
373: public static interface ExactNumeric extends NonFixedPrecision {
374: /**
375: * Overrides the default scale with the given value.
376: *
377: * @param newScale new scale value. The appropriate value depends on the current
378: * precision and radix - precision can be modified by the user, but the
379: * radix is fixed for each implementing type.
380: */
381: void setScale(int newScale);
382:
383: /**
384: * Creates a new instance of the implementing ExactNumeric type with the given
385: * precision and scale.
386: *
387: * @param newPrecision precision of the new instance
388: * @param newScale scale of the new instance
389: * @return new instance of ExactNumeric implementation with the given precision
390: * and scale
391: */
392: ExactNumeric makeNewInstance(int newPrecision, int newScale);
393: }
394:
395: /**
396: * Extension of DataType to indicate that the implementing class stores binary values,
397: * and as such returns precision as the number of bits used to represent a given
398: * value.
399: *
400: * @author Jonathan Giron
401: * @version $Revision: 1.14 $
402: */
403: public interface BinaryRepresentation extends DataType {
404: /**
405: * Returns the approximate number of decimal digits that would be used to
406: * represent
407: *
408: * @return
409: */
410: int getApproximateDecimalPrecision();
411: }
412: }
|