Make more JDO APIs generic
--------------------------
Key: JDO-538
URL: https://issues.apache.org/jira/browse/JDO-538
Project: JDO
Issue Type: Improvement
Components: api2
Affects Versions: JDO 2 final
Reporter: Craig Russell
Fix For: JDO 2 maintenance release 1
Several suggestions relating to evolving the API in support of Java5 features:
11.6, "Optional Feature Support":
The current draft specifies the signature
Collection supportedOptions();
then continues to read
"This method returns a Collection of String [...]"
This suggests that the signature should be
Collection<String> supportedOptions();
14.6.1, "Query Execution"
I suggest we eliminate
Object execute(Object p1);
Object execute(Object p1, Object p2);
Object execute(Object p1, Object p2, Object p3);
and deprecate
Object executeWithArray(Object[] parameters);
in favor of a newly added
Object execute(Object... parameters);
This new method would seamlessly support any existing calls to the three
eliminated methods, and is a proper replacement for executeWithArray().
This would would leave us with three (non-deprecated) execution methods off the
Query interface:
Object execute();
Object execute(Object... parameters);
Object executeWithMap(Map parameters);
A slightly more radical approach to this evolution would have us also eliminate
Object execute();
because the new varargs method can by definition support calls without
arguments,
and deprecate
Object executeWithMap(Map params);
in favor of a new
Object execute(Map params);
because Java can disambiguate between calls to execute(Object... params) and
execute(Map params) just fine. This is predecated by the assumption that it
would never be valid to pass a Map instance as a first-class query parameter.
That might be a faulty assumption, it might also just be confusing.
If all these changes were made, we'd be left with an execution API consisting
of just two methods:
Object execute(Object... params);
Object execute(Map params);
This is, I believe, technically favorable and cleaner, but technical
considerations are not the only valid ones. Leaving the no-arg execute() might
be friendly to folks that don't understand varargs, etc.
14.8, "Deletion by Query":
The rationale used above for paring down Query's execute methods could also be
applied to Query's deletePersistentAll methods. It would be legal and
Java5-ish to eliminate the no-arg deletePersistentAll method and reduce the API
down to:
long deletePersistentAll(Object... params);
long deletePersistentAll(Map params);
...
There's a number of other places in the spec changes like the ones mentioned
here could be made, but I might be getting ahead of myself :-) I'll await
comments before touching on anything else.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
