Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
KeyedHandler |
|
| 1.2222222222222223;1.222 |
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 | package org.apache.commons.dbutils.handlers; | |
18 | ||
19 | import java.sql.ResultSet; | |
20 | import java.sql.SQLException; | |
21 | import java.util.HashMap; | |
22 | import java.util.Map; | |
23 | ||
24 | import org.apache.commons.dbutils.ResultSetHandler; | |
25 | import org.apache.commons.dbutils.RowProcessor; | |
26 | ||
27 | /** | |
28 | * <p> | |
29 | * <code>ResultSetHandler</code> implementation that returns a Map of Maps. | |
30 | * <code>ResultSet</code> rows are converted into Maps which are then stored | |
31 | * in a Map under the given key. Although this implementation uses Maps to | |
32 | * store row contents, subclasses are encouraged to override the | |
33 | * <code>createRow()</code> method to convert the rows into any kind of object. | |
34 | * </p> | |
35 | * <p> | |
36 | * If you had a Person table with a primary key column called ID, you could | |
37 | * retrieve rows from the table like this: | |
38 | * <pre> | |
39 | * ResultSetHandler h = new KeyedHandler("id"); | |
40 | * Map found = (Map) queryRunner.query("select id, name, age from person", h); | |
41 | * Map jane = (Map) found.get(new Long(1)); // jane's id is 1 | |
42 | * String janesName = (String) jane.get("name"); | |
43 | * Integer janesAge = (Integer) jane.get("age"); | |
44 | * </pre> | |
45 | * Note that the "id" passed to KeyedHandler and "name" and "age" passed to the | |
46 | * returned Map's get() method can be in any case. The data types returned for | |
47 | * name and age are dependent upon how your JDBC driver converts SQL column | |
48 | * types from the Person table into Java types. | |
49 | * </p> | |
50 | * <p> | |
51 | * To avoid these type issues you could subclass KeyedHandler and override | |
52 | * <code>createRow()</code> to store rows in Java bean instances (ie. a | |
53 | * Person class). | |
54 | * </p> | |
55 | * <p>This class is thread safe.</p> | |
56 | * | |
57 | * @see org.apache.commons.dbutils.ResultSetHandler | |
58 | * @since DbUtils 1.1 | |
59 | */ | |
60 | public class KeyedHandler implements ResultSetHandler { | |
61 | ||
62 | /** | |
63 | * The RowProcessor implementation to use when converting rows | |
64 | * into Objects. | |
65 | */ | |
66 | protected final RowProcessor convert; | |
67 | ||
68 | /** | |
69 | * The column index to retrieve key values from. Defaults to 1. | |
70 | */ | |
71 | protected final int columnIndex; | |
72 | ||
73 | /** | |
74 | * The column name to retrieve key values from. Either columnName or | |
75 | * columnIndex will be used but never both. | |
76 | */ | |
77 | protected final String columnName; | |
78 | ||
79 | /** | |
80 | * Creates a new instance of KeyedHandler. The value of the first column | |
81 | * of each row will be a key in the Map. | |
82 | */ | |
83 | public KeyedHandler() { | |
84 | 0 | this(ArrayHandler.ROW_PROCESSOR, 1, null); |
85 | 0 | } |
86 | ||
87 | /** | |
88 | * Creates a new instance of KeyedHandler. The value of the first column | |
89 | * of each row will be a key in the Map. | |
90 | * | |
91 | * @param convert The <code>RowProcessor</code> implementation | |
92 | * to use when converting rows into Maps | |
93 | */ | |
94 | public KeyedHandler(RowProcessor convert) { | |
95 | 0 | this(convert, 1, null); |
96 | 0 | } |
97 | ||
98 | /** | |
99 | * Creates a new instance of KeyedHandler. | |
100 | * | |
101 | * @param columnIndex The values to use as keys in the Map are | |
102 | * retrieved from the column at this index. | |
103 | */ | |
104 | public KeyedHandler(int columnIndex) { | |
105 | 0 | this(ArrayHandler.ROW_PROCESSOR, columnIndex, null); |
106 | 0 | } |
107 | ||
108 | /** | |
109 | * Creates a new instance of KeyedHandler. | |
110 | * | |
111 | * @param columnName The values to use as keys in the Map are | |
112 | * retrieved from the column with this name. | |
113 | */ | |
114 | public KeyedHandler(String columnName) { | |
115 | 0 | this(ArrayHandler.ROW_PROCESSOR, 1, columnName); |
116 | 0 | } |
117 | ||
118 | // Helper | |
119 | private KeyedHandler(RowProcessor convert, int columnIndex, | |
120 | String columnName) { | |
121 | 0 | super(); |
122 | 0 | this.convert = convert; |
123 | 0 | this.columnIndex = columnIndex; |
124 | 0 | this.columnName = columnName; |
125 | 0 | } |
126 | ||
127 | /** | |
128 | * Convert each row's columns into a Map and store then | |
129 | * in a <code>Map</code> under <code>ResultSet.getObject(key)</code> key. | |
130 | * | |
131 | * @return A <code>Map</code> of Maps, never <code>null</code>. | |
132 | * @throws SQLException if a database access error occurs | |
133 | * @see org.apache.commons.dbutils.ResultSetHandler#handle(java.sql.ResultSet) | |
134 | */ | |
135 | public Object handle(ResultSet rs) throws SQLException { | |
136 | 0 | Map result = createMap(); |
137 | 0 | while (rs.next()) { |
138 | 0 | result.put(createKey(rs), createRow(rs)); |
139 | } | |
140 | 0 | return result; |
141 | } | |
142 | ||
143 | /** | |
144 | * This factory method is called by <code>handle()</code> to create the Map | |
145 | * to store records in. This implementation returns a <code>HashMap</code> | |
146 | * instance. | |
147 | * | |
148 | * @return Map to store records in | |
149 | */ | |
150 | protected Map createMap() { | |
151 | 0 | return new HashMap(); |
152 | } | |
153 | ||
154 | /** | |
155 | * This factory method is called by <code>handle()</code> to retrieve the | |
156 | * key value from the current <code>ResultSet</code> row. This | |
157 | * implementation returns <code>ResultSet.getObject()</code> for the | |
158 | * configured key column name or index. | |
159 | * @param rs ResultSet to create a key from | |
160 | * @return Object from the configured key column name/index | |
161 | * @throws SQLException if a database access error occurs | |
162 | */ | |
163 | protected Object createKey(ResultSet rs) throws SQLException { | |
164 | 0 | return (columnName == null) ? rs.getObject(columnIndex) : rs |
165 | .getObject(columnName); | |
166 | } | |
167 | ||
168 | /** | |
169 | * This factory method is called by <code>handle()</code> to store the | |
170 | * current <code>ResultSet</code> row in some object. This | |
171 | * implementation returns a <code>Map</code> with case insensitive column | |
172 | * names as keys. Calls to <code>map.get("COL")</code> and | |
173 | * <code>map.get("col")</code> return the same value. | |
174 | * @param rs ResultSet to create a row from | |
175 | * @return Object typed Map containing column names to values | |
176 | * @throws SQLException if a database access error occurs | |
177 | */ | |
178 | protected Object createRow(ResultSet rs) throws SQLException { | |
179 | 0 | return this.convert.toMap(rs); |
180 | } | |
181 | ||
182 | } |