db-jdo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cbeams <cbe...@gmail.com>
Subject Re: JDO 2.1 specification draft can be reviewed...
Date Sun, 05 Aug 2007 03:00:03 GMT
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@Sun.COM>
> Date: August 3, 2007 7:04:52 PM PDT
> To: Apache JDO project <jdo-dev@db.apache.org>, JDO Expert Group  
> <jdo-experts-ext@Sun.COM>
> 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@sun.com
> P.S. A good JDO? O, Gasp!
>



Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message