1 /*
2 * Copyright (c) 2012-2023, jcabi.com
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met: 1) Redistributions of source code must retain the above
8 * copyright notice, this list of conditions and the following
9 * disclaimer. 2) Redistributions in binary form must reproduce the above
10 * copyright notice, this list of conditions and the following
11 * disclaimer in the documentation and/or other materials provided
12 * with the distribution. 3) Neither the name of the jcabi.com nor
13 * the names of its contributors may be used to endorse or promote
14 * products derived from this software without specific prior written
15 * permission.
16 *
17 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
18 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT
19 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
20 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
21 * THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
22 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
23 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
24 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
26 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
28 * OF THE POSSIBILITY OF SUCH DAMAGE.
29 */
30 package com.jcabi.jdbc;
31
32 import java.sql.ResultSet;
33 import java.sql.SQLException;
34 import java.sql.Statement;
35
36 /**
37 * Outcome of ResultSet.
38 *
39 * <p>The following convenience implementations are provided:
40 *
41 * <ul>
42 * <li>{@link Outcome#NOT_EMPTY} to check that at least one result row is
43 * returned.
44 * <li>{@link Outcome#VOID} for when you wish to disregard the result.
45 * <li>{@link Outcome#UPDATE_COUNT} to check the number of updated rows.
46 * </ul>
47 *
48 * @param <T> Type of expected result
49 * @since 0.12
50 */
51 public interface Outcome<T> {
52
53 /**
54 * Returns {@code TRUE} if at least one SQL record found in
55 * {@link ResultSet}.
56 *
57 * <p>The outcome returns the value of {@link ResultSet#next()} and throws
58 * {@link SQLException} in case of a problem.
59 *
60 * @since 0.12
61 */
62 Outcome<Boolean> NOT_EMPTY = (rset, stmt) -> rset.next();
63
64 /**
65 * Outcome that does nothing (and always returns {@code null}).
66 *
67 * <p>Useful when you're not interested in the result:
68 *
69 * <pre> new JdbcSession(source)
70 * .sql("INSERT INTO foo (name) VALUES (?)")
71 * .set("Jeff Lebowski")
72 * .insert(Outcome.VOID);</pre>
73 *
74 * @since 0.12
75 */
76 Outcome<Void> VOID = (rset, stmt) -> Void.TYPE.cast(null);
77
78 /**
79 * Outcome that returns the number of updated rows.
80 *
81 * <p>Use it when you need to determine the number of rows updated:
82 *
83 * <pre> Integer count = new JdbcSession(source)
84 * .sql("UPDATE employee SET salary = 35000 WHERE department = ?")
85 * .set("Finance")
86 * .update(Outcome.UPDATE_COUNT);</pre>
87 *
88 * @since 0.12
89 */
90 Outcome<Integer> UPDATE_COUNT = (rset, stmt) -> stmt.getUpdateCount();
91
92 /**
93 * Outcome that returns last insert ID.
94 *
95 * <p>Use it when you need to get last insert ID from INSERT:
96 *
97 * <pre> long id = new JdbcSession(source)
98 * .sql("INSERT INTO employee (name) VALUES (?)")
99 * .set("Jeffrey")
100 * .insert(Outcome.LAST_INSERT_ID);</pre>
101 *
102 * @since 0.13
103 */
104 Outcome<Long> LAST_INSERT_ID = (rset, stmt) -> {
105 if (!rset.next()) {
106 throw new SQLException("no last_insert_id() available");
107 }
108 return rset.getLong(1);
109 };
110
111 /**
112 * Default mappings.
113 *
114 * @since 0.17.6
115 */
116 Mappings DEFAULT_MAPPINGS = new DefaultMappings();
117
118 /**
119 * Process the result set and return some value.
120 *
121 * @param rset The result set to process
122 * @param stmt The statement used in the run
123 * @return The result
124 * @throws SQLException If something goes wrong inside
125 */
126 T handle(ResultSet rset, Statement stmt) throws SQLException;
127
128 /**
129 * Mapping.
130 *
131 * @param <T> Type of output
132 * @since 0.13
133 */
134 interface Mapping<T> {
135 /**
136 * Map.
137 *
138 * @param rset Result set
139 * @return Object
140 * @throws SQLException If fails
141 */
142 T map(ResultSet rset) throws SQLException;
143 }
144
145 /**
146 * Mappings for different types.
147 *
148 * @since 0.17.6
149 */
150 interface Mappings {
151 /**
152 * Mapping for a type.
153 *
154 * @param tpe Class of result.
155 * @param <T> Type of result.
156 * @return Mapping.
157 */
158 <T> Mapping<T> forType(Class<? extends T> tpe);
159 }
160 }