Re: JDO 2.1 specification draft can be reviewed...

Sat, 04 Aug 2007 19:59:20 -0700 

Craig, all
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.


Thanks,

- Chris Beams



From: Craig L Russell <[EMAIL PROTECTED]>
Date: August 3, 2007 7:04:52 PM PDT

To: Apache JDO project <[email protected]>, JDO Expert Group  
<[EMAIL PROTECTED]>

Subject: JDO 2.1 specification draft can be reviewed...


at http://db.apache.org/jdo/documentation.html

Check it out, and send comments...

Craig Russell
Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
408 276-5638 mailto:[EMAIL PROTECTED]
P.S. A good JDO? O, Gasp!



























					Reply via email to