Mercurial > hg > monetdb-java
changeset 95:c9db0fdbfc53 embedded
Some documentation done, plus removed unnecessary instance variables.
line wrap: on
line diff
--- a/src/main/java/nl/cwi/monetdb/mcl/protocol/AbstractProtocol.java +++ b/src/main/java/nl/cwi/monetdb/mcl/protocol/AbstractProtocol.java @@ -22,7 +22,7 @@ public abstract class AbstractProtocol { public abstract void waitUntilPrompt() throws IOException; - public abstract void fetchNextResponseData() throws IOException; //UPDATE currentData!!! + public abstract void fetchNextResponseData() throws IOException; public abstract ServerResponses getCurrentServerResponseHeader();
--- a/src/main/java/nl/cwi/monetdb/mcl/protocol/ProtocolException.java +++ b/src/main/java/nl/cwi/monetdb/mcl/protocol/ProtocolException.java @@ -11,13 +11,10 @@ package nl.cwi.monetdb.mcl.protocol; import java.text.ParseException; /** - * When an ProtocolException is thrown, the MCL protocol is violated by - * the sender. In general a stream reader throws an - * ProtocolException as soon as something that is read cannot be - * understood or does not conform to the specifications (e.g. a - * missing field). The instance that throws the exception will try to - * give an error offset whenever possible. Alternatively it makes sure - * that the error message includes the offending data read. + * When an ProtocolException is thrown, the underlying protocol is violated by the sender. In general a stream reader + * throws an ProtocolException as soon as something that is read cannot be understood or does not conform to the + * specifications (e.g. a missing field). The instance that throws the exception will try to give an error offset + * whenever possible. Alternatively it makes sure that the error message includes the offending data read. */ public class ProtocolException extends ParseException {
--- a/src/main/java/nl/cwi/monetdb/mcl/protocol/ServerResponses.java +++ b/src/main/java/nl/cwi/monetdb/mcl/protocol/ServerResponses.java @@ -8,6 +8,9 @@ package nl.cwi.monetdb.mcl.protocol; +/** + * This enum represents the possible stages of a query response by the server. + */ public enum ServerResponses { /* Please don't change the order */
--- a/src/main/java/nl/cwi/monetdb/mcl/protocol/StarterHeaders.java +++ b/src/main/java/nl/cwi/monetdb/mcl/protocol/StarterHeaders.java @@ -8,6 +8,10 @@ package nl.cwi.monetdb.mcl.protocol; +/** + * This enum 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. + */ public enum StarterHeaders { /* Please don't change the order */
--- a/src/main/java/nl/cwi/monetdb/mcl/protocol/TableResultHeaders.java +++ b/src/main/java/nl/cwi/monetdb/mcl/protocol/TableResultHeaders.java @@ -8,22 +8,38 @@ package nl.cwi.monetdb.mcl.protocol; +/** + * This enum lists the result table headers returned by the server. + */ public enum TableResultHeaders { /* Please don't change the order */ + + /** The column names */ NAME(1), + /** The column lengths */ LENGTH(2), + /** The column table and schemas names in format of schema.table */ TABLE(4), + /** The SQL name of the MonetDB data type of the column */ TYPE(8), + /** This header is returned by the JDBC embedded telling that it fetches all the previous headers at once */ ALL(15), + /** When an unknown table header is returned on a MAPI connection */ UNKNOWN(0); + /** An integer value for the bitmap on the ResultSetResponse Class */ private final int valueForBitMap; TableResultHeaders(int valueForBitMap) { this.valueForBitMap = valueForBitMap; } + /** + * Returns the integer value for the bitmap. + * + * @return The integer value for the bitmap. + */ public int getValueForBitMap() { return valueForBitMap; }
--- a/src/main/java/nl/cwi/monetdb/mcl/protocol/oldmapi/OldMapiProtocol.java +++ b/src/main/java/nl/cwi/monetdb/mcl/protocol/oldmapi/OldMapiProtocol.java @@ -113,7 +113,7 @@ public class OldMapiProtocol extends Abs public DataBlockResponse getNextDatablockResponse(Map<Integer, ResultSetResponse> rsresponses) throws ProtocolException { int id = OldMapiStartOfHeaderParser.GetNextResponseDataAsInt(this); //The order cannot be switched!! - int columncount = OldMapiStartOfHeaderParser.GetNextResponseDataAsInt(this); + OldMapiStartOfHeaderParser.GetNextResponseDataAsInt(this); //column count int rowcount = OldMapiStartOfHeaderParser.GetNextResponseDataAsInt(this); int offset = OldMapiStartOfHeaderParser.GetNextResponseDataAsInt(this); @@ -121,7 +121,7 @@ public class OldMapiProtocol extends Abs if (rs == null) { return null; } - return rs.addDataBlockResponse(offset, rowcount, columncount, this); + return rs.addDataBlockResponse(offset, rowcount, this); } @Override
--- a/src/main/java/nl/cwi/monetdb/mcl/responses/AutoCommitResponse.java +++ b/src/main/java/nl/cwi/monetdb/mcl/responses/AutoCommitResponse.java @@ -9,12 +9,15 @@ package nl.cwi.monetdb.mcl.responses; /** - * The AutoCommitResponse represents a transaction message. It - * stores (a change in) the server side auto commit mode.<br /> + * The AutoCommitResponse represents a transaction message. It stores (a change in) the server side auto commit mode. + * <br /> * <tt>&4 (t|f)</tt> */ public class AutoCommitResponse extends SchemaResponse { + /** + * If the auto commit mode is set. + */ private final boolean autocommit; public AutoCommitResponse(boolean ac) { @@ -22,6 +25,11 @@ public class AutoCommitResponse extends this.autocommit = ac; } + /** + * The auto commit value + * + * @return The auto commit value + */ public boolean isAutocommit() { return autocommit; }
--- a/src/main/java/nl/cwi/monetdb/mcl/responses/DataBlockResponse.java +++ b/src/main/java/nl/cwi/monetdb/mcl/responses/DataBlockResponse.java @@ -21,21 +21,18 @@ import java.util.Arrays; import java.util.Calendar; /** - * The DataBlockResponse is tabular data belonging to a - * ResultSetResponse. Tabular data from the server typically looks - * like: + * The DataBlockResponse is tabular data belonging to a ResultSetResponse. On a MAPI connection, tabular data from the + * server typically looks like: * <pre> * [ "value", 56 ] * </pre> - * where each column is separated by ",\t" and each tuple surrounded - * by brackets ("[" and "]"). A DataBlockResponse object holds the - * raw data as read from the server, in a parsed manner, ready for - * easy retrieval. + * where each column is separated by ",\t" and each tuple surrounded by brackets ("[" and "]"). A DataBlockResponse + * object holds the raw data as read from the server, in a parsed manner, ready for easy retrieval. Meanwhile on an + * Embedded connection, the data is automatically parsed. * - * This object is not intended to be queried by multiple threads - * synchronously. It is designed to work for one thread retrieving - * rows from it. When multiple threads will retrieve rows from this - * object, it is possible for threads to get the same data. + * This object is not intended to be queried by multiple threads synchronously. It is designed to work for one thread + * retrieving rows from it. When multiple threads will retrieve rows from this object, it is possible for threads to + * get the same data. */ public class DataBlockResponse implements IIncompleteResponse { @@ -59,6 +56,8 @@ public class DataBlockResponse implement * * @param rowcount the number of rows * @param columncount the number of columns + * @param protocol the underlying protocol + * @param JdbcSQLTypes an array of the JDBC mappings of the columns */ DataBlockResponse(int rowcount, int columncount, AbstractProtocol protocol, int[] JdbcSQLTypes) { this.pos = -1; @@ -70,10 +69,9 @@ public class DataBlockResponse implement } /** - * addLine adds a String of data to this object's data array. Note that an IndexOutOfBoundsException can be thrown - * when an attempt is made to add more than the original construction size specified. + * addLines adds a batch of rows to the block. Before adding the first line, the column arrays are allocated. * - * @param protocol The connection's protocol + * @param protocol The connection's protocol to fetch data from * @throws ProtocolException If the result line is not expected */ @Override @@ -169,54 +167,131 @@ public class DataBlockResponse implement /* Methods to be called after the block construction has been completed */ + /** + * Sets the current line number on the block. + * + * @param blockLine the block line number + */ void setBlockLine(int blockLine) { this.blockLine = blockLine; } + /** + * Sets the data on the block. + * This method is called by the MonetVirtualResultSet class which should be eliminated on the future. + * + * @param data the data to set + */ public void setData(Object[] data) { /* For VirtualResultSet :( */ this.data = data; } + /** + * Gets the data on the block. + * This method is called by the MonetVirtualResultSet class which should be eliminated on the future. + * + * @return the result set data + */ public Object[] getData() { /* For VirtualResultSet :( */ return this.data; } + /** + * Checks if a value in the current row is null. + * + * @param column The column index starting from 0 + * @return If the value is null or not. + */ public boolean checkValueIsNull(int column) { return this.nullMappings[column][this.blockLine]; } + /** + * Gets the current row value as a Java Boolean. + * + * @param column The column index starting from 0 + * @return A Java Boolean if the column is a boolean, otherwise a ClassCastException is thrown + */ public boolean getBooleanValue(int column) { return ((boolean[]) this.data[column])[this.blockLine]; } + /** + * Gets the current row value as a Java Byte. + * + * @param column The column index starting from 0 + * @return A Java Byte if the column is a tinyint, otherwise a ClassCastException is thrown + */ public byte getByteValue(int column) { return ((byte[]) this.data[column])[this.blockLine]; } + /** + * Gets the current row value as a Java Short. + * + * @param column The column index starting from 0 + * @return A Java Short if the column is a smallint, otherwise a ClassCastException is thrown + */ public short getShortValue(int column) { return ((short[]) this.data[column])[this.blockLine]; } + /** + * Gets the current row value as a Java Integer. + * + * @param column The column index starting from 0 + * @return A Java Integer if the column is an integer or month_interval, otherwise a ClassCastException is thrown + */ public int getIntValue(int column) { return ((int[]) this.data[column])[this.blockLine]; } + /** + * Gets the current row value as a Java Long. + * + * @param column The column index starting from 0 + * @return A Java Long if the column is a bigint or second_interval, otherwise a ClassCastException is thrown + */ public long getLongValue(int column) { return ((long[]) this.data[column])[this.blockLine]; } + /** + * Gets the current row value as a Java Float. + * + * @param column The column index starting from 0 + * @return A Java Float if the column is a real, otherwise a ClassCastException is thrown + */ public float getFloatValue(int column) { return ((float[]) this.data[column])[this.blockLine]; } + /** + * Gets the current row value as a Java Double. + * + * @param column The column index starting from 0 + * @return A Java Double if the column is a double, otherwise a ClassCastException is thrown + */ public double getDoubleValue(int column) { return ((double[]) this.data[column])[this.blockLine]; } + /** + * Gets the current row value as a Java Object. + * + * @param column The column index starting from 0 + * @return A Java Object if the column is not a primitive type, otherwise a ClassCastException is thrown + */ public Object getObjectValue(int column) { return ((Object[]) this.data[column])[this.blockLine]; } + /** + * Gets the current row value as a Java String. + * + * @param column The column index starting from 0 + * @return The String representation of the data type + */ public String getValueAsString(int column) { switch (this.jdbcSQLTypes[column]) { case Types.BOOLEAN: @@ -235,11 +310,22 @@ public class DataBlockResponse implement return Double.toString(((double[]) this.data[column])[this.blockLine]); case Types.LONGVARBINARY: return Arrays.toString(((byte[][]) this.data[column])[this.blockLine]); - default: //CHAR, VARCHAR, LONGVARCHAR, OTHER, BLOB, CLOB and others + case Types.CHAR: + case Types.VARCHAR: + case Types.LONGVARCHAR: + case Types.OTHER: + return ((String[]) this.data[column])[this.blockLine]; + default: //BLOB, CLOB, BigDecimal, BigInteger, Time, Timestamp and Date return ((Object[]) this.data[column])[this.blockLine].toString(); } } + /** + * Gets the current row value as a Java Object. + * + * @param column The column index starting from 0 + * @return The Object representation of the data type + */ public Object getValueAsObject(int column) { switch (this.jdbcSQLTypes[column]) { case Types.BOOLEAN:
--- a/src/main/java/nl/cwi/monetdb/mcl/responses/IIncompleteResponse.java +++ b/src/main/java/nl/cwi/monetdb/mcl/responses/IIncompleteResponse.java @@ -11,7 +11,12 @@ package nl.cwi.monetdb.mcl.responses; import nl.cwi.monetdb.mcl.protocol.AbstractProtocol; import nl.cwi.monetdb.mcl.protocol.ProtocolException; +/** + * The ResultSetResponse and DatablockResponse Classes might require more than one Block response if the response is + * larger than the BlockSize. + */ public interface IIncompleteResponse extends IResponse { + /** * Returns whether this Response expects more lines to be added to it. * @@ -19,5 +24,11 @@ public interface IIncompleteResponse ext */ boolean wantsMore(); + /** + * Adds a batch of data to the Response instance. + * + * @param protocol The connection's protocol to fetch data from + * @throws ProtocolException If the result line is not expected + */ void addLines(AbstractProtocol protocol) throws ProtocolException; }
--- a/src/main/java/nl/cwi/monetdb/mcl/responses/IResponse.java +++ b/src/main/java/nl/cwi/monetdb/mcl/responses/IResponse.java @@ -9,13 +9,13 @@ package nl.cwi.monetdb.mcl.responses; /** - * A Response is a message sent by the server to indicate some - * action has taken place, and possible results of that action. + * A Response is a message sent by the server to indicate some action has taken place, and possible results of that + * action. */ public interface IResponse { + /** - * Instructs the Response implementation to close and do the - * necessary clean up procedures. + * Instructs the Response implementation to close and do the necessary clean up procedures. */ void close(); }
--- a/src/main/java/nl/cwi/monetdb/mcl/responses/ResultSetResponse.java +++ b/src/main/java/nl/cwi/monetdb/mcl/responses/ResultSetResponse.java @@ -21,9 +21,8 @@ import java.sql.SQLException; import java.sql.Types; /** - * The ResultSetResponse represents a tabular result sent by the - * server. This is typically an SQL table. The MAPI headers of the - * Response look like: + * The ResultSetResponse represents a tabular result sent by the server. This is typically an SQL table. The MAPI + * headers of the Response look like: * <pre> * &1 1 28 2 10 * # name, value # name @@ -31,13 +30,15 @@ import java.sql.Types; * </pre> * there the first line consists out of<br /> * <tt>&"qt" "id" "tc" "cc" "rc"</tt>. + * Meanwhile on an Embedded connection the data is fetched with no parsing. */ public class ResultSetResponse implements IIncompleteResponse { + /** + * The expected final value after the table headers are set. + */ private static final byte IS_SET_FINAL_VALUE = 15; - /** The number of columns in this result */ - private final int columncount; /** The number of rows in the current block */ private final int rowcount; /** The total number of rows this result set has */ @@ -78,12 +79,13 @@ public class ResultSetResponse implement /** * Sole constructor, which requires a MonetConnection parent to be given. * + * @param con The connection of this ResultSet + * @param parent the parent that created this Response and will supply new result blocks when necessary * @param id the ID of the result set + * @param seq the query sequence number + * @param rowcount the number of rows in the current block * @param tuplecount the total number of tuples in the result set * @param columncount the number of columns in the result set - * @param rowcount the number of rows in the current block - * @param parent the parent that created this Response and will supply new result blocks when necessary - * @param seq the query sequence number */ public ResultSetResponse(MonetConnection con, MonetConnection.ResponseList parent, int id, int seq, int rowcount, int tuplecount, int columncount) { @@ -113,13 +115,12 @@ public class ResultSetResponse implement int maxrows = parent.getMaxrows(); this.tuplecount = (maxrows != 0 && tuplecount > maxrows) ? maxrows : tuplecount; - this.columncount = columncount; - this.name = new String[this.columncount]; - this.type = new String[this.columncount]; - this.tableNames = new String[this.columncount]; - this.columnLengths = new int[this.columncount]; - this.JdbcSQLTypes = new int[this.columncount]; + this.name = new String[columncount]; + this.type = new String[columncount]; + this.tableNames = new String[columncount]; + this.columnLengths = new int[columncount]; + this.JdbcSQLTypes = new int[columncount]; this.resultBlocks = new DataBlockResponse[(tuplecount / cacheSize) + 1]; this.resultBlocks[0] = new DataBlockResponse(rowcount, columncount, con.getProtocol(), this.JdbcSQLTypes); @@ -156,26 +157,48 @@ public class ResultSetResponse implement * Adds the given DataBlockResponse to this ResultSetResponse at the given block position. * * @param offset the offset number of rows for this block + * @param rowcount the number of rows for this block + * @param proto The connection's protocol */ - public DataBlockResponse addDataBlockResponse(int offset, int rowcount, int columncount, AbstractProtocol proto) { + public DataBlockResponse addDataBlockResponse(int offset, int rowcount, AbstractProtocol proto) { int block = (offset - blockOffset) / cacheSize; - DataBlockResponse res = new DataBlockResponse(rowcount, columncount, proto, JdbcSQLTypes); + DataBlockResponse res = new DataBlockResponse(rowcount, this.name.length, proto, JdbcSQLTypes); resultBlocks[block] = res; return res; } + /** + * Returns this ResultSet id + * + * @return The resultSet id + */ public int getId() { return id; } + /** + * Returns the number of columns on this ResultSet + * + * @return The number of columns on this ResultSet + */ public int getColumncount() { - return columncount; + return name.length; } + /** + * Returns the number of rows on this ResultSet + * + * @return The number of rows on this ResultSet + */ public int getTuplecount() { return tuplecount; } + /** + * Returns the number of rows on the current block + * + * @return The number of rows on the current block + */ public int getRowcount() { return rowcount; } @@ -183,7 +206,7 @@ public class ResultSetResponse implement /** * Returns the names of the columns * - * @return the names of the columns + * @return The names of the columns */ public String[] getNames() { return name; @@ -192,7 +215,7 @@ public class ResultSetResponse implement /** * Returns the types of the columns * - * @return the types of the columns + * @return The types of the columns */ public String[] getTypes() { return type; @@ -201,7 +224,7 @@ public class ResultSetResponse implement /** * Returns the JDBC types of the columns * - * @return the JDBC types of the columns + * @return The JDBC types of the columns */ public int[] getJdbcSQLTypes() { return JdbcSQLTypes; @@ -210,7 +233,7 @@ public class ResultSetResponse implement /** * Returns the tables of the columns * - * @return the tables of the columns + * @return The tables of the columns */ public String[] getTableNames() { return tableNames; @@ -219,7 +242,7 @@ public class ResultSetResponse implement /** * Returns the lengths of the columns * - * @return the lengths of the columns + * @return The lengths of the columns */ public int[] getColumnLengths() { return columnLengths; @@ -228,7 +251,7 @@ public class ResultSetResponse implement /** * Returns the cache size used within this Response * - * @return the cache size + * @return The cache size */ public int getCacheSize() { return cacheSize; @@ -237,7 +260,7 @@ public class ResultSetResponse implement /** * Returns the current block offset * - * @return the current block offset + * @return The current block offset */ public int getBlockOffset() { return blockOffset; @@ -246,7 +269,7 @@ public class ResultSetResponse implement /** * Returns the ResultSet type, FORWARD_ONLY or not. * - * @return the ResultSet type + * @return The ResultSet type */ public int getRSType() { return parent.getRstype(); @@ -255,15 +278,15 @@ public class ResultSetResponse implement /** * Returns the concurrency of the ResultSet. * - * @return the ResultSet concurrency + * @return The ResultSet concurrency */ public int getRSConcur() { return parent.getRsconcur(); } /** - * Parses the given string and changes the value of the matching header appropriately, or passes it on to the - * underlying DataResponse. + * Gets the next table headers from the underlying protocol, or gets the next rows on to the underlying + * DataResponse if the headers are already retrieved. * * @param protocol the connection's protocol * @throws ProtocolException if has a wrong header @@ -275,10 +298,11 @@ public class ResultSetResponse implement } else if (protocol.getCurrentServerResponseHeader() != ServerResponses.HEADER) { throw new ProtocolException("header expected, got: " + protocol.getRemainingStringLine(0)); } else { - TableResultHeaders next = con.getProtocol().getNextTableHeader(this.name, this.columnLengths, this.type, this.tableNames); + TableResultHeaders next = con.getProtocol().getNextTableHeader(this.name, this.columnLengths, this.type, + this.tableNames); this.isSet |= next.getValueForBitMap(); if(this.isSet >= IS_SET_FINAL_VALUE) { - this.populateJdbcSQLTypesArray(); //VERY IMPORTANT + this.populateJdbcSQLTypesArray(); //VERY IMPORTANT to populate the JDBC types array } } }
--- a/src/main/java/nl/cwi/monetdb/mcl/responses/SchemaResponse.java +++ b/src/main/java/nl/cwi/monetdb/mcl/responses/SchemaResponse.java @@ -11,12 +11,10 @@ package nl.cwi.monetdb.mcl.responses; import java.sql.Statement; /** - * The SchemaResponse represents an schema modification response. - * It is issued on statements like CREATE, DROP or ALTER TABLE. - * This response keeps a field that represents the success state, as - * defined by JDBC, which is currently in MonetDB's case always - * SUCCESS_NO_INFO. Note that this state is not sent by the - * server.<br /> + * The SchemaResponse represents an schema modification response. It is issued on statements like CREATE, DROP or + * ALTER TABLE. This response keeps a field that represents the success state, as defined by JDBC, which is currently in + * MonetDB's case always SUCCESS_NO_INFO. Note that this state is not sent by the server. + * <br /> * <tt>&3</tt> */ public class SchemaResponse implements IResponse {
--- a/src/main/java/nl/cwi/monetdb/mcl/responses/UpdateResponse.java +++ b/src/main/java/nl/cwi/monetdb/mcl/responses/UpdateResponse.java @@ -9,17 +9,22 @@ package nl.cwi.monetdb.mcl.responses; /** - * The UpdateResponse represents an update statement response. It - * is issued on an UPDATE, INSERT or DELETE SQL statement. This - * response keeps a count field that represents the affected rows - * and a field that contains the last inserted auto-generated ID, or - * -1 if not applicable.<br /> + * The UpdateResponse represents an update statement response. It is issued on an UPDATE, INSERT or DELETE SQL + * statement. This response keeps a count field that represents the affected rows and a field that contains the last + * inserted auto-generated ID, or -1 if not applicable. + * <br /> * <tt>&2 0 -1</tt> */ public class UpdateResponse implements IResponse { + /** + * The id of the response before this one. + */ private final int lastid; + /** + * The number of rows affected by the update statement. + */ private final int count; public UpdateResponse(int lastid, int count) { @@ -28,10 +33,20 @@ public class UpdateResponse implements I this.count = count; } + /** + * The id of the response before this one. + * + * @return The id of the response before this one + */ public int getLastid() { return lastid; } + /** + * The number of rows affected by the update statement. + * + * @return The number of rows affected by the update statement + */ public int getCount() { return count; }