monetdb-java: src/main/java/org/monetdb/mcl/net/MapiSocket.java comparison

comparison src/main/java/org/monetdb/mcl/net/MapiSocket.java @ 834:5aa19bbed0d6 monetdbs

Comments and formatting

author	Joeri van Ruth <joeri.van.ruth@monetdbsolutions.com>
date	Wed, 13 Dec 2023 15:39:47 +0100 (17 months ago)
parents	ede3a59ff4f2
children	071be9a628e8

comparison

equal deleted inserted replaced

-:a71afa48f269
+:5aa19bbed0d6
 import java.net.*;
 import java.nio.charset.StandardCharsets;
 import java.security.MessageDigest;
 import java.security.NoSuchAlgorithmException;
 import java.util.*;
-import java.util.stream.Collectors;
 import org.monetdb.mcl.MCLException;
 import org.monetdb.mcl.io.BufferedMCLReader;
 import org.monetdb.mcl.io.BufferedMCLWriter;
 import org.monetdb.mcl.io.LineType;
 * @version 4.3
 * @see org.monetdb.mcl.io.BufferedMCLReader
 * @see org.monetdb.mcl.io.BufferedMCLWriter
 */
 public final class MapiSocket {
-	public static final byte[] NUL_BYTES = new byte[]{ 0, 0, 0, 0, 0, 0, 0, 0, };
+	/* an even number of NUL bytes used during the handshake */
+	private static final byte[] NUL_BYTES = new byte[]{ 0, 0, 0, 0, 0, 0, 0, 0, };
+	/* A mapping between hash algorithm names as used in the MAPI
+	 * protocol, and the names by which the Java runtime knows them.
+	 */
 	private static final String[][] KNOWN_ALGORITHMS = new String[][] {
 			{"SHA512", "SHA-512"},
 			{"SHA384", "SHA-384"},
 			{"SHA256", "SHA-256"},
 			// should we deprecate this by now?
 	public List<String> connect(String url, Properties props) throws URISyntaxException, ValidationError, MCLException, MCLParseException, IOException {
 		return connect(new Target(url, props), null);
 	}
+		/**
+	 * Connect according to the settings in the 'target' parameter.
+	 * If followRedirect is false, a RedirectionException is
+	 * thrown when a redirect is encountered.
+	 *
+	 * Some settings, such as the initial reply size, can already be configured
+	 * during the handshake, saving a command round-trip later on.
+	 * To do so, create and pass a subclass of {@link MapiSocket.OptionsCallback}.
+	 *
+	 * @param target the connection settings
+	 * @param callback will be called if the server allows options to be set during the
+	 * initial handshake
+	 * @return A List with informational (warning) messages. If this
+	 *		list is empty; then there are no warnings.
+	 * @throws IOException if an I/O error occurs when creating the socket
+	 * @throws SocketException - if there is an error in the underlying protocol, such as a TCP error.
+	 * @throws UnknownHostException if the IP address of the host could not be determined
+	 * @throws MCLParseException if bogus data is received
+	 * @throws MCLException if an MCL related error occurs
+	 */
 	public List<String> connect(Target target, OptionsCallback callback) throws MCLException, MCLParseException, IOException {
 		// get rid of any earlier connection state, including the existing target
 		close();
 		this.target = target;
 appendPrefixHere.append(mapiName);
 appendPrefixHere.append('}');
 }
 return digest;
 }
-		String algoNames = algos.stream().collect(Collectors.joining());
+		String algoNames = String.join(",", algos);
 		throw new MCLException("No supported hash algorithm: " + algoNames);
 	}
 	private void hexhash(StringBuilder buffer, MessageDigest digest, String text) {
 		byte[] bytes = text.getBytes(StandardCharsets.UTF_8);
 			else
 				return off - origOff;
 		}
 	}
+	/**
+	 * Callback used during the initial MAPI handshake.
+	 *
+	 * Newer MonetDB versions allow setting some options during the handshake.
+	 * The options are language-specific and each has a 'level'. The server
+	 * advertises up to which level options are supported for a given language
+	 * and for each language/option combination, {@link addOptions} will be invoked.
+	 * It should call {@link contribute} for each option it wants to set.
+	 *
+	 * At the time of writing, only the 'sql' language supports options,
+	 * they are listed in enum mapi_handshake_options_levels in mapi.h.
+	 */
 	public static abstract class OptionsCallback {
 		private StringBuilder buffer;
+		/**
+		 * Callback called for each language/level combination supported by the
+		 * server. May call {@link contribute} for options with a level STRICTLY
+		 * LOWER than the level passed as a parameter.
+		 * @param lang language advertised by the server
+		 * @param level one higher than the maximum supported option
+		 */
+		public abstract void addOptions(String lang, int level);
+		/**
+		 * Pass option=value during the handshake
+		 * @param field
+		 * @param value
+		 */
 		protected void contribute(String field, int value) {
 			if (buffer.length() > 0)
 				buffer.append(',');
 			buffer.append(field);
 			buffer.append('=');
 			buffer.append(value);
 		}
-		public abstract void addOptions(String lang, int level);
 		void setBuffer(StringBuilder buf) {
 			buffer = buf;
 		}
 	}

Mercurial > hg > monetdb-java

comparison src/main/java/org/monetdb/mcl/net/MapiSocket.java @ 834:5aa19bbed0d6 monetdbs