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

> 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 <Craig.Russell@...>
>> Date: August 3, 2007 7:04:52 PM PDT
>> To: Apache JDO project <jdo-dev@...>, JDO Expert Group  
>> <jdo-experts-ext@...>
>> 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:Craig.Russell@...
>> P.S. A good JDO? O, Gasp!
>>
>
>