View Javadoc
1   /*
2   Copyright (c) 2008 Health Market Science, Inc.
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.util;
18  
19  import java.io.IOException;
20  
21  import com.healthmarketscience.jackcess.Column;
22  import com.healthmarketscience.jackcess.Table;
23  
24  /**
25   * Handler for errors encountered while reading a column of row data from a
26   * Table.  An instance of this class may be configured at the Database, Table,
27   * or Cursor level to customize error handling as desired.  The default
28   * instance used is {@link #DEFAULT}, which just rethrows any exceptions
29   * encountered.
30   * 
31   * @author James Ahlborn
32   * @usage _intermediate_class_
33   */
34  public interface ErrorHandler 
35  {
36    /**
37     * default error handler used if none provided (just rethrows exception)
38     * @usage _general_field_
39     */
40    public static final ErrorHandler DEFAULT = new ErrorHandler() {
41        public Object handleRowError(Column column, byte[] columnData,
42                                     Location location, Exception error)
43          throws IOException
44        {
45          // really can only be RuntimeException or IOException
46          if(error instanceof IOException) {
47            throw (IOException)error;
48          }
49          throw (RuntimeException)error;
50        }
51      };
52  
53    /**
54     * Handles an error encountered while reading a column of data from a Table
55     * row.  Handler may either throw an exception (which will be propagated
56     * back to the caller) or return a replacement for this row's column value
57     * (in which case the row will continue to be read normally).
58     *
59     * @param column the info for the column being read
60     * @param columnData the actual column data for the column being read (which
61     *                   may be {@code null} depending on when the exception
62     *                   was thrown during the reading process)
63     * @param location the current location of the error
64     * @param error the error that was encountered
65     *
66     * @return replacement for this row's column
67     */
68    public Object handleRowError(Column column,
69                                 byte[] columnData,
70                                 Location location,
71                                 Exception error)
72      throws IOException;
73  
74    /**
75     * Provides location information for an error.
76     */
77    public interface Location 
78    {
79      /**
80       * @return the table in which the error occurred
81       */
82      public Table getTable();
83  
84      /**
85       * Contains details about the errored row, useful for debugging.
86       */
87      public String toString();
88    }
89  }