db-jdo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Craig Russell (JIRA)" <j...@apache.org>
Subject [jira] Created: (JDO-538) Make more JDO APIs generic
Date Wed, 03 Oct 2007 19:19:50 GMT
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

	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

This message is automatically generated by JIRA.
You can reply to this email to add a comment to the issue online.

View raw message