incubator-jspwiki-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Andrew Jaquith (JIRA)" <>
Subject [jira] Commented: (JSPWIKI-38) Rename packages to "org.apache.jspwiki"
Date Mon, 22 Dec 2008 23:11:44 GMT


Andrew Jaquith commented on JSPWIKI-38:


Your previous comment was very helpful. It illuminated several important points, which I either
failed to understand, or you failed to communicate. That's why we have these discussions,
right? To make our points clear, so that we may find common ground.

In particular, I failed to appreciate your intent to keep an entire package tree under the
.api package. My impression was that there would not be a hierarchy there, and that everything
that developers needed to rely on would go into one flat namespace. That seemed messy. Ok.
It's good that that's not what you meant.

Now, I could fence with you a bit more about the fact that J2SE and J2EE are, in fact, NOT
specifications and are actually APIs, but would distract from where we need to go, which is
to figure out what we need to do. :)

So, let's see if we can agree on the following principles:
1. Specifying a public API -- in an Apache package namespace -- is a good and worthy goal
2. Implementing the API -- in a separate, "private" package namespace is desirable
3. The namespaces should be distinct enough that developers should be able to tell what APIs
are "public" and which ones are "private"
4. It follows that the public interface and private implementations should not be in the same
package hierarchy (your logic was persuasive...)
5. The public interface and private implementations *may* be in the same source folder (though
I'd like to see them separated...)

With me so far? Ok, good. Here's what I propose:
- Private implementations live on in the "com.ecyrd.jspwiki" package namespace
- Public APIs move to the "org.apache.jspwiki" package namespace
- We do not create a "org.apache.jspwiki.api" package -- just snip the .api subpackage and
move everything up a level
- Create parallel packages under "org.apache.jspwiki.api" as needed. For example: .auth

In essence, this creates two trees, one that is org.apache.jspwiki and the other, which is
com.ecyrd.jspwiki (what we have now). The two would have parallel subpackage structures. Personally,
I don't think we need to keep these in separate source folders, although we might want to
package them into separate jars (jspwiki-api.jar + jspwiki-impl.jar?) at build-time.

I think this is a nice solution. It has the benefit of being simple. The trick, of course,
will be figuring out what types need to migrate from one tree to the other. Judicious use
of the Extact Interface... refactoring tool will become an important skill. :)


> Rename packages to "org.apache.jspwiki"
> ---------------------------------------
>                 Key: JSPWIKI-38
>                 URL:
>             Project: JSPWiki
>          Issue Type: Task
>            Reporter: Janne Jalkanen
>            Assignee: Janne Jalkanen
>             Fix For: 3.0

This message is automatically generated by JIRA.
You can reply to this email to add a comment to the issue online.

View raw message