Mercurial > hg > monetdb-java
changeset 98:c0ce1ea5075f embedded
Some documentation added.
line wrap: on
line diff
--- a/src/main/java/nl/cwi/monetdb/jdbc/MonetConnection.java +++ b/src/main/java/nl/cwi/monetdb/jdbc/MonetConnection.java @@ -1252,7 +1252,7 @@ public abstract class MonetConnection ex try { protocol.writeNextQuery(language.getQueryTemplateIndex(0), command, language.getQueryTemplateIndex(1)); protocol.waitUntilPrompt(); - int csrh = protocol.getCurrentServerResponseHeader(); + int csrh = protocol.getCurrentServerResponse(); if (csrh == ServerResponses.ERROR) { String error = protocol.getRemainingStringLine(0); throw new SQLException(error.substring(6), error.substring(0, 5)); @@ -1473,7 +1473,7 @@ public abstract class MonetConnection ex // go for new results protocol.fetchNextResponseData(); - int nextResponse = protocol.getCurrentServerResponseHeader(); + int nextResponse = protocol.getCurrentServerResponse(); IResponse res = null; while (nextResponse != ServerResponses.PROMPT) { // each response should start with a start of header (or error) @@ -1533,14 +1533,14 @@ public abstract class MonetConnection ex + e.getErrorOffset(); // flush all the rest protocol.waitUntilPrompt(); - nextResponse = protocol.getCurrentServerResponseHeader(); + nextResponse = protocol.getCurrentServerResponse(); break; } // immediately handle errors after parsing the header (res may be null) if (error != null) { protocol.waitUntilPrompt(); - nextResponse = protocol.getCurrentServerResponseHeader(); + nextResponse = protocol.getCurrentServerResponse(); break; } @@ -1555,7 +1555,7 @@ public abstract class MonetConnection ex // right, some protocol violation, skip the rest of the result error = "M0M10!" + ex.getMessage(); protocol.waitUntilPrompt(); - nextResponse = protocol.getCurrentServerResponseHeader(); + nextResponse = protocol.getCurrentServerResponse(); break; } } @@ -1572,20 +1572,20 @@ public abstract class MonetConnection ex } // read the next line (can be prompt, new result, error, etc.) before we start the loop over protocol.fetchNextResponseData(); - nextResponse = protocol.getCurrentServerResponseHeader(); + nextResponse = protocol.getCurrentServerResponse(); break; case ServerResponses.INFO: addWarning(protocol.getRemainingStringLine(0), "01000"); // read the next line (can be prompt, new result, error, etc.) before we start the loop over protocol.fetchNextResponseData(); - nextResponse = protocol.getCurrentServerResponseHeader(); + nextResponse = protocol.getCurrentServerResponse(); break; case ServerResponses.ERROR: // read everything till the prompt (should be error) we don't know if we ignore some // garbage here... but the log should reveal that error = protocol.getRemainingStringLine(0); protocol.waitUntilPrompt(); - nextResponse = protocol.getCurrentServerResponseHeader(); + nextResponse = protocol.getCurrentServerResponse(); break; default: throw new SQLException("Protocol violation, unexpected line!", "M0M10");
--- a/src/main/java/nl/cwi/monetdb/jdbc/MonetResultSet.java +++ b/src/main/java/nl/cwi/monetdb/jdbc/MonetResultSet.java @@ -1653,8 +1653,7 @@ public class MonetResultSet extends Mone // ignore exception and just return the val String object return val; } - } else - if ("uuid".equals(MonetDBType)) { + } else if ("uuid".equals(MonetDBType)) { try { return UUID.fromString(val); } catch (IllegalArgumentException exc) { @@ -2615,8 +2614,7 @@ public class MonetResultSet extends Mone if (header != null && header.isClosed()) throw new SQLException("Cannot call on closed ResultSet", "M1M20"); - // if there are no warnings, this will be null, which fits with the - // specification. + // if there are no warnings, this will be null, which fits with the specification. return warnings; }
--- a/src/main/java/nl/cwi/monetdb/mcl/connection/ControlCommands.java +++ b/src/main/java/nl/cwi/monetdb/mcl/connection/ControlCommands.java @@ -8,11 +8,14 @@ package nl.cwi.monetdb.mcl.connection; +/** + * The listening of the MonetDB's control commands sent by the client during a JDBC connection. + */ public final class ControlCommands { /** Send autocommit statement */ public static final int AUTO_COMMIT = 1; - /** Set reply size for the server */ + /** Set reply size for the server (for the maxrows specification) */ public static final int REPLY_SIZE = 2; /** Release a prepared statement data */ public static final int RELEASE = 3;
--- a/src/main/java/nl/cwi/monetdb/mcl/connection/IMonetDBLanguage.java +++ b/src/main/java/nl/cwi/monetdb/mcl/connection/IMonetDBLanguage.java @@ -8,15 +8,46 @@ package nl.cwi.monetdb.mcl.connection; +/** + * An interface which represents the delimiters for user queries depending on the language (SQL and MAL) and connection + * (Socket and Embedded). + */ public interface IMonetDBLanguage { + /** + * Gets the String representation of a query delimiter represented through the index parameter. + * + * @param index The delimiter index starting from 0 + * @return The String representation of the delimiter + */ String getQueryTemplateIndex(int index); + /** + * Gets the String representation of a command delimiter represented through the index parameter. + * + * @param index The delimiter index starting from 0 + * @return The String representation of the delimiter + */ String getCommandTemplateIndex(int index); + /** + * Gets all query delimiters. + * + * @return All query delimiters + */ String[] getQueryTemplates(); + /** + * Gets all command delimiters. + * + * @return All command delimiters + */ String[] getCommandTemplates(); + /** + * Gets the String representation of the language currently used. + * + * @return The String representation of the language currently used. + */ String getRepresentation(); }
--- a/src/main/java/nl/cwi/monetdb/mcl/connection/MCLException.java +++ b/src/main/java/nl/cwi/monetdb/mcl/connection/MCLException.java @@ -9,8 +9,8 @@ package nl.cwi.monetdb.mcl.connection; /** - * A general purpose Exception class for MCL related problems. This - * class should be used if no more precise Exception class exists. + * A general purpose Exception class for MCL related problems. This class should be used if no more precise Exception + * class exists. */ public class MCLException extends Exception {
--- a/src/main/java/nl/cwi/monetdb/mcl/connection/SenderThread.java +++ b/src/main/java/nl/cwi/monetdb/mcl/connection/SenderThread.java @@ -17,15 +17,11 @@ import java.util.concurrent.locks.Lock; import java.util.concurrent.locks.ReentrantLock; /** - * A thread to send a query to the server. When sending large - * amounts of data to a server, the output buffer of the underlying - * communication socket may overflow. In such case the sending - * process blocks. In order to prevent deadlock, it might be - * desirable that the driver as a whole does not block. This thread - * facilitates the prevention of such 'full block', because this - * separate thread only will block.<br /> - * This thread is designed for reuse, as thread creation costs are - * high. + * A thread to send a query to the server. When sending large amounts of data to a server, the output buffer of the + * underlying communication socket may overflow. In such case the sending process blocks. In order to prevent deadlock, + * it might be desirable that the driver as a whole does not block. This thread facilitates the prevention of such + * 'full block', because this separate thread only will block.<br /> This thread is designed for reuse, as thread + * creation costs are high. */ public class SenderThread extends Thread {
--- a/src/main/java/nl/cwi/monetdb/mcl/connection/mapi/MapiConnection.java +++ b/src/main/java/nl/cwi/monetdb/mcl/connection/mapi/MapiConnection.java @@ -78,10 +78,8 @@ public class MapiConnection extends Mone } /** - * Sets whether MCL redirections should be followed or not. If set - * to false, an MCLException will be thrown when a redirect is - * encountered during connect. The default behaviour is to - * automatically follow redirects. + * Sets whether MCL redirections should be followed or not. If set to false, an MCLException will be thrown when a + * redirect is encountered during connect. The default behaviour is to automatically follow redirects. * * @param r whether to follow redirects (true) or not (false) */ @@ -90,12 +88,9 @@ public class MapiConnection extends Mone } /** - * Sets the number of redirects that are followed when - * followRedirects is true. In order to avoid going into an endless - * loop due to some evil server, or another error, a maximum number - * of redirects that may be followed can be set here. Note that to - * disable the following of redirects you should use - * setFollowRedirects. + * Sets the number of redirects that are followed when followRedirects is true. In order to avoid going into an + * endless loop due to some evil server, or another error, a maximum number of redirects that may be followed can be + * set here. Note that to disable the following of redirects you should use setFollowRedirects. * * @see #setFollowRedirects(boolean r) * @param t the number of redirects before an exception is thrown @@ -105,9 +100,8 @@ public class MapiConnection extends Mone } /** - * Returns the mapi protocol version used by this socket. The - * protocol version depends on the server being used. Users of the - * MapiSocket should check this version to act appropriately. + * Returns the mapi protocol version used by this socket. The protocol version depends on the server being used. + * Users of the MapiSocket should check this version to act appropriately. * * @return the mapi protocol version */ @@ -219,7 +213,7 @@ public class MapiConnection extends Mone try { protocol.writeNextQuery(language.getCommandTemplateIndex(0), command, language.getCommandTemplateIndex(1)); protocol.waitUntilPrompt(); - int csrh = protocol.getCurrentServerResponseHeader(); + int csrh = protocol.getCurrentServerResponse(); if (csrh == ServerResponses.ERROR) { String error = protocol.getRemainingStringLine(0); throw new SQLException(error.substring(6), error.substring(0, 5)); @@ -272,7 +266,7 @@ public class MapiConnection extends Mone do { this.protocol.fetchNextResponseData(); - next = this.protocol.getCurrentServerResponseHeader(); + next = this.protocol.getCurrentServerResponse(); switch (next) { case ServerResponses.ERROR: err += "\n" + this.protocol.getRemainingStringLine(7);
--- a/src/main/java/nl/cwi/monetdb/mcl/protocol/AbstractProtocol.java +++ b/src/main/java/nl/cwi/monetdb/mcl/protocol/AbstractProtocol.java @@ -18,36 +18,132 @@ import nl.cwi.monetdb.mcl.responses.Resu import java.io.IOException; import java.util.Map; +/** + * A generic protocol for the underlying connection, either as a socket or an embedded connection. All the server + * responses are retrieved from this class. At the same time, the user queries are submitted through this class. + * + * @author Pedro Ferreira + */ public abstract class AbstractProtocol { + /** + * Waits until the server sends the PROMPT message, meaning that the next response is ready for retrieval. + * + * @throws IOException If an error in the underlying connection happened. + */ public abstract void waitUntilPrompt() throws IOException; + /** + * Fetch the server's next response data. + * + * @throws IOException If an error in the underlying connection happened. + */ public abstract void fetchNextResponseData() throws IOException; - public abstract int getCurrentServerResponseHeader(); + /** + * Get the current server response, obtained through the fetchNextResponseData method. + * + * @return The integer representation of the server response + */ + public abstract int getCurrentServerResponse(); + /** + * Get the next starter header of a server response. + * + * @return The integer representation of the starter header + */ public abstract int getNextStarterHeader(); + /** + * Get the next ResultSet response from the server, belonging to a ResponseList. + * + * @param con The current MonetDB's JDBC connection + * @param list The Response List this result set will belong to + * @param seqnr The sequence number of this result set on the Response List + * @return The ResultSet instance + * @throws ProtocolException If an error in the underlying connection happened. + */ public abstract ResultSetResponse getNextResultSetResponse(MonetConnection con, MonetConnection.ResponseList list, int seqnr) throws ProtocolException; + /** + * Get the next UpdateResponse response from the server. + * + * @return The UpdateResponse instance + * @throws ProtocolException If an error in the underlying connection happened. + */ public abstract UpdateResponse getNextUpdateResponse() throws ProtocolException; + /** + * Get the next SchemaResponse response from the server. + * + * @return The SchemaResponse instance + */ public SchemaResponse getNextSchemaResponse() { return new SchemaResponse(); } + /** + * Get the next AutoCommitResponse response from the server. + * + * @return The AutoCommitResponse instance + * @throws ProtocolException If an error in the underlying connection happened. + */ public abstract AutoCommitResponse getNextAutoCommitResponse() throws ProtocolException; + /** + * Get the next DataBlockResponse response from the server, belonging to a ResultSetResponse + * + * @param rsresponses A map of ResultSetResponse, in which this Block will belong to one of them, by checking its id + * against the keys of the Map. + * @return The DataBlockResponse instance + * @throws ProtocolException If an error in the underlying connection happened. + */ public abstract DataBlockResponse getNextDatablockResponse(Map<Integer, ResultSetResponse> rsresponses) throws ProtocolException; + /** + * Get the next Table Header for a ResultSetResponse. More than one of the parameter arrays can be filled at once. + * + * @param columnNames The column names array + * @param columnLengths The column lengths array + * @param types The columns SQL names array + * @param tableNames The columns schemas and names in format schema.name + * @return A TableResultHeaders integer representation, representing which of the fields was filled + * @throws ProtocolException If an error in the underlying connection happened. + */ public abstract int getNextTableHeader(String[] columnNames, int[] columnLengths, String[] types, String[] tableNames) throws ProtocolException; + /** + * Retrieves the next values in a DataBlockResponse from the underlying connection, starting at a specific line + * number. + * + * @param firstLineNumber The first line number in the response to retrieve + * @param typesMap The JDBC types mapping array for every column in the ResultSetResponse of the DataBlock + * @param values An array of columns to fill the values + * @return The number of lines parsed from the underlying connection + * @throws ProtocolException If an error in the underlying connection happened. + */ public abstract int parseTupleLines(int firstLineNumber, int[] typesMap, Object[] values) throws ProtocolException; + /** + * Gets the remaining response line from the underlying connection as a Java String. This method is mostly used to + * retrieve error Strings, when they are detected while parsing a response line. + * + * @param startIndex The first index in the response line to retrieve the String + * @return The String representation of the line starting at the provided index + */ public abstract String getRemainingStringLine(int startIndex); + /** + * Writes a user query to the server, while providing the respective prefixes and suffixes depending on the current + * language and connection used. + * + * @param prefix The prefix to append at the beginning of the query string + * @param query The user query to submit at the server + * @param suffix The suffix to append at the end of the query string + * @throws IOException If an error in the underlying connection happened. + */ public abstract void writeNextQuery(String prefix, String query, String suffix) throws IOException; }
--- a/src/main/java/nl/cwi/monetdb/mcl/protocol/StarterHeaders.java +++ b/src/main/java/nl/cwi/monetdb/mcl/protocol/StarterHeaders.java @@ -9,8 +9,8 @@ package nl.cwi.monetdb.mcl.protocol; /** - * This class lists the possible responses of a query by the server. Notice that Q_PARSE is not used by neither a MAPI or - * embedded connection, so it's here for completeness. + * This class lists the possible responses of a query by the server. Notice that Q_PARSE is not used by neither a MAPI + * or an embedded connection, so it's here for completeness. */ public final class StarterHeaders {
--- a/src/main/java/nl/cwi/monetdb/mcl/protocol/newmapi/NewMapiProtocol.java +++ b/src/main/java/nl/cwi/monetdb/mcl/protocol/newmapi/NewMapiProtocol.java @@ -21,7 +21,7 @@ import java.util.Map; public class NewMapiProtocol extends AbstractProtocol { @Override - public int getCurrentServerResponseHeader() { + public int getCurrentServerResponse() { return 0; }
--- a/src/main/java/nl/cwi/monetdb/mcl/protocol/oldmapi/OldMapiProtocol.java +++ b/src/main/java/nl/cwi/monetdb/mcl/protocol/oldmapi/OldMapiProtocol.java @@ -43,7 +43,7 @@ public class OldMapiProtocol extends Abs } @Override - public int getCurrentServerResponseHeader() { + public int getCurrentServerResponse() { return currentServerResponseHeader; }
--- a/src/main/java/nl/cwi/monetdb/mcl/responses/DataBlockResponse.java +++ b/src/main/java/nl/cwi/monetdb/mcl/responses/DataBlockResponse.java @@ -73,7 +73,7 @@ public class DataBlockResponse implement */ @Override public void addLines(AbstractProtocol protocol) throws ProtocolException { - int csrh = protocol.getCurrentServerResponseHeader(); + int csrh = protocol.getCurrentServerResponse(); if (csrh != ServerResponses.RESULT) { throw new ProtocolException("protocol violation: unexpected line in data block: " + protocol.getRemainingStringLine(0));
--- a/src/main/java/nl/cwi/monetdb/mcl/responses/ResultSetResponse.java +++ b/src/main/java/nl/cwi/monetdb/mcl/responses/ResultSetResponse.java @@ -14,7 +14,6 @@ import nl.cwi.monetdb.mcl.connection.Con import nl.cwi.monetdb.mcl.protocol.AbstractProtocol; import nl.cwi.monetdb.mcl.protocol.ProtocolException; import nl.cwi.monetdb.mcl.protocol.ServerResponses; -import nl.cwi.monetdb.mcl.protocol.TableResultHeaders; import java.sql.ResultSet; import java.sql.SQLException; @@ -296,7 +295,7 @@ public class ResultSetResponse implement if (this.isSet >= IS_SET_FINAL_VALUE) { this.resultBlocks[0].addLines(protocol); } else { - int csrh = protocol.getCurrentServerResponseHeader(); + int csrh = protocol.getCurrentServerResponse(); if (csrh != ServerResponses.HEADER) { throw new ProtocolException("header expected, got: " + protocol.getRemainingStringLine(0)); } else {
--- a/src/main/java/nl/cwi/monetdb/merovingian/Control.java +++ b/src/main/java/nl/cwi/monetdb/merovingian/Control.java @@ -179,7 +179,7 @@ public class Control { protocol.writeNextQuery(null,database + " " + command, "\n"); ArrayList<String> l = new ArrayList<>(); protocol.waitUntilPrompt(); - int next = protocol.getCurrentServerResponseHeader(); + int next = protocol.getCurrentServerResponse(); String line = protocol.getRemainingStringLine(0); if (next == ServerResponses.ERROR) @@ -189,7 +189,7 @@ public class Control { if (!line.substring(1).equals(RESPONSE_OK)) throw new MerovingianException(line.substring(1)); - next = protocol.getCurrentServerResponseHeader(); + next = protocol.getCurrentServerResponse(); line = protocol.getRemainingStringLine(0); while (next != ServerResponses.PROMPT) { if (next != ServerResponses.RESULT) @@ -197,7 +197,7 @@ public class Control { l.add(line.substring(1)); - next = protocol.getCurrentServerResponseHeader(); + next = protocol.getCurrentServerResponse(); line = protocol.getRemainingStringLine(0); }
--- a/src/main/java/nl/cwi/monetdb/util/SQLRestore.java +++ b/src/main/java/nl/cwi/monetdb/util/SQLRestore.java @@ -57,7 +57,7 @@ public class SQLRestore { try { while (true) { protocol.waitUntilPrompt(); - next = protocol.getCurrentServerResponseHeader(); + next = protocol.getCurrentServerResponse(); line = protocol.getRemainingStringLine(0); if (line == null) break;