1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package java.sql; 19 20 import java.util.Map; 21 22 /** 23 * A Java representation of the SQL {@code ARRAY} type. 24 */ 25 public interface Array { 26 27 /** 28 * Retrieves the contents of the SQL {@code ARRAY} value as a Java array 29 * object. 30 * 31 * @return A Java array containing the elements of this Array 32 * @throws SQLException 33 * if there is a database error. 34 */ 35 public Object getArray() throws SQLException; 36 37 /** 38 * Returns part of the SQL {@code ARRAY} associated with this array, 39 * starting at a particular {@code index} and comprising up to {@code count} 40 * successive elements of the SQL array. 41 * 42 * @param index 43 * the start position in the array where the values are 44 * retrieved. 45 * @param count 46 * the number of elements to retrieve. 47 * @return A Java array containing the desired set of elements from this Array 48 * @throws SQLException 49 * if there is a database error. 50 */ 51 public Object getArray(long index, int count) throws SQLException; 52 53 /** 54 * Returns part of the SQL {@code ARRAY} associated with this array, 55 * starting at a particular {@code index} and comprising up to {@code count} 56 * successive elements of the SQL array. 57 * 58 * @param index 59 * the start position in the array where the values are 60 * retrieved. 61 * @param count 62 * the number of elements to retrieve. 63 * @param map 64 * the map defining the correspondence between SQL type names 65 * and Java types. 66 * @return A Java array containing the desired set of elements from this Array 67 * @throws SQLException 68 * if there is a database error. 69 */ 70 public Object getArray(long index, int count, Map<String, Class<?>> map) 71 throws SQLException; 72 73 /** 74 * Returns the data from the underlying SQL {@code ARRAY} as a Java array. 75 * 76 * @param map 77 * the map defining the correspondence between SQL type names 78 * and Java types. 79 * @return A Java array containing the elements of this array 80 * @throws SQLException 81 * if there is a database error. 82 */ 83 public Object getArray(Map<String, Class<?>> map) throws SQLException; 84 85 /** 86 * Returns the JDBC type of the entries in this array's underlying 87 * SQL array. 88 * 89 * @return An integer constant from the {@code java.sql.Types} class 90 * @throws SQLException 91 * if there is a database error. 92 */ 93 public int getBaseType() throws SQLException; 94 95 /** 96 * Returns the SQL type name of the entries in this array's underlying 97 * SQL array. 98 * 99 * @return The database specific name or a fully-qualified SQL type name. 100 * @throws SQLException 101 * if there is a database error. 102 */ 103 public String getBaseTypeName() throws SQLException; 104 105 /** 106 * Returns a ResultSet object which holds the entries of the SQL {@code 107 * ARRAY} associated with this array. 108 * 109 * @return the elements of the array as a {@code ResultSet}. 110 * @throws SQLException 111 * if there is a database error. 112 */ 113 public ResultSet getResultSet() throws SQLException; 114 115 /** 116 * Returns a {@code ResultSet} object that holds the entries of a subarray, 117 * beginning at a particular index and comprising up to {@code count} 118 * successive entries. 119 * 120 * @param index 121 * the start position in the array where the values are 122 * retrieved. 123 * @param count 124 * the number of elements to retrieve. 125 * @return the elements of the array as a {@code ResultSet}. 126 * @throws SQLException 127 * if there is a database error. 128 */ 129 public ResultSet getResultSet(long index, int count) throws SQLException; 130 131 /** 132 * Returns a {@code ResultSet} object that holds the entries of a subarray, 133 * beginning at a particular index and comprising up to {@code count} 134 * successive entries. 135 * 136 * @param index 137 * the start position in the array where the values are 138 * retrieved. 139 * @param count 140 * the number of elements to retrieve. 141 * @param map 142 * the map defining the correspondence between SQL type names 143 * and Java types. 144 * @return the {@code ResultSet} the array's custom type values. if a 145 * database error has occurred. 146 * @throws SQLException 147 * if there is a database error. 148 */ 149 public ResultSet getResultSet(long index, int count, 150 Map<String, Class<?>> map) throws SQLException; 151 152 /** 153 * Returns a {@code ResultSet} object which holds the entries of the SQL 154 * {@code ARRAY} associated with this array. 155 * 156 * @param map 157 * the map defining the correspondence between SQL type names 158 * and Java types. 159 * @return the array as a {@code ResultSet}. 160 * @throws SQLException 161 * if there is a database error. 162 */ 163 public ResultSet getResultSet(Map<String, Class<?>> map) 164 throws SQLException; 165 166 /** 167 * Frees any resources held by this array. After {@code free} is called, calling 168 * method other than {@code free} will throw {@code SQLException} (calling {@code free} 169 * repeatedly will do nothing). 170 * @throws SQLException 171 */ 172 public void free() throws SQLException; 173 } 174
