001: package net.sourceforge.squirrel_sql.fw.datasetviewer.cellcomponent;
002:
003: /*
004: * Copyright (C) 2001-2003 Colin Bell
005: * colbell@users.sourceforge.net
006: *
007: * This library is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU Lesser General Public
009: * License as published by the Free Software Foundation; either
010: * version 2.1 of the License, or (at your option) any later version.
011: *
012: * This library is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public
018: * License along with this library; if not, write to the Free Software
019: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
020: */
021:
022: import java.io.FileInputStream;
023: import java.io.FileOutputStream;
024: import java.io.IOException;
025:
026: import javax.swing.JTable;
027: import javax.swing.JTextField;
028: import javax.swing.JTextArea;
029:
030: import net.sourceforge.squirrel_sql.fw.datasetviewer.ColumnDisplayDefinition;
031: import net.sourceforge.squirrel_sql.fw.sql.ISQLDatabaseMetaData;
032:
033: import java.sql.PreparedStatement;
034: import java.sql.ResultSet;
035:
036: /**
037: * @author gwg
038: *
039: * These are the calls needed to support the various ways of displaying and
040: * editing data for each data type.
041: *
042: *
043: */
044: public interface IDataTypeComponent {
045: /**
046: * Return the name of the Java class used to store this data type in the
047: * application.
048: */
049: public String getClassName();
050:
051: /**
052: * Determine if two objects of this data type contain the same value.
053: * Neither of the objects is null.
054: */
055: public boolean areEqual(Object obj1, Object obj2);
056:
057: /*
058: * Cell related methods come next.
059: */
060:
061: /**
062: * Convert the given object into its printable String value for use in Text
063: * output and the in-cell representations (CellRenderer and CellEditor).
064: */
065: public String renderObject(Object object);
066:
067: /**
068: * Returns true if data type may be edited within a table cell, false if
069: * not.
070: */
071: public boolean isEditableInCell(Object originalValue);
072:
073: /**
074: * See if a value in a column has been limited in some way and needs to be
075: * re-read before being used for editing. For read-only tables this may
076: * actually return true since we want to be able to view the entire contents
077: * of the cell even if it was not completely loaded during the initial table
078: * setup.
079: */
080: public boolean needToReRead(Object originalValue);
081:
082: /**
083: * Get the JTextField component for this data type to be used in a
084: * CellEditor. The value of the text field is set by the JTable mechanism
085: * using the same mechanism as the renderer. The Assumption here is that the
086: * CellEditor uses the same string representation as the CellRenderer.
087: */
088: public JTextField getJTextField();
089:
090: /**
091: * Validate that the contents of a cell is in the right form for this data
092: * type and convert that text into an object of the correct (Java) type for
093: * the column Ideally this should be a static function, but the mechanics of
094: * using CellComponentFactory and the constraints of the Java language make
095: * that difficult.
096: */
097: public Object validateAndConvert(String value,
098: Object originalValue, StringBuffer messageBuffer);
099:
100: /**
101: * If true, this tells the PopupEditableIOPanel to use the binary editing
102: * panel rather than a pure text panel. The binary editing panel assumes the
103: * data is an array of bytes, converts it into text form, allows the user to
104: * change how that data is displayed (e.g. Hex, Decimal, etc.), and converts
105: * the data back from text to bytes when the user editing is completed. If
106: * this returns false, this DataType class must convert the internal data
107: * into a text string that can be displayed (and edited, if allowed) in a
108: * TextField or TextArea, and must handle all user key strokes related to
109: * editing of that data.
110: */
111: public boolean useBinaryEditingPanel();
112:
113: /*
114: * Now the Popup-related methods. These are not quite symmetric with the
115: * in-cell calls because the conversion of the object into the text to
116: * display in the popup is handled internally to the DataType object inside
117: * getJTextArea(), so we do not need a "renderObjectInPopup" function
118: * visible to the rest of the world.
119: */
120:
121: /**
122: * Returns true if data type may be edited in the popup, false if not.
123: */
124: public boolean isEditableInPopup(Object originalValue);
125:
126: /**
127: * Get the JTextArea component for this data type to be used in the
128: * CellPopupDialog and fill in the initial value in the appropriate
129: * representation. That representation may be the same as is renderObject(),
130: * or it may be different (e.g. a BLOB may have renderObject=>"<BLOB>" but
131: * fill in the actual value in the Popup TextArea).
132: */
133: public JTextArea getJTextArea(Object value);
134:
135: /**
136: * Validate that the contents of a cell is in the right form for this data
137: * type and convert that text into an object of the correct (Java) type for
138: * the column Ideally this should be a static function, but the mechanics of
139: * using CellComponentFactory and the constraints of the Java language make
140: * that difficult.
141: */
142: public Object validateAndConvertInPopup(String value,
143: Object originalValue, StringBuffer messageBuffer);
144:
145: /*
146: * DataBase-related functions
147: */
148:
149: /**
150: * On input from the DB, read the data from the ResultSet into the
151: * appropriate type of object to be stored in the table cell.
152: */
153: public Object readResultSet(ResultSet rs, int index,
154: boolean limitDataRead) throws java.sql.SQLException;
155:
156: /**
157: * When updating the database, generate a string form of this object value
158: * that can be used in the WHERE clause to match the value in the database.
159: * A return value of null means that this column cannot be used in the WHERE
160: * clause, while a return of "null" (or "is null", etc) means that the
161: * column can be used in the WHERE clause and the value is actually a null
162: * value. This function must also include the column label so that its
163: * output is of the form: "columnName = value" or "columnName is null" or
164: * whatever is appropriate for this column in the database.
165: */
166: public String getWhereClauseValue(Object value,
167: ISQLDatabaseMetaData md);
168:
169: /**
170: * When updating the database, insert the appropriate datatype into the
171: * prepared statment at the given variable position.
172: */
173: public void setPreparedStatementValue(PreparedStatement pstmt,
174: Object value, int position) throws java.sql.SQLException;
175:
176: /**
177: * Get a default value for the table used to input data for a new row to be
178: * inserted into the DB.
179: */
180: public Object getDefaultValue(String dbDefaultValue);
181:
182: /*
183: * File IO related functions
184: */
185:
186: /**
187: * Say whether or not object can be exported to and imported from a file. We
188: * put both export and import together in one test on the assumption that
189: * all conversions can be done both ways.
190: */
191: public boolean canDoFileIO();
192:
193: /**
194: * Read a file and construct a valid object from its contents. Errors are
195: * returned by throwing an IOException containing the cause of the problem
196: * as its message.
197: * <P>
198: * DataType is responsible for validating that the imported data can be
199: * converted to an object, and then must return a text string that can be
200: * used in the Popup window text area. This object-to-text conversion is the
201: * same as is done by the DataType object internally in the getJTextArea()
202: * method.
203: */
204: public String importObject(FileInputStream inStream)
205: throws IOException;
206:
207: /**
208: * Read a file and construct a valid object from its contents. Errors are
209: * returned by throwing an IOException containing the cause of the problem
210: * as its message.
211: * <P>
212: * DataType is responsible for validating that the given text text from a
213: * Popup JTextArea can be converted to an object. This text-to-object
214: * conversion is the same as validateAndConvertInPopup, which may be used
215: * internally by the object to do the validation.
216: * <P>
217: * The DataType object must flush and close the output stream before
218: * returning. Typically it will create another object (e.g. an
219: * OutputWriter), and that is the object that must be flushed and closed.
220: */
221: public void exportObject(FileOutputStream outStream, String text)
222: throws IOException;
223:
224: /**
225: * Sets the display definition of the Column being operated upon.
226: *
227: * @param def the ColumnDisplayDefinition that describes the column in the
228: * db table.
229: */
230: public void setColumnDisplayDefinition(ColumnDisplayDefinition def);
231:
232: /**
233: * Sets the JTable of which holds data rendered by this DataTypeComponent.
234: *
235: * @param table a JTable component
236: */
237: public void setTable(JTable table);
238: }
|