View Javadoc
1   /*
2   Copyright (c) 2013 James Ahlborn
3   
4   Licensed under the Apache License, Version 2.0 (the "License");
5   you may not use this file except in compliance with the License.
6   You may obtain a copy of the License at
7   
8       http://www.apache.org/licenses/LICENSE-2.0
9   
10  Unless required by applicable law or agreed to in writing, software
11  distributed under the License is distributed on an "AS IS" BASIS,
12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  See the License for the specific language governing permissions and
14  limitations under the License.
15  */
16  
17  package com.healthmarketscience.jackcess;
18  
19  import java.io.IOException;
20  import java.util.Iterator;
21  import java.util.List;
22  import java.util.Map;
23  
24  import com.healthmarketscience.jackcess.util.ErrorHandler;
25  
26  /**
27   * A single database table.  A Table instance is retrieved from a {@link
28   * Database} instance.  The Table instance provides access to the table
29   * metadata as well as the table data.  There are basic data operations on the
30   * Table interface (i.e. {@link #iterator} {@link #addRow}, {@link #updateRow}
31   * and {@link #deleteRow}), but for advanced search and data manipulation a
32   * {@link Cursor} instance should be used.  New Tables can be created using a
33   * {@link TableBuilder}.  The {@link com.healthmarketscience.jackcess.util.Joiner} utility can be used to traverse
34   * table relationships (e.g. find rows in another table based on a foreign-key
35   * relationship).
36   * <p/>
37   * A Table instance is not thread-safe (see {@link Database} for more
38   * thread-safety details).
39   *
40   * @author James Ahlborn
41   * @usage _general_class_
42   */
43  public interface Table extends Iterable<Row>
44  {
45    /**
46     * enum which controls the ordering of the columns in a table.
47     * @usage _intermediate_class_
48     */
49    public enum ColumnOrder {
50      /** columns are ordered based on the order of the data in the table (this
51          order does not change as columns are added to the table). */
52      DATA, 
53      /** columns are ordered based on the "display" order (this order can be
54          changed arbitrarily) */
55      DISPLAY;
56    }
57  
58    /**
59     * @return The name of the table
60     * @usage _general_method_
61     */
62    public String getName();
63  
64    /**
65     * Whether or not this table has been marked as hidden.
66     * @usage _general_method_
67     */
68    public boolean isHidden();
69  
70    /**
71     * Whether or not this table is a system (internal) table.
72     * @usage _general_method_
73     */
74    public boolean isSystem();
75  
76    /**
77     * @usage _general_method_
78     */
79    public int getColumnCount();
80  
81    /**
82     * @usage _general_method_
83     */
84    public Database getDatabase();
85  
86    /**
87     * Gets the currently configured ErrorHandler (always non-{@code null}).
88     * This will be used to handle all errors unless overridden at the Cursor
89     * level.
90     * @usage _intermediate_method_
91     */
92    public ErrorHandler getErrorHandler();
93  
94    /**
95     * Sets a new ErrorHandler.  If {@code null}, resets to using the
96     * ErrorHandler configured at the Database level.
97     * @usage _intermediate_method_
98     */
99    public void setErrorHandler(ErrorHandler newErrorHandler);
100 
101   /**
102    * Gets the currently configured auto number insert policy.
103    * @see Database#isAllowAutoNumberInsert
104    * @usage _intermediate_method_
105    */
106   public boolean isAllowAutoNumberInsert();
107 
108   /**
109    * Sets the new auto number insert policy for the Table.  If {@code null},
110    * resets to using the policy configured at the Database level.
111    * @usage _intermediate_method_
112    */
113   public void setAllowAutoNumberInsert(Boolean allowAutoNumInsert);
114 
115   /**
116    * @return All of the columns in this table (unmodifiable List)
117    * @usage _general_method_
118    */
119   public List<? extends Column> getColumns();
120 
121   /**
122    * @return the column with the given name
123    * @usage _general_method_
124    */
125   public Column getColumn(String name);
126 
127   /**
128    * @return the properties for this table
129    * @usage _general_method_
130    */
131   public PropertyMap getProperties() throws IOException;
132 
133   /**
134    * @return All of the Indexes on this table (unmodifiable List)
135    * @usage _intermediate_method_
136    */
137   public List<? extends Index> getIndexes();
138 
139   /**
140    * @return the index with the given name
141    * @throws IllegalArgumentException if there is no index with the given name
142    * @usage _intermediate_method_
143    */
144   public Index getIndex(String name);
145 
146   /**
147    * @return the primary key index for this table
148    * @throws IllegalArgumentException if there is no primary key index on this
149    *         table
150    * @usage _intermediate_method_
151    */
152   public Index getPrimaryKeyIndex();
153 
154   /**
155    * @return the foreign key index joining this table to the given other table
156    * @throws IllegalArgumentException if there is no relationship between this
157    *         table and the given table
158    * @usage _intermediate_method_
159    */
160   public Index getForeignKeyIndex(Table otherTable);
161 
162   /**
163    * Converts a map of columnName -> columnValue to an array of row values
164    * appropriate for a call to {@link #addRow(Object...)}.
165    * @usage _general_method_
166    */
167   public Object[] asRow(Map<String,?> rowMap);
168 
169   /**
170    * Converts a map of columnName -> columnValue to an array of row values
171    * appropriate for a call to {@link Cursor#updateCurrentRow(Object...)}.
172    * @usage _general_method_
173    */
174   public Object[] asUpdateRow(Map<String,?> rowMap);
175 
176   /**
177    * @usage _general_method_
178    */
179   public int getRowCount();
180 
181   /**
182    * Adds a single row to this table and writes it to disk.  The values are
183    * expected to be given in the order that the Columns are listed by the
184    * {@link #getColumns} method.  This is by default the storage order of the
185    * Columns in the database, however this order can be influenced by setting
186    * the ColumnOrder via {@link Database#setColumnOrder} prior to opening
187    * the Table.  The {@link #asRow} method can be used to easily convert a row
188    * Map into the appropriate row array for this Table.
189    * <p>
190    * Note, if this table has an auto-number column, the value generated will be
191    * put back into the given row array (assuming the given row array is at
192    * least as long as the number of Columns in this Table).
193    *
194    * @param row row values for a single row.  the given row array will be
195    *            modified if this table contains an auto-number column,
196    *            otherwise it will not be modified.
197    * @return the given row values if long enough, otherwise a new array.  the
198    *         returned array will contain any autonumbers generated
199    * @usage _general_method_
200    */
201   public Object[] addRow(Object... row) throws IOException;
202 
203   /**
204    * Calls {@link #asRow} on the given row map and passes the result to {@link
205    * #addRow}.
206    * <p/>
207    * Note, if this table has an auto-number column, the value generated will be
208    * put back into the given row map.
209    * @return the given row map, which will contain any autonumbers generated
210    * @usage _general_method_
211    */
212   public <M extends Map<String,Object>> M addRowFromMap(M row) 
213     throws IOException;
214 
215   /**
216    * Add multiple rows to this table, only writing to disk after all
217    * rows have been written, and every time a data page is filled.  This
218    * is much more efficient than calling {@link #addRow} multiple times.
219    * <p>
220    * Note, if this table has an auto-number column, the values written will be
221    * put back into the given row arrays (assuming the given row array is at
222    * least as long as the number of Columns in this Table).
223    * <p>
224    * Most exceptions thrown from this method will be wrapped with a {@link
225    * BatchUpdateException} which gives useful information in the case of a
226    * partially successful write.
227    *
228    * @see #addRow(Object...) for more details on row arrays
229    * 
230    * @param rows List of Object[] row values.  the rows will be modified if
231    *             this table contains an auto-number column, otherwise they
232    *             will not be modified.
233    * @return the given row values list (unless row values were to small), with
234    *         appropriately sized row values (the ones passed in if long
235    *         enough).  the returned arrays will contain any autonumbers
236    *         generated
237    * @usage _general_method_
238    */
239   public List<? extends Object[]> addRows(List<? extends Object[]> rows) 
240     throws IOException;
241 
242   /**
243    * Calls {@link #asRow} on the given row maps and passes the results to
244    * {@link #addRows}.
245    * <p/>
246    * Note, if this table has an auto-number column, the values generated will
247    * be put back into the appropriate row maps.
248    * <p>
249    * Most exceptions thrown from this method will be wrapped with a {@link
250    * BatchUpdateException} which gives useful information in the case of a
251    * partially successful write.
252    * 
253    * @return the given row map list, where the row maps will contain any
254    *         autonumbers generated
255    * @usage _general_method_
256    */
257   public <M extends Map<String,Object>> List<M> addRowsFromMaps(List<M> rows) 
258     throws IOException;
259 
260   /**
261    * Update the given row.  Provided Row must have previously been returned
262    * from this Table.
263    * @return the given row, updated with the current row values
264    * @throws IllegalStateException if the given row is not valid, or deleted.
265    */
266   public Row updateRow(Row row) throws IOException;
267 
268   /**
269    * Delete the given row.  Provided Row must have previously been returned
270    * from this Table.
271    * @return the given row
272    * @throws IllegalStateException if the given row is not valid
273    */
274   public Row deleteRow(Row row) throws IOException;
275 
276   /**
277    * Calls {@link #reset} on this table and returns a modifiable
278    * Iterator which will iterate through all the rows of this table.  Use of
279    * the Iterator follows the same restrictions as a call to
280    * {@link #getNextRow}.
281    * <p/>
282    * For more advanced iteration, use the {@link #getDefaultCursor default
283    * cursor} directly.
284    * @throws RuntimeIOException if an IOException is thrown by one of the
285    *         operations, the actual exception will be contained within
286    * @usage _general_method_
287    */
288   public Iterator<Row> iterator();
289 
290   /**
291    * After calling this method, {@link #getNextRow} will return the first row
292    * in the table, see {@link Cursor#reset} (uses the {@link #getDefaultCursor
293    * default cursor}).
294    * @usage _general_method_
295    */
296   public void reset();
297 
298   /**
299    * @return The next row in this table (Column name -> Column value) (uses
300    *         the {@link #getDefaultCursor default cursor})
301    * @usage _general_method_
302    */
303   public Row getNextRow() throws IOException;
304 
305   /**
306    * @return a simple Cursor, initialized on demand and held by this table.
307    *         This cursor backs the row traversal methods available on the
308    *         Table interface.  For advanced Table traversal and manipulation,
309    *         use the Cursor directly.
310    */
311   public Cursor getDefaultCursor();
312 
313   /**
314    * Convenience method for constructing a new CursorBuilder for this Table.
315    */
316   public CursorBuilder newCursor();
317 }