Should API packages be reorganized?

[GoogleCodeExporter]

Eric has suggested that we might move some bits around.  His suggestions are on 
the mailing list; he may copy them here.  This is a slight modification.

1) move DtdAttributeKind, EventKind, Resolved, and Resolver to base.io

2) move NodeKind to base

These two steps empty the 'root' package.

3) Move everything in base and its child packages to root.

This makes the entry point more obvious.

Marking as high priority, release 1.0. We shouldn't do this after 1.0.  The 
changes are easy enough, with a refactoring IDE, but they are very extensive.

Original issue reported on code.google.com by aale...@gmail.com on 15 Feb 2011 at 5:46

[GoogleCodeExporter]

My suggestions - continuing numbering, so we can summarize at the end exactly 
which we should do:

4) org.genxdm.Feature should presumably also move to o.g.base

I don't concur with #3. I think "mutable" should remain a separate package from 
"base", because we intend to push people to think about immutability when using 
XML.

5) org.genxdm.base.mutable should become org.genxdm.mutable

For that matter, I like that org.genxdm (with changes 1,2,4) won't have 
anything in it, as it forces people to think up front - typed, untyped, 
mutable? So I would suggest not doing #3.

Also, proposed in email, is emptying out the "o.g.names" package:

6) NameSource & NamespaceResolver moves from org.genxdm.names to 
org.genxdm.typed.types

7) NamespaceBinding moves from org.genxdm.names to org.genxdm.nodes

Other items I just noted:

8) Nuke PrefixResolver (not used)

9) Nuke AxisNavigator (not used)

Original comment by eric%tib...@gtempaccount.com on 17 Feb 2011 at 6:09

[GoogleCodeExporter]

[deleted comment]

[GoogleCodeExporter]

Argh.  I apparently wasn't clear.

#3, rephrased: refactor 'base' and its child packages, removing the 'base' 
particle.  The effect of this is that 'base' moves to the root package, base.io 
to io, base.mutable to mutable

So I agree with your #5, because it's part of #3.  Otherwise, no.  I completely 
disagree with the idea of emptying out the root package.  If we're going to do 
this, then moving the base APIs into root is sensible; emptying root and making 
people wander around isn't, in my opinion.

Notably, no one chooses between based, mutable, and typed.  They choose between 
base-alone, base-and-mutable, and base-and-typed.  In short, base *ought* to be 
in the root.

I am -1 on having an empty root package.

As for #6: I see no reason to move a namespace resolver into typed.types.  
Justification?  The only thing valid there is moving NameSource, which is now 
only used to map QNames to Primitive types (apart from deprecated uses for the 
empty namespace uri). I'm +0 to +1 on moving NameSource, -1 to moving 
NamespaceResolver lacking justification for treating namespace resolution as 
part of the typed API.

#7 makes no sense to me.  The fact that things in nodes use NamespaceBinding is 
no justification for putting NamespaceBinding in nodes.  It is, by definition, 
exactly *not* a node (this is the abstraction that appears when the namespace 
axis is not supported, when namespace declarations are not nodes). -1 without 
much better reason than (some) APIs that use it are in nodes.

#8 *shrug*. It was created as a parallel to NamespaceResolver.  Perhaps if some 
justification is given for moving namespace resolution into the typed API, I'll 
understand.  Re-creating this is trivial, if it's desired to remove it. Unless 
a better place to move namespace resolution is proposed, however, I don't see 
the package emptying. -0

#9 No. Check the creation date.  It is possible that cursor will soon have 
axes.  I'm not going to do this while we have so much else on our plates, and 
it isn't certain that it can be done in the way that AxisNavigator implies, but 
it's there for a very good reason.  Note that proposals to develop something 
cursor-like, but lacking the N parameter, would be significantly enhanced by 
the existence of axis iteration via this abstraction (which is parameter-free). 
-1; I would change my mind if and only if a sample implementation of an 
existing bridge (possibly bridgekit's cursor on model, but not certain that 
that's a good use case for the potential functionality here) showed that the 
API is ill-conceived or unimplementable (which is possible). It's there as a 
future direction, saving information about design directions.

Original comment by aale...@gmail.com on 17 Feb 2011 at 6:39

[GoogleCodeExporter]

OK, so Amy and I at least agree on #1, #2, #3, & #4.

Let's go ahead and do that, unless anyone else disagrees?

Original comment by eric%tib...@gtempaccount.com on 23 Feb 2011 at 1:12

[GoogleCodeExporter]

Okay. Beginning work.  Note that there may be some breakage in XML Security; I 
don't have that included in my project.

Clarifying (actual steps):

1) rename base.mutable -> mutable
2) rename base.io -> io
3) move dtdattributekind, eventkind, resolver, resolved -> io
4) move base/* -> root package (where feature and nodekind already live)

Same effect, less movement.

Original comment by aale...@gmail.com on 28 Feb 2011 at 5:11

• Changed state: Started

[GoogleCodeExporter]

All right.

This is done at r142 (supposed to be done at r141, but subversion threw a 
wobbly).

Remaining issues:

1) (part of old #6): move NameSource into the typed hierarchy.

2) (part of old #6): move NamespaceResolver into the typed hierarchy.  Note my 
-1; I do not feel that this is justified and haven't seen an explanation.

3) (old #7) move NamespaceBinding to nodes. Note my -1; given the existence of 
NamespaceResolver (namespace handling in general), I do not see that this is 
adequately justified.  'nodes' is about node information; one *might* be able 
to argue that NamespaceBinding is a 'node replacement,' I suppose, but I 
haven't seen the argument proffered.

4) (old #8) remove PrefixResolver. I'd like to see what happens to 
NamespaceResolver first.  PrefixResolver is typically a client-use API. I agree 
it would be more interesting if both namespace resolver and prefix resolver 
were 'accessible' in some sense from model or cursor, where they are 
'interesting' to users.

5) (old #9) remove AxisNavigator. I am -1, since I checked it in recently. I 
realize that it is not yet in use.  I need to show that it's usable.  I haven't 
got the time at the moment, and perhaps it's premature to save the design 
information in this fashion, but I'd rather have it there, with the comment 
that it's a WIP than have it removed.  If we're to remove it, please argue 
about it with me for a while; I can be convinced (occasionally).

:-)

Original comment by aale...@gmail.com on 28 Feb 2011 at 5:51

[GoogleCodeExporter]

I've patched XML Security in my local copy to work with Amy's latest 
changes.

-Eric.

Original comment by eric%tib...@gtempaccount.com on 28 Feb 2011 at 7:01

[GoogleCodeExporter]

Oops.  This one was done a while ago.  Can't remember the number, but it's 
finished.

Original comment by aale...@gmail.com on 31 Mar 2011 at 5:13

• Changed state: Fixed

[GoogleCodeExporter]

Original comment by eric%tib...@gtempaccount.com on 29 Apr 2011 at 11:15

• Added labels: Milestone-20110415
• Removed labels: Milestone-Release1.0