Hi all,
 
As I was reading through the 2006-01-03 version of the spec along with
Craig's most recent FetchPlan proposal (subject "RE: [IMPORTANT]
Fetch-depth"), I kept getting confused between the current fetchSize and
proposed maxFetchDepth properties on FetchPlan.  There is only a small
mention in section 12.7 that fetchPlan only applies to "the number of
instances of multi-valued fields", meaning collections, maps, and arrays.
The javadoc for set/getFetchSize in the spec says nothing about multi-valued
fields explicitly, and the Apache JDO source javadoc for the API says even
less.
 
I would prefer that the API itself be more self-documenting, so I'm
suggesting that we rename the fetchSize property to include something about
the fact that it applies to collection and is not the same as maxFetchDepth,
further, that is the logical complement to depth.  Taking both of these into
consideration, I would suggest fetchCollectionWidth, "Collection" for
multivalued fields, "Width" to distinguish it from maxFieldDepth.  However,
I don't really like that, since we're talking about maps and arrays as well
as collections, and I think "width" is sufficient to distinguish it from
depth, even though it doesn't have the "max" prefix.
 
So...........
 
My recommendation to make the API more self-documenting is to change
fetchSize to fetchWidth, so as to clearly show that is the complement of
maxFetchDepth in Craig's proposal.  The small educational issue that "width"
refers to size for collections/maps & length for arrays.  If you envision a
detached graph starting with the root object at the top and descending
downward, it becomes even more obvious.
 
The only remaining question is whether to remove the "max" prefix in
"maxFetchDepth", making "fetchWidth" and "fetchDepth" even better
complements.
 
Craig, perhaps a negative vote on changing the current "fetchSize" property
to "fetchWidth" and the proposed "maxFetchDepth" to just "fetchDepth" would
be good, but it's my suggestion.  I'll leave that to you, fearless leader.
 
--matthew
 
Matthew T. Adams
Corporate Technical Advisor & Senior Consultant
Mobile:  +1 253 732 1051
Phone:  +1 206 331 3833
Fax:  +1 815 331 0952
matthew.adams@xcalia.com
P.O. Box 24163
Federal Way, WA  98093
www.xcalia.com <http://www.xcalia.com/> 
 

 
Xcalia makes implementing SOA easy with agile business intermediation
software that combines heterogeneous data with services to easily develop
and deploy transactional composite applications.  Enterprises can quickly
respond to changing business requirements and dramatically reduce the costs
of data access and service integration.
 

[ Post a follow-up to this message ]

Matthew T. Adams wrote:

Hi Matthew,

I don't think "fetchWidth" is particularly self-documenting; the "width"
of a collection/array is not terminology I'm familiar with, and I would
imagine it would play the same way to most developers.

Perhaps something involving "limit" might be clearer to those familiar
with the SQL pseudo-keyword.

Wes


> Hi all,
>
> As I was reading through the 2006-01-03 version of the spec along with
> Craig's most recent FetchPlan proposal (subject "RE: [IMPORTANT]
> Fetch-depth"), I kept getting confused between the current fetchSize
> and proposed maxFetchDepth properties on FetchPlan.  There is only a
> small mention in section 12.7 that fetchPlan only applies to "the
> number of instances of multi-valued fields", meaning collections,
> maps, and arrays.  The javadoc for set/getFetchSize in the spec says
> nothing about multi-valued fields explicitly, and the Apache JDO
> source javadoc for the API says even less.
>
> I would prefer that the API itself be more self-documenting, so I'm
> suggesting that we rename the fetchSize property to include something
> about the fact that it applies to collection and is not the same as
> maxFetchDepth, further, that is the logical complement to depth.
> Taking both of these into consideration, I would suggest
> fetchCollectionWidth, "Collection" for multivalued fields, "Width" to
> distinguish it from maxFieldDepth.  However, I don't really like that,
> since we're talking about maps and arrays as well as collections, and
> I think "width" is sufficient to distinguish it from depth, even
> though it doesn't have the "max" prefix.
>
> So...........
>
> My recommendation to make the API more self-documenting is to change
> fetchSize to fetchWidth, so as to clearly show that is the complement
> of maxFetchDepth in Craig's proposal.  The small educational issue
> that "width" refers to size for collections/maps & length for arrays.
> If you envision a detached graph starting with the root object at the
> top and descending downward, it becomes even more obvious.
>
> The only remaining question is whether to remove the "max" prefix in
> "maxFetchDepth", making "fetchWidth" and "fetchDepth" even better
> complements.
>
> Craig, perhaps a negative vote on changing the current "fetchSize"
> property to "fetchWidth" and the proposed "maxFetchDepth" to just
> "fetchDepth" would be good, but it's my suggestion.  I'll leave that
> to you, fearless leader.
>
> --matthew
>
> *Matthew T. Adams*
> Corporate Technical Advisor & Senior Consultant
> Mobile:  +1 253 732 1051
> Phone:  +1 206 331 3833
> Fax:  +1 815 331 0952
> matthew.adams@xcalia.com <mailto:matthew.adams@xcalia.com>
> P.O. Box 24163
> Federal Way, WA  98093
> www.xcalia.com <http://www.xcalia.com/>
>
>
> Xcalia makes implementing SOA easy with agile business intermediation
> software that combines heterogeneous data with services to easily
> develop and deploy transactional composite applications.  Enterprises
> can quickly respond to changing business requirements and dramatically
> reduce the costs of data access and service integration.
>

[ Post a follow-up to this message ]

Yeah, "width" was just a nice complement to "depth", but I agree with =
you
that it's not as inuitive as it could be.  Another option that occurred =
to
me after sending my prior message was get/setCollectionFetchSize.  I =
think
it's good, and as long as people can generalize from collection.size() =
to
map.size() and array length, it works for me.  It certainly makes it =
obvious
that it applies to collection-like thingies, yes?

The question still remains as whether or not to use the "max" prefix on =
both
this property and the fetch depth

--matthew

>-----Original Message-----
>From: Wes Biggs [mailto:wes@tralfamadore.com]=20
>Sent: Thursday, January 26, 2006 7:29 AM
>To: 'JDO Expert Group'
>Cc: jdo-dev@db.apache.org
>Subject: Re: FetchPlan's fetchSize property: better name proposal
>
>
>Matthew T. Adams wrote:
>
>Hi Matthew,
>
>I don't think "fetchWidth" is particularly self-documenting;=20
>the "width"=20
>of a collection/array is not terminology I'm familiar with,=20
>and I would=20
>imagine it would play the same way to most developers.
>
>Perhaps something involving "limit" might be clearer to those familiar=20
>with the SQL pseudo-keyword.
>
>Wes
>
> 
>along with=20 
>something=20 
>"Width" to=20 
>like that,=20 
>collections, and=20 
>complement=20 
>for arrays. =20 
>object at the=20 
>intermediation=20 
>Enterprises=20 
>dramatically=20 
>
>
>

[ Post a follow-up to this message ]