RE: excalibur package naming

[Leo Simons <le...@apache.org>]

> Simons,

:)

<snip summary>
> Is this your understanding of the problem, proposed solution
> and motivation behind it as well? (Just checking.)

Of course, the flattening of trees was proposed (has been before)
because we feel we're getting redicously long package names.

Note that I think (and think I have said) under the current
'system', that we should replace "completely descriptive" with
"as completely descriptive as possible while avoiding
namespace collissions".

Keeping those points in mind, yes.

> > > Do we want to use the flat structure you propose if the cost
> > > is incomprehensible names? I do not.
> >
> > That structure has been proposed several times, and accepted. I
> > am open to changing it again if there if enough reason to do so.
> > I don't think the cost of the flat structure is incomprehensible names.
>
> Not neccesarily, but the fact that you *do* get namespace collisions
> that you must solve by using non-descriptive names indicates
> that a flat structure does not scale too well.

It can scale extremely far, though...Java API again is an example.
"Use a flat structure" should then be redefined as "use a not
completely normalized tree structure until we get scalability problems",
and everyone's happy.

The question is how much to normalize.

> > Quoting the Java API once more, it contains many packages in
> > java.* and javax.* (certainly more than excalibur), with peer
> > package dependencies.
>
> And whenever there is multiple implementations of one interface
> that is solved by putting the implementations in subpackages:
> javax.swing.plaf.*

for us that would mean:

org.apache.framework.${interfacepackage}.${SomeInterface}
org.apache.excalibur.${interfaceimplementationpackage}.${specificimplementat
ion}.${SomeInterfaceImplementation}

leading to:

org.apache.avalon.framework.component.ComponentManager
org.apache.avalon.framework.component.DefaultComponentManager
org.apache.avalon.excalibur.component.default.DefaultComponentManager
org.apache.avalon.excalibur.component.excalibur.ExcaliburComponentManager
org.apache.avalon.excalibur.component.phoenix.PhoenixComponentManager
org.apache.avalon.excalibur.component.{bla}.{Bla}ComponentManager

However, there will still be "bla" in there somewhere. And
"bla" is not always "caching" or "ejb". It might be "merlin"
or "fortress".

This is workable for me. Does it satisfy your needs?


(all the below is somewhat off-topic imo)

> > Basically, in the 'logic rule world', you are saying: "I don't
> > want #4". That is no solution, as we have #4 and can't really do
> > without it (or really want to, at least not completely).
>
> The logical steps, quoted:
>
> 1): we have interfaces. These define components that are used to satisfy
>     some use cases.
> 2): we have widely applicable components.
> 3): 1) + 2) -> we potentially have multiple component interfaces that
>     satisfy the same use case.
> 4): we have multiple implementations of 1).
> 5): 3) + 4) -> purely descriptive naming of 1) and 2) will lead to
>     some duplication in descriptive names.
> 6): java does not allow duplication in descriptive names among peers.
> 7): we want our projects to be flat, ie using a structure like
>     org.apache.${projectname}.${packagename}.
> 8): 6) + 7) -> purely descriptive names are not always an option. We
>     will use nondescriptive names instead in those cases.
>
> No. I'm not arguing against #4. That would be madness. I'm saying
> "We do not want #3." I tried to indicate that by defining two
> *interfaces*, but I apologize if I was unclear.

for the sake of keeping the model alive,
"a) + b) -> c" is not normally something you can argue against.
You can argue agains a or b, but not against c. So there is a
flaw in my model, as I should have explained that widely applicable
components means there will be overlap in use case (ie
excalibur.component and phoenix merlin).

If you mean you are arguing that should not be the case, well, you
might be right but it is hardly an option to change the overlap.

> In my experience, having several interfaces to
> the same functionality always leads to one abstracting away from
> the multiple interfaces and putting it behind a single interface
> (like we did with Logger). Or when the functionality of two
> interfaces partially overlap, refactor.

"always leads to" should probably be "should always lead to", and it
doesn't hold true because it is simply too much work. If it wasn't,
there'd be a compatability layer that allows you to "write once, run
on both j2ee and .net*".

*supports cobol too.

> I *am* saying that the implementations in #4 should be named in a
> certain way to solve the original problem described at the top
> of this letter.

And I agree. But there was no "and here's how" yet.

