Skip to content

Commit

Permalink
docs: improve javadocs in PgResultSetMetaData (#792)
Browse files Browse the repository at this point in the history
  • Loading branch information
@davecramer @vlsi
davecramer authored and vlsi committed Jun 30, 2018
1 parent 7a0b7d6 commit 825c092
Showing 1 changed file with 42 additions and 161 deletions.
203 changes: 42 additions & 161 deletions pgjdbc/src/main/java/org/postgresql/jdbc/PgResultSetMetaData.java
View file
Expand Up @@ -28,7 +28,7 @@ public class PgResultSetMetaData implements ResultSetMetaData, PGResultSetMetaDa


private boolean fieldInfoFetched; private boolean fieldInfoFetched;


/* /**
* Initialise for a result with a tuple set and a field descriptor set * Initialise for a result with a tuple set and a field descriptor set
* *
* @param fields the array of field descriptors * @param fields the array of field descriptors
Expand All @@ -39,25 +39,17 @@ public PgResultSetMetaData(BaseConnection connection, Field[] fields) {
fieldInfoFetched = false; fieldInfoFetched = false;
} }


/*
* Whats the number of columns in the ResultSet?
*
* @return the number
*
* @exception SQLException if a database access error occurs
*/
public int getColumnCount() throws SQLException { public int getColumnCount() throws SQLException {
return fields.length; return fields.length;
} }


/* /**
* Is the column automatically numbered (and thus read-only) I believe that PostgreSQL does not * {@inheritDoc}
* support this feature.
* *
* @param column the first column is 1, the second is 2... * <p>It is believed that PostgreSQL does not support this feature.
* *
* @param column the first column is 1, the second is 2...
* @return true if so * @return true if so
*
* @exception SQLException if a database access error occurs * @exception SQLException if a database access error occurs
*/ */
public boolean isAutoIncrement(int column) throws SQLException { public boolean isAutoIncrement(int column) throws SQLException {
Expand All @@ -67,45 +59,45 @@ public boolean isAutoIncrement(int column) throws SQLException {
return metadata != null && metadata.autoIncrement; return metadata != null && metadata.autoIncrement;
} }


/* /**
* Does a column's case matter? ASSUMPTION: Any field that is not obviously case insensitive is * {@inheritDoc}
*
* <p>Does a column's case matter? ASSUMPTION: Any field that is not obviously case insensitive is
* assumed to be case sensitive * assumed to be case sensitive
* *
* @param column the first column is 1, the second is 2... * @param column the first column is 1, the second is 2...
*
* @return true if so * @return true if so
*
* @exception SQLException if a database access error occurs * @exception SQLException if a database access error occurs
*/ */
public boolean isCaseSensitive(int column) throws SQLException { public boolean isCaseSensitive(int column) throws SQLException {
Field field = getField(column); Field field = getField(column);
return connection.getTypeInfo().isCaseSensitive(field.getOID()); return connection.getTypeInfo().isCaseSensitive(field.getOID());
} }


/* /**
* Can the column be used in a WHERE clause? Basically for this, I split the functions into two * {@inheritDoc}
*
* <p>Can the column be used in a WHERE clause? Basically for this, I split the functions into two
* types: recognised types (which are always useable), and OTHER types (which may or may not be * types: recognised types (which are always useable), and OTHER types (which may or may not be
* useable). The OTHER types, for now, I will assume they are useable. We should really query the * useable). The OTHER types, for now, I will assume they are useable. We should really query the
* catalog to see if they are useable. * catalog to see if they are useable.
* *
* @param column the first column is 1, the second is 2... * @param column the first column is 1, the second is 2...
*
* @return true if they can be used in a WHERE clause * @return true if they can be used in a WHERE clause
*
* @exception SQLException if a database access error occurs * @exception SQLException if a database access error occurs
*/ */
public boolean isSearchable(int column) throws SQLException { public boolean isSearchable(int column) throws SQLException {
return true; return true;
} }


/* /**
* Is the column a cash value? 6.1 introduced the cash/money type, which haven't been incorporated * {@inheritDoc}
*
* <p>Is the column a cash value? 6.1 introduced the cash/money type, which haven't been incorporated
* as of 970414, so I just check the type name for both 'cash' and 'money' * as of 970414, so I just check the type name for both 'cash' and 'money'
* *
* @param column the first column is 1, the second is 2... * @param column the first column is 1, the second is 2...
*
* @return true if its a cash column * @return true if its a cash column
*
* @exception SQLException if a database access error occurs * @exception SQLException if a database access error occurs
*/ */
public boolean isCurrency(int column) throws SQLException { public boolean isCurrency(int column) throws SQLException {
Expand All @@ -114,75 +106,42 @@ public boolean isCurrency(int column) throws SQLException {
return type_name.equals("cash") || type_name.equals("money"); return type_name.equals("cash") || type_name.equals("money");
} }


/*
* Indicates the nullability of values in the designated column.
*
* @param column the first column is 1, the second is 2...
*
* @return one of the columnNullable values
*
* @exception SQLException if a database access error occurs
*/
public int isNullable(int column) throws SQLException { public int isNullable(int column) throws SQLException {
fetchFieldMetaData(); fetchFieldMetaData();
Field field = getField(column); Field field = getField(column);
return field.getMetadata().nullable; return field.getMetadata().nullable;
} }


/* /**
* Is the column a signed number? In PostgreSQL, all numbers are signed, so this is trivial. * {@inheritDoc}
*
* <p>Is the column a signed number? In PostgreSQL, all numbers are signed, so this is trivial.
* However, strings are not signed (duh!) * However, strings are not signed (duh!)
* *
* @param column the first column is 1, the second is 2... * @param column the first column is 1, the second is 2...
*
* @return true if so * @return true if so
*
* @exception SQLException if a database access error occurs * @exception SQLException if a database access error occurs
*/ */
public boolean isSigned(int column) throws SQLException { public boolean isSigned(int column) throws SQLException {
Field field = getField(column); Field field = getField(column);
return connection.getTypeInfo().isSigned(field.getOID()); return connection.getTypeInfo().isSigned(field.getOID());
} }


/*
* What is the column's normal maximum width in characters?
*
* @param column the first column is 1, the second is 2, etc.
*
* @return the maximum width
*
* @exception SQLException if a database access error occurs
*/
public int getColumnDisplaySize(int column) throws SQLException { public int getColumnDisplaySize(int column) throws SQLException {
Field field = getField(column); Field field = getField(column);
return connection.getTypeInfo().getDisplaySize(field.getOID(), field.getMod()); return connection.getTypeInfo().getDisplaySize(field.getOID(), field.getMod());
} }


/*
* @param column the first column is 1, the second is 2, etc.
*
* @return the column label
*
* @exception SQLException if a database access error occurs
*/
public String getColumnLabel(int column) throws SQLException { public String getColumnLabel(int column) throws SQLException {
Field field = getField(column); Field field = getField(column);
return field.getColumnLabel(); return field.getColumnLabel();
} }


/*
* What's a column's name?
*
* @param column the first column is 1, the second is 2, etc.
*
* @return the column name
*
* @exception SQLException if a database access error occurs
*/
public String getColumnName(int column) throws SQLException { public String getColumnName(int column) throws SQLException {
return getColumnLabel(column); return getColumnLabel(column);
} }



public String getBaseColumnName(int column) throws SQLException { public String getBaseColumnName(int column) throws SQLException {
Field field = getField(column); Field field = getField(column);
if (field.getTableOid() == 0) { if (field.getTableOid() == 0) {
Expand All @@ -192,13 +151,6 @@ public String getBaseColumnName(int column) throws SQLException {
return field.getMetadata().columnName; return field.getMetadata().columnName;
} }


/*
* @param column the first column is 1, the second is 2...
*
* @return the Schema Name
*
* @exception SQLException if a database access error occurs
*/
public String getSchemaName(int column) throws SQLException { public String getSchemaName(int column) throws SQLException {
return ""; return "";
} }
Expand Down Expand Up @@ -316,43 +268,16 @@ public String getBaseSchemaName(int column) throws SQLException {
return field.getMetadata().schemaName; return field.getMetadata().schemaName;
} }


/*
* What is a column's number of decimal digits.
*
* @param column the first column is 1, the second is 2...
*
* @return the precision
*
* @exception SQLException if a database access error occurs
*/
public int getPrecision(int column) throws SQLException { public int getPrecision(int column) throws SQLException {
Field field = getField(column); Field field = getField(column);
return connection.getTypeInfo().getPrecision(field.getOID(), field.getMod()); return connection.getTypeInfo().getPrecision(field.getOID(), field.getMod());
} }


/*
* What is a column's number of digits to the right of the decimal point?
*
* @param column the first column is 1, the second is 2...
*
* @return the scale
*
* @exception SQLException if a database access error occurs
*/
public int getScale(int column) throws SQLException { public int getScale(int column) throws SQLException {
Field field = getField(column); Field field = getField(column);
return connection.getTypeInfo().getScale(field.getOID(), field.getMod()); return connection.getTypeInfo().getScale(field.getOID(), field.getMod());
} }


/*
* @param column the first column is 1, the second is 2...
*
* @return column name, or "" if not applicable
*
* @exception SQLException if a database access error occurs
*
* @see #getBaseTableName
*/
public String getTableName(int column) throws SQLException { public String getTableName(int column) throws SQLException {
return getBaseTableName(column); return getBaseTableName(column);
} }
Expand All @@ -363,59 +288,29 @@ public String getBaseTableName(int column) throws SQLException {
return field.getMetadata().tableName; return field.getMetadata().tableName;
} }


/* /**
* What's a column's table's catalog name? As with getSchemaName(), we can say that if * {@inheritDoc}
*
* <p>As with getSchemaName(), we can say that if
* getTableName() returns n/a, then we can too - otherwise, we need to work on it. * getTableName() returns n/a, then we can too - otherwise, we need to work on it.
* *
* @param column the first column is 1, the second is 2... * @param column the first column is 1, the second is 2...
*
* @return catalog name, or "" if not applicable * @return catalog name, or "" if not applicable
*
* @exception SQLException if a database access error occurs * @exception SQLException if a database access error occurs
*/ */
public String getCatalogName(int column) throws SQLException { public String getCatalogName(int column) throws SQLException {
return ""; return "";
} }


/*
* What is a column's SQL Type? (java.sql.Type int)
*
* @param column the first column is 1, the second is 2, etc.
*
* @return the java.sql.Type value
*
* @exception SQLException if a database access error occurs
*
* @see org.postgresql.Field#getSQLType
*
* @see java.sql.Types
*/
public int getColumnType(int column) throws SQLException { public int getColumnType(int column) throws SQLException {
return getSQLType(column); return getSQLType(column);
} }


/*
* Is a column Text or Binary?
*
* @param column the first column is 1, the second is 2...
*
* @return 0 if column data foramt is TEXT, or 1 if BINARY
*
* @exception SQLException if a database access error occurs
*/
public int getFormat(int column) throws SQLException { public int getFormat(int column) throws SQLException {
return getField(column).getFormat(); return getField(column).getFormat();
} }


/*
* Whats is the column's data source specific type name?
*
* @param column the first column is 1, the second is 2, etc.
*
* @return the type name
*
* @exception SQLException if a database access error occurs
*/
public String getColumnTypeName(int column) throws SQLException { public String getColumnTypeName(int column) throws SQLException {
String type = getPGType(column); String type = getPGType(column);
if (isAutoIncrement(column)) { if (isAutoIncrement(column)) {
Expand All @@ -429,45 +324,45 @@ public String getColumnTypeName(int column) throws SQLException {
return type; return type;
} }


/* /**
* Is the column definitely not writable? In reality, we would have to check the GRANT/REVOKE * {@inheritDoc}
*
* <p>In reality, we would have to check the GRANT/REVOKE
* stuff for this to be effective, and I haven't really looked into that yet, so this will get * stuff for this to be effective, and I haven't really looked into that yet, so this will get
* re-visited. * re-visited.
* *
* @param column the first column is 1, the second is 2, etc. * @param column the first column is 1, the second is 2, etc.*
* * @return true if so*
* @return true if so
*
* @exception SQLException if a database access error occurs * @exception SQLException if a database access error occurs
*/ */
public boolean isReadOnly(int column) throws SQLException { public boolean isReadOnly(int column) throws SQLException {
return false; return false;
} }


/* /**
* Is it possible for a write on the column to succeed? Again, we would in reality have to check * {@inheritDoc}
*
* <p>In reality have to check
* the GRANT/REVOKE stuff, which I haven't worked with as yet. However, if it isn't ReadOnly, then * the GRANT/REVOKE stuff, which I haven't worked with as yet. However, if it isn't ReadOnly, then
* it is obviously writable. * it is obviously writable.
* *
* @param column the first column is 1, the second is 2, etc. * @param column the first column is 1, the second is 2, etc.
*
* @return true if so * @return true if so
*
* @exception SQLException if a database access error occurs * @exception SQLException if a database access error occurs
*/ */
public boolean isWritable(int column) throws SQLException { public boolean isWritable(int column) throws SQLException {
return !isReadOnly(column); return !isReadOnly(column);
} }


/* /**
* Will a write on this column definately succeed? Hmmm...this is a bad one, since the two * {@inheritDoc}
*
* <p>Hmmm...this is a bad one, since the two
* preceding functions have not been really defined. I cannot tell is the short answer. I thus * preceding functions have not been really defined. I cannot tell is the short answer. I thus
* return isWritable() just to give us an idea. * return isWritable() just to give us an idea.
* *
* @param column the first column is 1, the second is 2, etc.. * @param column the first column is 1, the second is 2, etc..
*
* @return true if so * @return true if so
*
* @exception SQLException if a database access error occurs * @exception SQLException if a database access error occurs
*/ */
public boolean isDefinitelyWritable(int column) throws SQLException { public boolean isDefinitelyWritable(int column) throws SQLException {
Expand All @@ -478,14 +373,12 @@ public boolean isDefinitelyWritable(int column) throws SQLException {
// END OF PUBLIC INTERFACE // END OF PUBLIC INTERFACE
// ******************************************************** // ********************************************************


/* /**
* For several routines in this package, we need to convert a columnIndex into a Field[] * For several routines in this package, we need to convert a columnIndex into a Field[]
* descriptor. Rather than do the same code several times, here it is. * descriptor. Rather than do the same code several times, here it is.
* *
* @param columnIndex the first column is 1, the second is 2... * @param columnIndex the first column is 1, the second is 2...
*
* @return the Field description * @return the Field description
*
* @exception SQLException if a database access error occurs * @exception SQLException if a database access error occurs
*/ */
protected Field getField(int columnIndex) throws SQLException { protected Field getField(int columnIndex) throws SQLException {
Expand All @@ -511,18 +404,6 @@ protected int getSQLType(int columnIndex) throws SQLException {


// This can hook into our PG_Object mechanism // This can hook into our PG_Object mechanism


/**
* Returns the fully-qualified name of the Java class whose instances are manufactured if the
* method <code>ResultSet.getObject</code> is called to retrieve a value from the column.
*
* <code>ResultSet.getObject</code> may return a subclass of the class returned by this method.
*
* @param column the first column is 1, the second is 2, ...
* @return the fully-qualified name of the class in the Java programming language that would be
* used by the method <code>ResultSet.getObject</code> to retrieve the value in the
* specified column. This is the class name used for custom mapping.
* @throws SQLException if a database access error occurs
*/
public String getColumnClassName(int column) throws SQLException { public String getColumnClassName(int column) throws SQLException {
Field field = getField(column); Field field = getField(column);
String result = connection.getTypeInfo().getJavaClass(field.getOID()); String result = connection.getTypeInfo().getJavaClass(field.getOID());
Expand Down

0 comments on commit 825c092

Please sign in to comment.