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