sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Martin Desruisseaux (JIRA)" <>
Subject [jira] [Commented] (SIS-180) Place a crude JDBC driver over Dbase files
Date Thu, 23 Oct 2014 16:33:33 GMT


Martin Desruisseaux commented on SIS-180:

Thanks for the new JIRA task. I have applied a few changes in the JDBC classes:

* Replaced {{InvalidDbaseFileFormatException}} by the standard {{SQLNonTransientConnectionException}}.
Especially since the former moved to SIS internal packages, it can theoretically not be known
to the user.
* Replaced the resource properties files by the SIS mechanism (which is itself built on top
of JDK resource bundles):
** Collapsed {{}}, {{}}, {{}}
and {{}} in a single {{}} file. This avoid redundancies
like the message for closed connection, which was repeated in different resource files.
** Moved {{}} from the {{src/main/resources}} to the {{src/main/java}}
directory. While not a Java source, the SIS mechanism does not bundle the properties file
directly in the JAR file neither. The resources are instead bundled in a kind of compiled
form by our {{sis-build-helper}} plugin.
** Element order in {{}} file does not matter. I tend to use alphabetical
order, but any other order is okay as long as this is structured in a way easy to find when
the file has a lot of resources. It is okay to put large comment explaining the logic (if
desired), since those comments are omitted in the compiled result.
** Some differences between French and English languages: French quotation marks versus English
quotation marks, a space before ":" in French but not in English. In French the space before
":" or adjacent to the quotation marks is {{\\u202f}} (narrow no-break space). The easiest
way to edit is to always copy-and-paste those character sequences instead than typing them.
** When using the SIS resources, the key names need to be valid Java identifiers. I omit the
"exception" or "log" prefix since I found (in other resources) that the same message can sometime
be used in both case. By convention, I use the "_(number of arguments)" prefix in order to
see in source code how many arguments are expected. This reduce the risk of errors.
** Single quote does not need to be doubled in the SIS resource files for  {{MessageFormat}}
compliance. This is done automatically by SIS resource compiler.
** Note the {{}} file, which contains static constants for the resource keys
in order to ensure compile-time safety. We don't need to edit this file manually: just add
new entries in the {{*.properties}} files, then run {{mvn compile}} from the command line
(it is okay to be only in the {{sis-shapefile}} directory for faster compilation). The {{}}
file will be updated automatically.
* The {{throw new SQLException(...)}} instructions were also logging a warning at the {{SEVERE}}
level. I took the liberty to omit the logging step. I think we should either log a warning
or throw an exception, but not both. Furthermore {{Level.SEVERE}} should be reserved for serious
problem which compromise the system (or Apache SIS library as a whole) integrity. Its usage
should be very rare.
* Omit the {{m_}} prefix for member fields. While this convention is sometime used, this is
not really the usage in Java.
* Edited javadoc for uniformity with other SIS classes and re-arranged the method order in
an attempt to keep related methods together (the order in JDBC interfaces is more historical
than logical).
* Provided default implementation when a sensible behaviour exists. For example all {{get}}
and {{update}} method of {{ResultSet}} with a {{String columnLabel}} argument convert the
label to an index by invoking {{findColumn(String)}}, then delegate to the method having a
{{int columnIndex}} argument. Also some method like {{first()}}, {{previous()}}, {{relative(int)}}
etc. can delegate their work to {{absolute(int)}}. For each class, a table in the class javadoc
document most of the default implementations.

Open questions:

* {{AbstractConnection.rollback()}} log a warning. I would have expected an exception to be
thrown, since a change that the user may have expected in the database did not occurred because
of unsupported functionality. This is different than {{commit()}}, which may have invisible
* Same idea apply to all setters: it seems to me that all of them shall thrown an exception
instead than logging a warning. This is the same idea than {{java.util.AbstractCollection}}
for instance. Some exception to this rule would be when the given value is the expected one.
For instance {{AbstractConnection.setAutoCommit(boolean)}} would throw an exception only if
the given value is {{false}}.
* Probably some getters do not need to log a warning. For example {{Connection.getTypeMap()}}
javadoc said "_Unless the application has added an entry, the type map returned will be empty_".
Since we do not support the {{setTypeMap}} method returning an empty map is the correct value
and may not need a warning.

> Place a crude JDBC driver over Dbase files
> ------------------------------------------
>                 Key: SIS-180
>                 URL:
>             Project: Spatial Information Systems
>          Issue Type: Improvement
>          Components: Storage
>    Affects Versions: 0.5
>            Reporter: M. Le Bihan
>            Assignee: Martin Desruisseaux
>            Priority: Minor
>             Fix For: 0.5
>         Attachments:
> It would be useful to be able to query DBF content through SQL.
> But there are no free drivers available for the old _Dbase 3_ format.
> The first step is to create short implementations of _Connection_, _Statement_, _ResultSet_,
_ResultSetMetadata_ interfaces for a JDBC using our _Database_ class as core binary loader
at the begining.
> The main difficulty is to respond to a SQL request, and first : being able to analyze
it to understand what is expected.
> The SQL request analysis is a very strong job, but I suggest to ease it a lot by relying
on _AntLR_ API for grammar analysis, associated with a BNF grammar file, maybe taken from
^1^ or from elsewhere (grammars are of public domain).
> The goal of this current JIRA is only to be able to perform a 
> _SELECT * FROM <shapefile layer name>_
> The WHERE clause or the selection of fields, will come later in other JIRA.
> No transactions, classic _Statement_ only.
> _PreparedStatement_ would be also implemented later (another JIRA).
> Of course, this improvment can be discarded if an open source or free driver is discovered,
that would allow us to execute SQL requests on DBase 3 easily.
> ^1^ For example, [] has some BNF, but maybe elsewhere they
will more compliant with AntLR.

This message was sent by Atlassian JIRA

View raw message