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
P.O. Box 24163
Federal Way, WA
98093
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.
