| Craig Russell (JIRA) 2007-10-27, 7:11 pm |
|
[ https://issues.apache.org/jira/brow...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, paramete
r 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 use
d.
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 var
iable. 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 dependi
ng 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.
|