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] Commented: (JDO-446) Add subqueries APIs
Date Sat, 27 Oct 2007 18:41:51 GMT

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

Craig Russell commented on JDO-446:

Hi Michael,

As I was reading the patch, I thought that it might be better if we eliminated most of the
javadoc that is duplicated in the four addSubquery methods. This is because some of the wording
used in the original patch has been changed in the specification to make it clearer. Specifically,
the specification now says 
This method adds a subquery to this Query. A subquery is composed as a Query and subsequently
attached to a different Query (the outer Query) by calling this method. The String parameters
are trimmed of white space. 
The Query parameter instance is unmodified as a result of the addSubquery or subsequent execution
of the outer Query. Only some of the parameter query parts are copied for use as the subquery.
The parts copied include the candidate class, filter, parameter declarations, variable declarations,
imports, ordering specification, uniqueness, result specification, and grouping specification.
The association with a PersistenceManager, the candidate collection or extent, result class,
and range limits are not used. 
The variableDeclaration parameter is the name of the variable containing the results of the
subquery execution. If the same value of variableDeclaration is used to add multpile subqueries,
the subquery replaces the previous subquery for the same named variable. If the subquery parameter
is null, the variable is unset, effectively making the variable named in the variableDeclaration
unbound. If the trimmed value is the empty String, or the parameter is null, then JDOUserException
is thrown.
The candidateCollectionExpression is the expression from the outer query that represent the
candidates over which the subquery is evaluated. If the trimmed value is the empty String,
or the parameter is null, then the candidate collection is the extent of the candidate class.
When comments on the spec wording are all resolved, we should put them back into the javadoc.
So I'm thinking that maybe we should avoid copying and pasting into four different methods.

What I don't understand well is the impact on javadoc for code completion. If we have the
full javadoc only on the first method, and the paragraph on the parameter handling is mostly
in the single string version, do we hurt the usability for users depending on javadoc for
code completion? I'm pretty sure that javadoc for regular users will not suffer if there is
a @see reference that points to the full description in the other method.

Any comments from code completion fans?

> Add subqueries APIs
> -------------------
>                 Key: JDO-446
>                 URL: https://issues.apache.org/jira/browse/JDO-446
>             Project: JDO
>          Issue Type: New Feature
>          Components: api2, api2-legacy
>    Affects Versions: JDO 2 final
>            Reporter: Michelle Caisse
>            Assignee: Michael Bouschen
>             Fix For: JDO 2 maintenance release 1
>         Attachments: Query-patch.txt, subquery-api.patch
> In 14, add subqueries to permit e.g. select from Employee where this.salary > (select
avg(salary) from Employee)

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

View raw message