db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Knut Anders Hatlen (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (DERBY-6376) Revise DatabaseMetaData section of Reference Manual
Date Wed, 09 Oct 2013 11:59:45 GMT

    [ https://issues.apache.org/jira/browse/DERBY-6376?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13790279#comment-13790279
] 

Knut Anders Hatlen commented on DERBY-6376:
-------------------------------------------

+1 to mentioning that catalog arguments should be null in the top-level "java.sql.DatabaseMetaData
interface" topic and removing the "Parameters to getProcedureColumns" topic. It also sounds
like a good idea to mention that % can be used as a wildcard in pattern arguments.

I don't see much point in keeping the "java.sql.DatabaseMetaData.getProcedureColumns method"
topic, so +1 to removing that one too.

The "java.sql.DatabaseMetaData.getBestRowIdentifier method" topic contains Derby-specific
information about the algorithm used to find the best identifier. I think it should be retained.
I do find the sentence "This order might not return a unique row." in that topic a bit unclear,
though. I think what it means to say is that the returned identifier is not guaranteed to
identify a unique row. So maybe we should change the sentence to say just that. (Details about
why it's not guaranteed to identify a unique row, is given in the last paragraph of the topic.)

We should probably also keep "Columns in the ResultSet returned by getProcedureColumns", as
it contains some Derby-specific information. Most of it is not Derby-specific, though. And
it's not complete, as it lacks information on the columns DATA_TYPE, PRECISION, LENGTH, SCALE
and RADIX. We should either make it complete, or make it only call out the Derby-specific
info. I think I'm leaning towards the latter. Then we could move the information about the
PROCEDURE_CAT column to the top-level "java.sql.DatabaseMetaData interface" topic and say
that all DatabaseMetaData methods that returned ResultSet with a catalog column will have
NULL in that column. And we can remove the information about PROCEDURE_SCHEM, PROCEDURE_NAME,
COLUMN_NAME, COLUMN_DEF, SQL_DATA_TYPE, SQL_DATETIME_SUB, CHAR_OCTET_LENGTH, ORDINAL_POSITION,
IS_NULLABLE and SPECIFIC_NAME.

I don't have a good answer to why the getProcedureColumns() has been given this much space
in the reference manual, whereas most other methods are not even mentioned. I think there
are Derby-specific columns in other meta-data queries too.

> Revise DatabaseMetaData section of Reference Manual
> ---------------------------------------------------
>
>                 Key: DERBY-6376
>                 URL: https://issues.apache.org/jira/browse/DERBY-6376
>             Project: Derby
>          Issue Type: Improvement
>          Components: Documentation
>    Affects Versions: 10.10.1.1
>            Reporter: Kim Haase
>            Priority: Minor
>
> In a comment on DERBY-6369, Knut Anders Hatlen suggests that the topic "Parameters to
getProcedureColumns" (http://db.apache.org/derby/docs/10.10/ref/rrefpgc1.html) might be removed.
The purpose of the topics under "JDBC Reference" is to provide Derby-specific implementation
information. In this topic, however, the Derby-specific information seems to apply to other
methods as well: the information on catalogs and the information on name patterns.
> It may be that another topic in the same section, "java.sql.DatabaseMetaData.getProcedureColumns
method" (http://db.apache.org/derby/docs/10.10/ref/rrefgpc1.html), could also be removed.
Derby presumably supports other DatabaseMetaData methods that are not mentioned, such as getFunctionColumns
and, more recently, getAttributes (of UDTS) and getUDTs. Why mention this one only?
> The topic "Columns in the ResultSet returned by getProcedureColumns" (http://db.apache.org/derby/docs/10.10/ref/rrefcrsrgpc1.html)
does contain Derby-specific information, listing a couple of columns that are not listed in
the Java SE documentation on this method (see http://docs.oracle.com/javase/7/docs/api/java/sql/DatabaseMetaData.html).
So this topic needs to be retained.
> Some information could be added to the top-level "java.sql.DatabaseMetaData interface"
topic (http://docs.oracle.com/javase/7/docs/api/java/sql/DatabaseMetaData.html) about needing
to specify null for catalog columns and perhaps about using the "%" wildcard to obtain a list
of all items in a particular namePattern field.
> Let me know if these changes don't make sense.



--
This message was sent by Atlassian JIRA
(v6.1#6144)

Mime
View raw message