Mailing-List: contact jdo-dev-help@db.apache.org; run by ezmlm
Precedence: bulk
Reply-To: jdo-dev@db.apache.org
Message-ID: <27224309.1191440511217.JavaMail.jira@brutus>
Date: Wed, 3 Oct 2007 12:41:51 -0700 (PDT)
From: "Craig Russell (JIRA)" <jira@apache.org>
To: jdo-dev@db.apache.org
Subject: [jira] Commented: (JDO-538) Make more JDO APIs generic
In-Reply-To: <29253486.1191439190783.JavaMail.jira@brutus>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 7bit


    [ https://issues.apache.org/jira/browse/JDO-538?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12532217 ] 

Craig Russell commented on JDO-538:
-----------------------------------

> 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); 

The executeWithArray was deliberately different from execute because we wanted to allow for an object array to be passed as a single parameter to execute. 

For example, we envisaged this usage: 
Query q = pm.newQuery("SELECT e FROM Employee e WHERE param.contains(name) PARAMETERS String[ ] param");
q.execute(new String[ ] {"Joe", "Bob");

If we got rid of the executeWithMap, there would be no way to pass a String[ ] to execute.  

That said, I think it makes sense to replace executeWithArray (Object[ ] parameters) with executeWithArray(Object... parameters). 

Any objections?


> 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: Chris Beams
>            Assignee: Craig Russell
>             Fix For: JDO 2 maintenance release 1
>
>         Attachments: jdo-538.patch
>
>
> 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.