• Type: Improvement
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: JDO 2 final (2.0)
    • Component/s: api
    • Labels:


      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.


        1. jdo-538.patch
          30 kB
          Craig L Russell



            • Assignee:
              clr Craig L Russell
              cbeams Chris Beams
            • Votes:
              0 Vote for this issue
              0 Start watching this issue


              • Created: