Changeset: fc32ba68a2cc for monetdb-java URL: https://dev.monetdb.org/hg/monetdb-java/rev/fc32ba68a2cc Removed Files: onclient.txt Modified Files: release.md Branch: default Log Message:
Remove onclient.txt. It is now made available on https://www.monetdb.org/documentation-Aug2024/user-guide/client-interfaces/libraries-drivers/jdbc-driver/#on-client-extension diffs (163 lines): diff --git a/onclient.txt b/onclient.txt deleted file mode 100644 --- a/onclient.txt +++ /dev/null @@ -1,118 +0,0 @@ -COPY ... ON CLIENT ... support in the MonetDB JDBC driver and JdbcClient program. - -MonetDB provides the non-standard COPY INTO statement to perform bulk inserts and -retrievals, see also: -https://www.monetdb.org/documentation/user-guide/sql-manual/data-loading/copy-from/ -https://www.monetdb.org/documentation/user-guide/sql-manual/data-loading/export_data/ - -By default, COPY INTO accesses files on the server but it also has a mode to -access files on the client. This is supported by the command line tool -mclient(1) and now also as an extension to the MonetDB JDBC driver. - -This is how it works: The JDBC client automatically announces that it is capable -of file transfers. If you execute, for example, - - COPY INTO mytable FROM 'data.csv' ON CLIENT; - -the server will send a request for file 'data.csv' to the JDBC driver. -By default, the JDBC driver will refuse with an error message: - 'No file upload handler has been registered with the JDBC driver' - -or in JdbcClient: - 'Error [42000] when opening data.csv: ON CLIENT: No file upload handler has been registered with the JDBC driver' - -This is for security reasons. However, you can register a callback to handle -these requests from the server: - - Connection conn = DriverManager.getConnection(dbUrl, userName, password); - MyUploader handler = new MyUploadHandler(); - conn.unwrap(MonetConnection.class).setUploadHandler(handler); - -or provide the JdbcClient startup argument: --csvdir "/path/to/csvfilesdir" - -Here, MyUploadHandler is an implementation of the interface MonetConnection.UploadHandler, -which signature looks like this: - - public interface UploadHandler { - /** - * Called if the server sends a request to read file data. - * - * Use the given handle to receive data or send errors to the server. - * - * @param handle Handle to communicate with the server - * @param name Name of the file the server would like to read. Make sure - * to validate this before reading from the file system - * @param textMode Whether to open the file as text or binary data. - * @param linesToSkip In text mode, number of initial lines to skip. - * 0 means upload everything, 1 means skip the first line, etc. - * Note: this is different from the OFFSET option of the COPY INTO, - * where both 0 and 1 mean 'upload everything' - * @throws IOException when I/O problem occurs - */ - void handleUpload(Upload handle, String name, boolean textMode, long linesToSkip) throws IOException; - - /** - * Called when the upload is cancelled halfway by the server. - * - * The default implementation does nothing. - */ - default void uploadCancelled() {} - } - -In your implementation of handleUpload(), you can use the 'handle' object to -communicate with the server, for example: - -- PrintStream handle.getStream() to obtain a stream object to which you can write. - This is useful if you want to generate the data on the fly. - -- void uploadFrom(InputStream stream) to have the JDBC driver read data from the - stream and send it to the server as-is. For text mode uploads this means the - text must be UTF-8 encoded. - -- void handle.uploadFrom(Reader reader) to have the JDBC driver read text from the given - Reader and upload it. - -- void handle.uploadFrom(BufferedReader reader, long linesToSkip) to have the JDBC - driver read from the given BufferedReader and upload the text, skipping the first - 'linesToSkip' lines. Typically you would use the value passed to handleUpload in - parameter 'linesToSkip'. - -- void handle.sendError(String errorMessage) to refuse the upload. - -See also: - https://www.monetdb.org/hg/monetdb-java/file/tip/src/main/java/org/monetdb/jdbc/MonetConnection.java#l3546 - -If you use sendError() to refuse the upload, the COPY INTO statement will fail but -the connection will remain usable. On the other hand, if your implementation of -handleUpload throws an IOException, the connection will be closed because there -is currently no way to signal errors to the server once the transfer has begun. - - -The interface for DownloadHandler is: - - public interface DownloadHandler { - /** - * Called if the server sends a request to write a file. - * - * Use the given handle to send data or errors to the server. - * - * @param handle Handle to communicate with the server - * @param name Name of the file the server would like to write. Make sure - * to validate this before writing to the file system - * @param textMode Whether this is text or binary data. - * @throws IOException when I/O problem occurs - */ - void handleDownload(Download handle, String name, boolean textMode) throws IOException; - } - - -Class org.monetdb.util.FileTransferHandler provides a default implementation -of both MonetConnection.UploadHandler and MonetConnection.DownloadHandler for -reading from and writing to local csv files. -You pass the FileTransferHandler constructor a directory name and a Charset to -specify the encoding used for the data in the csv files. -FileTransferHandler class is intended for situations where you do not need to -generate or transform data while uploading or downloading to a file. -See also: - https://www.monetdb.org/hg/monetdb-java/file/tip/src/main/java/org/monetdb/util/FileTransferHandler.java#l29 - diff --git a/release.md b/release.md --- a/release.md +++ b/release.md @@ -89,36 +89,6 @@ The old driver class (nl.cwi.monetdb.jdb since 12 Nov 2020 and has been removed in release 3.4 (monetdb-jdbc-3.4.jre8.jar). -ON CLIENT support ------------------ - -Since release 3.2 (monetdb-jdbc-3.2.jre8.jar), the MonetDB JDBC driver has -support for the ON CLIENT clause of the COPY statement. To use -this functionality you must register handlers for upload and download of data. -The MonetConnection class has been extended with 2 methods: - -* public void setUploadHandler(UploadHandler uploadHandler) -* public void setDownloadHandler(DownloadHandler downloadHandler) - -The API has been extended with some further interfaces and utility classes: -* public interface org.monetdb.jdbc.MonetConnection.UploadHandler -* public interface org.monetdb.jdbc.MonetConnection.DownloadHandler -* public static class org.monetdb.jdbc.MonetConnection.Upload -* public static class org.monetdb.jdbc.MonetConnection.Download -* public class org.monetdb.util.FileTransferHandler - which implements the UploadHandler and DownloadHandler interfaces. - -See file onclient.txt for more information on how to use these from Java. - -The JdbcClient application has also been extended to support COPY ... -ON CLIENT functionality. However for security reasons you must provide an -explicit new startup argument - --csvdir "/path/to/csvdatafiles" -or on MS Windows - --csvdir "C:\\path\\to\\csvdatafiles" -in order to allow the JdbcClient to access local files. - - Notes and tips -------------- _______________________________________________ checkin-list mailing list -- [email protected] To unsubscribe send an email to [email protected]
