123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366 |
- /*
- 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.time.LocalDateTime;
- import java.util.Iterator;
- import java.util.List;
- import java.util.Map;
- import java.util.stream.Stream;
- import java.util.stream.StreamSupport;
-
- import com.healthmarketscience.jackcess.util.ErrorHandler;
- import com.healthmarketscience.jackcess.util.OleBlob;
-
- /**
- * 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>, TableDefinition
- {
- /**
- * 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_
- */
- @Override
- public String getName();
-
- /**
- * Whether or not this table has been marked as hidden.
- * @usage _general_method_
- */
- @Override
- public boolean isHidden();
-
- /**
- * Whether or not this table is a system (internal) table.
- * @usage _general_method_
- */
- @Override
- public boolean isSystem();
-
- /**
- * @usage _general_method_
- */
- @Override
- public int getColumnCount();
-
- /**
- * @usage _general_method_
- */
- @Override
- 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_
- */
- @Override
- public List<? extends Column> getColumns();
-
- /**
- * @return the column with the given name
- * @usage _general_method_
- */
- @Override
- public Column getColumn(String name);
-
- /**
- * @return the properties for this table
- * @usage _general_method_
- */
- @Override
- public PropertyMap getProperties() throws IOException;
-
- /**
- * @return the created date for this table if available
- * @usage _general_method_
- */
- @Override
- public LocalDateTime getCreatedDate() throws IOException;
-
- /**
- * Note: jackcess <i>does not automatically update the modified date of a
- * Table</i>.
- *
- * @return the last updated date for this table if available
- * @usage _general_method_
- */
- @Override
- public LocalDateTime getUpdatedDate() throws IOException;
-
- /**
- * @return All of the Indexes on this table (unmodifiable List)
- * @usage _intermediate_method_
- */
- @Override
- 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_
- */
- @Override
- 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_
- */
- @Override
- 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_
- */
- @Override
- 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();
-
- /**
- * @return a Stream using the default Iterator.
- */
- default public Stream<Row> stream() {
- return StreamSupport.stream(spliterator(), false);
- }
-
- /**
- * 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();
-
-
- /**
- * Convenience method for constructing a new OleBlob.Builder.
- */
- default public OleBlob.Builder newBlob() {
- return new OleBlob.Builder();
- }
- }
|