[jira] Created: (JDO-538) Make more JDO APIs generic

[Craig Russell (JIRA)]

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.