[ https://issues.apache.org/jira/browse/SIS-189?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15046333#comment-15046333
]
M. Le Bihan edited comment on SIS-189 at 12/8/15 5:30 AM:
----------------------------------------------------------
{color:darkblue}_Wrap the SQL exceptions into DataStoreException using the Throwable.initCause(Throwable)
method or the convenience method. There is no need to create dedicated subclasses of DataStoreException
(we can, but this is not mandatory)._{color}
It's done at {{Shapefile}} (or I think before : {{InputFeatureStream}}) level.
{{ShapefileNotFoundException}}, {{DbaseFileNotFoundException}}, {{InvalidShapefileFormatException}},
{{InvalidDbaseFileFormatException}}, {{DataStoreQueryException}}, {{DataStoreQueryResultException}}
are all extending {{DataStoreException}}, and their relative {{SQLException}} are in their
roots causes only.
SQL exceptions are summarized into Data Store exceptions this way :
+Problems having chances to come from the environment :+
{{SQLDbaseFileNotFoundException}} -> {{DbaseFileNotFoundException}}
{{SQLShapefileNotFoundException}} -> {{ShapefileNotFoundException}}
+Problems having chances to come from developer code :+
{{SQLConnectionClosedException}} -> {{DataStoreClosedException}}
{{SQLInvalidStatementException}}, {{SQLIllegalParameterException}}, {{SQLNoSuchFieldException}},
{{SQLUnsupportedParsingFeatureException}}, {{SQLFeatureNotSupportedException}}, {{SQLNoDirectAccessAvailableException}}->
{{DataStoreQueryException}}
{{SQLNotNumericException}} | {{SQLNotDateException}} -> {{DataStoreQueryResultException}}
+Problems depicting flawed files :+
{{SQLInvalidDbaseFileFormatException}} -> {{InvalidDbaseFileFormatException}}
{color:darkblue}Subclasses of DataStoreException{color}
*{color:red}Are mandatory.{color}*
Let me give you another explicit name for {{DataStoreException}} in this sample code :
{code:java}try {
... various methods called, using one or more data stores ...
}
catch(ProblemException e) {
// What happened ? The program is in the darkness here : is there a file missing, a wrong
query done, and what file has the problem ?
// The only thing the program can do now is a pathetic :
log.severe(e.getMessage()); // Or why not : System.err.println(e.getMessage()); System.exit(0);
? The program has already so much failed, that it won't help anyone anymore...
// The end user will have to undersand the message alone (and maybe do a phone call, open
a ticket...) :
// the program resign.
}{code}
throwing {{DataStoreException}} is quite the same thing as throwing the core {{java.lang.Exception}}
or having a function returning {{Object}} : you planify your program death. I explain myself
:
In the code part I shown upside, in term of Petri net, if before attemting the _try .. catch_
you are in state (=place) E1, and that if case of success you are in state E2,
+each+ distinct exception thrown represent another +different+ state. An unwished state maybe,
but a state however. You can't say : "_E3, E4, E5 ... E10 states follow on from one of these
specific exceptions will be summarized to a global E11 state_" that has no well defined existence
and has especially no sense if done automatically without thinking.
Summarizing to a global state disallow the program to attempt catching some exceptions at
various level of the call stack climb up.
*What is especially what I want a clever program to do !!!!*
Handle a troublesome situation (in place of the end-user) in a case a clueless program won't
! This, just maybe to classify the trouble and send a log to the administrator for files missings
or developers for wrong queries. Loosing the ability to catch specific problems among the
call stack makes your program frail. Or at least the end-user believes it : he sees a program
that stops for "_almost everything_".
Another reason for the existence of subclasses for {{SQLException}} is that they are carrying
specific data to depict each specific problem they are representing :
For example, {{SQLIllegalParameterException}} has for additional members :
- the database file that was queried.
- the sql statement that went wrong.
- the parameter name that was illegal.
- its illegal value.
Why ? Because at the time this exception was issued, the API had _all_ this informations available.
So it has to return them to avoid a developer or a DBA to later have searching for them, what
clueless program, again, forces them to do. Do you know the famous message : "_ORA-1403 :
No Data Found_" found in a log ? How much year of developer's or administrator's time in the
world has caused this message ? What query, what tables ?
However, what I see now, is that I forgot to copy some of these specific exceptions members
to their relative subclass of {{DatastoreException}}. I will correct this.
Never throw any core exception please. Even {{DataStoreException}} is a core exception. Of
persistence nature, but it is.
I would like it to be abstract, by the way.
was (Author: mlebihan):
{color:darkblue}_Wrap the SQL exceptions into DataStoreException using the Throwable.initCause(Throwable)
method or the convenience method. There is no need to create dedicated subclasses of DataStoreException
(we can, but this is not mandatory)._{color}
It's done at {{Shapefile}} (or I think before : {{InputFeatureStream}}) level.
{{ShapefileNotFoundException}}, {{DbaseFileNotFoundException}}, {{InvalidShapefileFormatException}},
{{InvalidDbaseFileFormatException}}, {{DataStoreQueryException}}, {{DataStoreQueryResultException}}
are all extending {{DataStoreException}}, and their relative {{SQLException}} are in their
roots causes only.
SQL exceptions are summarized into Data Store exceptions this way :
+Problems having chances to come from the environment :+
{{SQLDbaseFileNotFoundException}} -> {{DbaseFileNotFoundException}}
{{SQLShapefileNotFoundException}} -> {{ShapefileNotFoundException}}
+Problems having chances to come from developer code :+
{{SQLConnectionClosedException}} -> {{DataStoreClosedException}}
{{SQLInvalidStatementException}}, {{SQLIllegalParameterException}}, {{SQLNoSuchFieldException}},
{{SQLUnsupportedParsingFeatureException}}, {{SQLFeatureNotSupportedException}}, {{SQLNoDirectAccessAvailableException}}->
{{DataStoreQueryException}}
{{SQLNotNumericException}} | {{SQLNotDateException}} -> {{DataStoreQueryResultException}}
+Problems depicting flawed files :+
{{SQLInvalidDbaseFileFormatException}} -> {{InvalidDbaseFileFormatException}}
{color:darkblue}Subclasses of DataStoreException{color}
*{color:red}Are mandatory.{color}*
Let me give you another explicit name for {{DataStoreException}} in this sample code :
{code:java}try {
... various methods called, using one or more data stores ...
}
catch(ProblemException e) {
// What happened ? The program is in the darkness here : is there a file missing, a wrong
query done, and what file has the problem ?
// The only thing the program can do now is a pathetic :
log.severe(e.getMessage()); // Or why not : System.err.println(e.getMessage()); System.exit(0);
? The program has already so much failed, that it won't help anyone anymore...
// The end user will have to undersand the message alone (and maybe do a phone call, open
a ticket...) :
// the program resign.
}{code}
throwing {{DataStoreException}} is quite the same thing as throwing the core {{java.lang.Exception}}
or having a function returning {{Object}} : you planify your program death. I explain myself
:
In the code part I shown upside, in term of Petri net, if before attemting the _try .. catch_
you are in state (=place) E1, and that if case of success you are in state E2,
+each+ distinct exception thrown represent another +different+ state. An unwished state maybe,
but a state however. You can't say : "_E3, E4, E5 ... E10 states follow on from one of these
specifics exceptions will be resumed to a global E11 state_" that has no well defined existence
and has especially no sense if done automatically without thinking.
Summarizing to a global state disallow the program to attempt catching some exceptions at
various level of the call stack climb up.
*What is especially what I want a clever program to do !!!!*
Handle a troublesome situation (in place of the end-user) in a case a clueless program won't
! This, just maybe to classify the trouble and send a log to the administrator for files missings
or developers for wrong queries. Loosing the ability to catch specific problems among the
call stack makes your program frail. Or at least the end-user believes it : he sees a program
that stops for "_almost everything_".
Another reason for the existence of subclasses for {{SQLException}} is that they are carrying
specific data to depict each specific problem they are representing :
For example, {{SQLIllegalParameterException}} has for additional members :
- the database file that was queried.
- the sql statement that went wrong.
- the parameter name that was illegal.
- its illegal value.
Why ? Because at the time this exception was issued, the API had _all_ this informations available.
So it has to return them to avoid a developer or a DBA to later have searching for them, what
clueless program, again, forces them to do. Do you know the famous message : "_ORA-1403 :
No Data Found_" found in a log ? How much year of developer's or administrator's time in the
world has caused this message ? What query, what tables ?
However, what I see now, is that I forgot to copy some of these specific exceptions members
to their relative subclass of {{DatastoreException}}. I will correct this.
Never throw any core exception please. Even {{DataStoreException}} is a core exception. Of
persistence nature, but it is.
I would like it to be abstract, by the way.
> InvalidDbaseFileFormatException should extend DataStoreException
> ----------------------------------------------------------------
>
> Key: SIS-189
> URL: https://issues.apache.org/jira/browse/SIS-189
> Project: Spatial Information Systems
> Issue Type: Sub-task
> Components: Shapefile
> Reporter: Martin Desruisseaux
> Assignee: M. Le Bihan
> Labels: JDBC
> Fix For: 0.7
>
>
> {{InvalidDbaseFileFormatException}} currently extends {{SQLNonTransientException}}. But
the the fact that a {{DataStore}} uses SQL or I/O operations for fetching the data is considered
internal to the data store. The higher-level exception for data stores is rather {{DataStoreException}},
which may contain a {{SQLException}}, {{IOException}} or other kind of exceptions as its cause.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)