Changeset: daf6a3b828f9 for monetdb-java URL: https://dev.monetdb.org/hg/monetdb-java/rev/daf6a3b828f9 Added Files: example/OnClientExample.java onclient.txt Removed Files: src/main/java/OnClientExample.java Modified Files: release.txt Branch: onclient Log Message:
Add onclient.txt and refer to it from release.txt Also move OnClientExample.java to directory examples/ diffs (102 lines): diff --git a/src/main/java/OnClientExample.java b/example/OnClientExample.java rename from src/main/java/OnClientExample.java rename to example/OnClientExample.java diff --git a/onclient.txt b/onclient.txt new file mode 100644 --- /dev/null +++ b/onclient.txt @@ -0,0 +1,75 @@ +ON CLIENT support + +MonetDB provides the nonstandard COPY INTO statement to perform bulk inserts and +retrievals, see also +https://www.monetdb.org/Documentation/ServerAdministration/LoadingBulkData. + +By default, COPY INTO accesses files on the server but it also has a mode to +access files on the client. This has long been supported by the command line +tool mclient(1) and is now also supported 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'. + +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); + +Here, MyUploadHandler is an implementation of the interface MonetUploadHandler, +whose main component is the method + + /** + * Called if the server sends a request to write a file. + * + * 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 this is text or binary data. + */ + void handleUpload(MonetConnection.Upload handle, String name, boolean textMode, int offset) + throws IOException; + +In your implementation of this method, you can use the 'handle' object to +communicate with the server, for example: + +- PrintStream 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 uploadFrom(Reader reader) to have the JDBC driver read text from the given + Reader and upload it. + +- void uploadFrom(BufferedReader reader, int offset) to have the JDBC driver read from + the given BufferedReader, and upload the text starting at line 'offset'. Typically + you would use the offset passed to handleUpload in parameter 'offset'. + +- void sendError(String errorMessage) to refuse the upload. + +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 you implementation of +handleUpload throws an IO Exception, the connection will be closed because there +is no way to signal errors to the server once the transfer has begun. + +The interface for downloading is similar to that for uploading. + +Class org.monetdb.util.FileTransferHandler provides a default implementation of +both MonetUploadHandler and MonetDownloadHandler. You pass it a directory name +and a flag indicating whether the contents of that directory can be assumed to +be UTF-8 encoded. It is intended for situations where you do not need to +generate or transform data while uploading. \ No newline at end of file diff --git a/release.txt b/release.txt --- a/release.txt +++ b/release.txt @@ -185,6 +185,9 @@ The following java.sql.* interfaces are * java.sql.SQLXML * java.sql.Struct +Since version VERSION_NUMBER, the MonetDB JDBC driver has support for the +ON CLIENT clause of the COPY statement. You can register callback to provide +data when the server asks for it, see onclient.txt for more information. Notes and Tips for Java Programmers using MonetDB JDBC driver: - Close JDBC ResultSet, Statement, PreparedStatement, CallableStatement and @@ -248,4 +251,3 @@ Warning: Note: as of Febr 2021 (monetdb-jdbc-3.0.jre8.jar) we compile all the java sources to target: Java SE 8 (profile compact2), so you need a JRE/JDK JVM of version 8 or higher to use it. - _______________________________________________ checkin-list mailing list [email protected] https://www.monetdb.org/mailman/listinfo/checkin-list
