incubator-jspwiki-dev mailing list archives

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


Janne Jalkanen commented on JSPWIKI-38:

The Ruby on Rails folks have taught an important lesson: convention over configuration.  I
think this is very powerful, and Stripes uses the same paradigm as well by defaulting to certain
package naming conventions for its ActionBeans: in fact, they force you to have an extra level
of depth in your package naming by assuming your ActionBeans lie in the ".stripes." or ".action."
packages.  In the same vein, I think the separation of the API classes into a separate hierarchy
of their own does make sense by encoding the fact that they *are* API classes directly into
the package names themselves.  Much like the "plugin" in the package name means that these
are plugins.

Now, I am not entirely certain whether moving practically all of our classes (save a few odd
stranglers, perhaps ten or so for 3.0) into a .private -namespace makes sense either.  It
is certainly not the simple solution that Andrew alluded to above, and will probably confuse
developers.  Think about the two different messages: "You may use anything in the api-package,
and that will be stable." vs "You may use anything under org.apache.jspwiki.* EXCEPT for the
packages under private, and all those will be stable (except those aforementioned packages)"
 There's a subtle difference, and I would much rather go for the first one than the second
one.  Easier to communicate, easier to code, easier to understand and easier to build scripts
for.  And, while creation of an "impl" -package might keep third party developers happier,
it will annoy our current core developer base by introducing an extra layer.  After all, *we*
have to deal with those 350+ classes all the time.

However, we could make a cosmetic change by creating a JSPWiki API subproject, call it "jspwiki-api".
 It's really all about switching a period to a dash, but it does not create any further nesting
levels (though since most developers these days *do* use IDEs, I don't think any extra levels
are really a problem).  So, we would have "org.apache.jspwiki" with the implementation, and
"org.apache.jspwiki-api" for the API.

Other possibility is to treat these in reverse, but I don't really like the "impl" or "private"
names.  There would need to be a better naming convention.

I guess my main objection is that since the aim of this project is to produce the wikiengine
itself, not the API, I really don't like the idea that we give the API the first-class citizen
treatment and force the actual implementation to some second-tier packages.  The org.apache.jspwiki
-package should really be about the JSPWiki *engine*, not an abstract API class set.  If we
had set out to do to create an API definition, then yes, then obviously we would do things
differently, but I don't think API creation has ever been more than just an issue on this

If we wish to have a top-level package for the API, then perhaps a subproject with own dedicated
package name might make most sense.

> 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