> > Leo Sutic
> > > As for the subpackage names, they should be
> > > descriptive of the difference between the two
> > >implementations:
> > <example snipped>
> >
> > I agree. This is however also not always possible, as there may
> > well be multiple differences, differences that cannot be keyed in
> > a single word (or even phrase), etc etc.
>
> But I say that those instances are very rare. So rare that they
> can be dealt with individually, much as one would deal with exceptions
> to coding standards.

And I say they are common enough in avalon that we must be prepared
to deal with them, and decide on a way to handle those instances before
they occur.

Who of us is correct is irrelevant. We're having a discussion about
how to handle this problem. If it were very rare, we wouldn't have to.

> So I still believe that my -1 has some basis in the voting rules.

let us drop this as well. We have different views, which is caused
by the rules not being completely clear. I don't want to go find out
which view is "official".

<snip>
> So why should you care about all the idiot CTOs in the world?
<snip>

I wrote a reply, but delted it because this is essentialy OT. I care
about idiots being in positions of power in so far as that I think that
is what causes the world problems. Let's drop this.

I can't resist this tho':
> If we do not watch out, a CTO looking at Avalon with several
> medieval names risk having his crap filter triggered. On the other
> hand, if we immediately present the CTO with something that just
> screams "ENTERPRISE DEVELOPMENT", because it *looks* like other frameworks
> for enterprise development, he will get that warm, fuzzy feeling
> and *bam* then we can lay it on with just how technically
> superior we are. Because now he will *stay* and *listen*.

Avalon should not scream enterprise development. I don't want
it to scream anything at all. I'm getting images of Steve Ballmer,
and I don't think he has a solution to our package naming problem.

Instead, Avalon should speak on a normal vocal level, reading like
a good O'reilly book rather than something fuzzy. And the medieval
part of Avalon is/should be like the furry animals on those books:
there, but not in the way.

cheers,

- Leo Simons


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: excalibur package naming

[Leo Simons <le...@apache.org>]

> > for us that would mean:
> >
> > org.apache.framework.${interfacepackage}.${SomeInterface}
> > org.apache.excalibur.${interfaceimplementationpackage}.${specifici
> > mplementat
> > ion}.${SomeInterfaceImplementation}
> >
> > leading to:
> >
> > org.apache.avalon.framework.component.ComponentManager
> > org.apache.avalon.framework.component.DefaultComponentManager
> > org.apache.avalon.excalibur.component.default.DefaultComponentManager
> > 
> org.apache.avalon.excalibur.component.excalibur.ExcaliburComponentManager
> > org.apache.avalon.excalibur.component.phoenix.PhoenixComponentManager
> > org.apache.avalon.excalibur.component.{bla}.{Bla}ComponentManager
> 
> I am extremely nitpicking here, but as I understand it, it would be
> 
> org.apache.framework.component.ComponentManager
> org.apache.framework.component.DefaultComponentManager
> 
> Dropping avalon from the name. I would prefer:
> 
> org.apache.avalon.component.ComponentManager
> org.apache.avalon.component.DefaultComponentManager
> 
> though - just to get the Avalon name in there.

this will have to wait until avalon 5 for compatibility issues
'n stuff.

