changeset 944:fc32ba68a2cc

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
author Martin van Dinther <martin.van.dinther@monetdbsolutions.com>
date Thu, 09 Jan 2025 14:14:52 +0100 (2 months ago)
parents ff075ed5ce81
children 4dd3bc7162f6
files onclient.txt release.md
diffstat 2 files changed, 0 insertions(+), 148 deletions(-) [+]
line wrap: on
line diff
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
-
--- 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
 --------------