001/*
002 * Copyright (C) 2014 Jörg Prante
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.xbib.elasticsearch.river.jdbc;
017
018import org.xbib.elasticsearch.plugin.jdbc.keyvalue.KeyValueStreamListener;
019import org.xbib.elasticsearch.plugin.jdbc.util.SQLCommand;
020
021import java.io.IOException;
022import java.sql.CallableStatement;
023import java.sql.Connection;
024import java.sql.PreparedStatement;
025import java.sql.ResultSet;
026import java.sql.SQLException;
027import java.sql.Statement;
028import java.text.ParseException;
029import java.util.List;
030import java.util.Locale;
031import java.util.Map;
032import java.util.TimeZone;
033
034/**
035 * The river source models the data producing side
036 */
037public interface RiverSource<RC extends RiverContext> {
038
039    /**
040     * The strategy this river source supports.
041     *
042     * @return the strategy as a string
043     */
044    String strategy();
045
046    /**
047     * Create new river source instance
048     *
049     * @return a new river source instance
050     */
051    RiverSource<RC> newInstance();
052
053    /**
054     * Set the river context
055     *
056     * @param context the context
057     * @return this river source
058     */
059    RiverSource setRiverContext(RC context);
060
061    /**
062     * Executed before fetch() is executed
063     *
064     * @throws Exception
065     */
066    void beforeFetch() throws Exception;
067
068    /**
069     * Fetch a data portion from the database and pass it to the river task
070     * for firther processing.
071     *
072     * @throws Exception when execution gives an error
073     */
074    void fetch() throws Exception;
075
076    /**
077     * Executed after fetch() has been executed or threw an exception.
078     *
079     * @throws Exception
080     */
081    void afterFetch() throws Exception;
082
083    /**
084     * Set JDBC connection URL
085     *
086     * @param url the JDBC connection URL
087     * @return this river source
088     */
089    RiverSource setUrl(String url);
090
091    /**
092     * Set the user authentication
093     *
094     * @param user the user
095     * @return this river source
096     */
097    RiverSource setUser(String user);
098
099    /**
100     * Set the password authentication
101     *
102     * @param password the password
103     * @return this river source
104     */
105    RiverSource setPassword(String password);
106
107    /**
108     * Get a connection for reading data
109     *
110     * @return connection
111     * @throws SQLException when SQL execution gives an error
112     */
113    Connection getConnectionForReading() throws SQLException;
114
115    /**
116     * Get a connection for writing data
117     *
118     * @return connection
119     * @throws SQLException when SQL execution gives an error
120     */
121    Connection getConnectionForWriting() throws SQLException;
122
123    /**
124     * Prepare query statement
125     *
126     * @param sql SQL statement
127     * @return a prepared statement
128     * @throws SQLException when SQL execution gives an error
129     */
130    PreparedStatement prepareQuery(String sql) throws SQLException;
131
132    /**
133     * Prepare insert/update statement
134     *
135     * @param sql SQL statement
136     * @return a prepared statement
137     * @throws SQLException when SQL execution gives an error
138     */
139    PreparedStatement prepareUpdate(String sql) throws SQLException;
140
141    /**
142     * Bind query variables
143     *
144     * @param statement prepared statement
145     * @param values    values
146     * @return this river source
147     * @throws SQLException when SQL execution gives an error
148     */
149    RiverSource bind(PreparedStatement statement, List<Object> values) throws SQLException;
150
151    /**
152     * Register output variables for callable statement
153     *
154     * @param statement callable statement
155     * @param values    values
156     * @return this river source
157     * @throws SQLException when SQL execution gives an error
158     */
159    RiverSource register(CallableStatement statement, Map<String, Object> values) throws SQLException;
160
161    /**
162     * Execute query
163     *
164     * @param statement prepared statement
165     * @return the result set
166     * @throws SQLException when SQL execution gives an error
167     */
168    ResultSet executeQuery(PreparedStatement statement) throws SQLException;
169
170    /**
171     * Execute query without binding parameters
172     *
173     * @param statement the SQL statement
174     * @param sql       the SQL query
175     * @return the result set
176     * @throws SQLException when SQL execution gives an error
177     */
178    ResultSet executeQuery(Statement statement, String sql) throws SQLException;
179
180    /**
181     * Execute insert/update
182     *
183     * @param statement statement
184     * @return this river source
185     * @throws SQLException when SQL execution gives an error
186     */
187    RiverSource executeUpdate(PreparedStatement statement) throws SQLException;
188
189    /**
190     * Execute insert update
191     *
192     * @param statement statement
193     * @param sql       SQL query
194     * @return this river source
195     * @throws SQLException
196     */
197    RiverSource executeUpdate(Statement statement, String sql) throws SQLException;
198
199    /**
200     * Executed before rows are fetched from result set
201     *
202     * @param results  the result set
203     * @param listener a result set listener or null
204     * @throws SQLException
205     * @throws IOException
206     */
207    void beforeRows(ResultSet results, KeyValueStreamListener listener) throws SQLException, IOException;
208
209    /**
210     * Executed when next row is fetched from result set
211     *
212     * @param results  the result set
213     * @param listener a result set listener or null
214     * @return true if next row could be processed, otherwise false
215     * @throws SQLException
216     * @throws IOException
217     */
218    boolean nextRow(ResultSet results, KeyValueStreamListener listener) throws SQLException, IOException;
219
220    /**
221     * Executed after all rows have been fetched from result set
222     *
223     * @param results  the result set
224     * @param listener a result set listener or null
225     * @throws SQLException
226     * @throws IOException
227     */
228    void afterRows(ResultSet results, KeyValueStreamListener listener) throws SQLException, IOException;
229
230    /**
231     * This routine is executed before the result set is evaluated
232     *
233     * @param command  the SQL command that created this result set
234     * @param results  the result set
235     * @param listener listener for the key/value stream generated from the result set
236     * @throws SQLException
237     * @throws IOException
238     */
239    void beforeRows(SQLCommand command, ResultSet results, KeyValueStreamListener listener) throws SQLException, IOException;
240
241    /**
242     * Action for the next row of the result set to be processed
243     *
244     * @param results  result
245     * @param listener listener
246     * @return true if next row exists
247     * @throws SQLException when SQL execution gives an error
248     * @throws IOException  when input/output error occurs
249     */
250    boolean nextRow(SQLCommand command, ResultSet results, KeyValueStreamListener listener) throws SQLException, IOException;
251
252    /**
253     * After the result set is processed, this method is called.
254     *
255     * @param command  the SQL command that created this result set
256     * @param results  the result set
257     * @param listener listener for the key/value stream generated from the result set
258     * @throws SQLException
259     * @throws IOException
260     */
261    void afterRows(SQLCommand command, ResultSet results, KeyValueStreamListener listener) throws SQLException, IOException;
262
263    /**
264     * Parse a value in a row column
265     *
266     * @param results result set
267     * @param num     position
268     * @param type    type
269     * @param locale  locale
270     * @return object
271     * @throws SQLException   when SQL execution gives an error
272     * @throws IOException    when input/output error occurs
273     * @throws ParseException if number format could not be parsed
274     */
275    Object parseType(ResultSet results, Integer num, int type, Locale locale) throws SQLException, IOException, ParseException;
276
277    /**
278     * Close result set
279     *
280     * @param result result set
281     * @return this river source
282     * @throws SQLException when SQL execution gives an error
283     */
284    RiverSource close(ResultSet result) throws SQLException;
285
286    /**
287     * Close statement
288     *
289     * @param statement statement
290     * @return this river source
291     * @throws SQLException when SQL execution gives an error
292     */
293    RiverSource close(Statement statement) throws SQLException;
294
295    /**
296     * Close reading from this river source
297     *
298     * @return this river source
299     */
300    RiverSource closeReading();
301
302    /**
303     * Close writing to this river source
304     *
305     * @return this river source
306     */
307    RiverSource closeWriting();
308
309    /**
310     * Set the locale for JDBC
311     *
312     * @param locale locale
313     * @return this river source
314     */
315    RiverSource setLocale(Locale locale);
316
317    /**
318     * Get the current locale
319     *
320     * @return the time zone
321     */
322    Locale getLocale();
323
324    /**
325     * Set the timezone for JDBC setTimestamp() calls with calendar object.
326     *
327     * @param timeZone the time zone
328     * @return this river source
329     */
330    RiverSource setTimeZone(TimeZone timeZone);
331
332    /**
333     * Get the current timezone of this river source for the JDBC setTimestamp() call
334     *
335     * @return the time zone
336     */
337    TimeZone getTimeZone();
338
339    /**
340     * Suspend river source
341     *
342     * @throws Exception
343     */
344    void suspend() throws Exception;
345
346    /**
347     * Resume river source
348     *
349     * @throws Exception
350     */
351    void resume() throws Exception;
352
353    /**
354     * Shutdown source
355     *
356     * @throws IOException
357     */
358    void shutdown() throws IOException;
359
360}