> org.apache.excalibur.component.DefaultComponentManager
> 
> No need to put in 'default' there. (default is a reserved word,
> so you'd end up with 'defaultimpl' or something).
> 

well, you'd be really 'favoring' these. I'm okay with that tho'.
But, if you have the system

org.apache.${subproject}.${subsubproject}.${someimpl}.SomeImplClasses

that is easier for stuff like dep checking, etc, than using

org.apache.${subproject}.${subsubproject}.DefaultImplClasses
org.apache.${subproject}.${subsubproject}.${someimpl}.SomeImplClasses

> org.apache.excalibur.component.ExcaliburComponentManager
> 
> Let's say that the project itself does not have to repeat its own name
> for implementation, unless there is a need for it or it makes sense
> to put it in a excalibur subpackage.

There is no sense in calling ExcaliburComponentManager
ExcaliburComponentManager. There's a Default one, and then there
is an alternative one. It is not _the_ excalibur one. You are
right tho'.

> For example, if we knew that
> there would be many implementations it would make sense to put it
> in a subpackage. If we feel confident that only one implementation
> will exist, or that only one implementation will be in the
> 'all' project, with other implementations being in subprojects,
> then I say we skip the subpackage.

If you don't know this stuff beforehand and you want to change it
later, that means waiting for a major version change. Anyhow, I'll
hammer out a votable proposal from this.

- Leo

--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: excalibur package naming

[Leo Sutic <le...@inspireinfrastructure.com>]

> From: Leo Simons [mailto:leosimons@apache.org]
>
> > Not neccesarily, but the fact that you *do* get namespace collisions
> > that you must solve by using non-descriptive names indicates
> > that a flat structure does not scale too well.
>
> It can scale extremely far, though...Java API again is an example.

Yes, but the number of different implementations for the same interface
is small, and whenever you see them it is solved with subpackages.

> > > Quoting the Java API once more, it contains many packages in
> > > java.* and javax.* (certainly more than excalibur), with peer
> > > package dependencies.
> >
> > And whenever there is multiple implementations of one interface
> > that is solved by putting the implementations in subpackages:
> > javax.swing.plaf.*
>
> for us that would mean:
>
> org.apache.framework.${interfacepackage}.${SomeInterface}
> org.apache.excalibur.${interfaceimplementationpackage}.${specifici
> mplementat
> ion}.${SomeInterfaceImplementation}
>
> leading to:
>
> org.apache.avalon.framework.component.ComponentManager
> org.apache.avalon.framework.component.DefaultComponentManager
> org.apache.avalon.excalibur.component.default.DefaultComponentManager
> org.apache.avalon.excalibur.component.excalibur.ExcaliburComponentManager
> org.apache.avalon.excalibur.component.phoenix.PhoenixComponentManager
> org.apache.avalon.excalibur.component.{bla}.{Bla}ComponentManager

I am extremely nitpicking here, but as I understand it, it would be

org.apache.framework.component.ComponentManager
org.apache.framework.component.DefaultComponentManager

Dropping avalon from the name. I would prefer:

org.apache.avalon.component.ComponentManager
org.apache.avalon.component.DefaultComponentManager

though - just to get the Avalon name in there.


org.apache.excalibur.component.DefaultComponentManager

No need to put in 'default' there. (default is a reserved word,
so you'd end up with 'defaultimpl' or something).


org.apache.excalibur.component.ExcaliburComponentManager

Let's say that the project itself does not have to repeat its own name
for implementation, unless there is a need for it or it makes sense
to put it in a excalibur subpackage. For example, if we knew that
there would be many implementations it would make sense to put it
in a subpackage. If we feel confident that only one implementation
will exist, or that only one implementation will be in the
'all' project, with other implementations being in subprojects,
then I say we skip the subpackage.


org.apache.phoenix.component.PhoenixComponentManager

Phoenix is a project in itself and not a subproject of Excalibur.


org.apache.excalibur.component.{bla}.{Bla}ComponentManager

Yes. For component managers in Excalibur. Phoenix CMs would
be as above.

> However, there will still be "bla" in there somewhere. And
> "bla" is not always "caching" or "ejb". It might be "merlin"
> or "fortress".
>

--------------------------------------------------------------------
SUMMARY:
--------------------------------------------------------------------

> "Use a flat structure" should then be redefined as "use a not
> completely normalized tree structure until we get scalability problems",
> and everyone's happy.

---------------------------

> Note that I think (and think I have said) under the current
> 'system', that we should replace "completely descriptive" with
> "as completely descriptive as possible while avoiding
> namespace collissions".

---------------------------

> This is workable for me. Does it satisfy your needs?

Yes. If you *did* say that then I missed it.




> The question is how much to normalize.

I'm sure we can take that as we go. My main problem was making
names like 'merlin' (org.apache.phoenix.component.EmbeddedComponentManager?)
the norm, with descriptive names being the exception.

The proposal above is "descriptive when possible, otherwise use common
sense".

Common sense: For 'merlin', for example, I would choose:

    org.apache.phoenix.component.merlin.MerlinComponentManager

and not:

    org.apache.phoenix.merlin.MerlinComponentManager

to at least give a hint to someone seeing

    org.apache.phoenix.component.merlin

that it is somthing component-related.

    org.apache.phoenix.merlin

Doesn't really hint it for me.

/LS


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>