You are viewing a plain text version of this content. The canonical link for it is here.
Posted to jetspeed-dev@portals.apache.org by Raphaël Luta <ra...@apache.org> on 2005/06/03 11:24:13 UTC
Jetspeed 2 M4 focus: Documentation !
What:
-----
I'd like to propose a specific focus sor the upcoming M4 release: improving the
documentation available on jetspeed 2 and possibly reorganise the repository to
make it easier for new developpers (or returning developpers like me :) to get
into the code.
Why:
----
- Every time I talk of J2 to external developers (integrators, and such...)
complexity and lack of documentation is the top 1 grief when they have looked
at using J2.
- I'm developping a new feature right now (PagePreference) and I'm losing a
*ridiculous* amount of time trying to understand how the stuff is organized
and how everything interacts:
- many classes have no javadocs explaining what this class is about
- the java package structure is seemingly unrelated to the "physical"
packaging, so it's basically just looking at a class name to know where
it's located (jetspeed-api, commons, components, demo, etc..), against
losing way too much energy trying to navigate.
- the Spring assembly conf files are (mostly) undocumented
If I'm feeling such a pain, I can really sympathize with an external portal
integrator developers building on top of J2 and trying to get some results
fast.
How:
----
Providing there's approval within the community for this drive, I propose that
we tackle it in this order :
#1 Move to SVN.
This will make any refactoring/repackaging much easier.
#2 Start a thread on how to manage our java packages and adopt a clear package
naming policy for the different main code blocks:
- jetspeed-api
- jetspeed engine core components
- jetspeed engine optional components
- application level code (admin stuff, portlet stuff, etc...)
- generic utility code
#3 Update Javadocs and assembly files as soon as possibly :
- if possible go through all the different classes and document them at least
at a basic level of details
- at the very least, whenever working on a class make sure to comment this
class before committing
#4 Rework the user documentation and developer design docs or HOWTO
Update and reorganize the existing design-docs, move to forrest
Task #1 is underway
Task #2 should be approached as a group and I think will be pretty easy to so
thaks to IDE power.
Task #3 really requires the active collaboration of everybody knowledgeable with
the code
I volunteer to drive #4 and complete the forrest site I've started.
--
Raphaël Luta - raphael@apache.org
Apache Portals - Enterprise Portal in Java
http://portals.apache.org/
---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org
Re: PagePreference
Posted by Randy Watler <wa...@wispertel.net>.
Raphael,
> - I'm developping a new feature right now (PagePreference) and I'm
> losing a
> *ridiculous* amount of time trying to understand how the stuff is
> organized
> and how everything interacts:
OT, I know. Is this a PSML extension? I must have missed a thread
somewhere along the way, (sorry). I can probably help you figure out
just about everything in PageManager these days if you need a pointer or
two... (catch me on IRC).
Randy
---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org
Re: Jetspeed 2 M4 focus: Documentation !
Posted by Ate Douma <at...@douma.nu>.
Sorry for the delayed response.
Comments below.
Raphaël Luta wrote:
> How:
> ----
> Providing there's approval within the community for this drive, I
> propose that
> we tackle it in this order :
>
> #1 Move to SVN.
> This will make any refactoring/repackaging much easier.
>
> #2 Start a thread on how to manage our java packages and adopt a clear
> package
> naming policy for the different main code blocks:
+1
> - jetspeed-api
> - jetspeed engine core components
> - jetspeed engine optional components
> - application level code (admin stuff, portlet stuff, etc...)
> - generic utility code
>
> #3 Update Javadocs and assembly files as soon as possibly :
> - if possible go through all the different classes and document them
> at least
> at a basic level of details
> - at the very least, whenever working on a class make sure to comment
> this
> class before committing
+1
>
> #4 Rework the user documentation and developer design docs or HOWTO
> Update and reorganize the existing design-docs, move to forrest
As I don't know yet forrest, could you give a short summary what we will gain by
moving to forrest (and what we might lose)?
I'm not against changing to forrest, but I'd like to know why we should do so...
For what I've seen from forrest sites so far, some things look very nice, but it
seems to have some (serious?) layout problems too.
How stable/complete is it and how difficult is it to use and to get it "right"?
>
> Task #1 is underway
> Task #2 should be approached as a group and I think will be pretty easy
> to so thaks to IDE power.
Refactoring itself is very easy to do these days. But redefining packaging
shouldn't be taken too lightly. In my experience, finding a good or even "best" package naming
and structure is one of the hardest thing in coding and usually subject to personal taste as well.
> Task #3 really requires the active collaboration of everybody
> knowledgeable with
> the code
> I volunteer to drive #4 and complete the forrest site I've started.
>
---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org
Re: Jetspeed 2 java packages structure (Re: Jetspeed 2 M4 focus:
Documentation !)
Posted by Ate Douma <at...@douma.nu>.
David Sean Taylor wrote:
> Raphaël Luta wrote:
>
>> David Sean Taylor wrote:
>>
>> I can understand why we would have 2 base packages one for
>> jetspeed-specific
>> and one more generic JSR-168 portlets but 5 packages is a lot :)
>>
>
> yes perhaps a secondary package for jetspeed administrative portlet
> applications such as
>
> org.apache.jetspeed.applications.admin
> org.apache.jetspeed.applications.palm
> ...
And to extend this, maybe move all the demo portlet apps under o.a.j.applications.examples:
o.a.j.applications.examples.demo
o.a.j.applications.examples.jpetstore
o.a.j.applications.examples.jsf-demo
o.a.j.applications.examples.jsf-demo-myfaces
o.a.j.applications.examples.php
o.a.j.applications.examples.perl
o.a.j.applications.examples.rss
o.a.j.applications.examples.struts-demo
o.a.j.applications.admin
o.a.j.applications.palm
o.a.j.applications.security (separated login/chgpwd)
The gems package/contents then could move to o.a.j.portlets.
And maybe base portlet code for the php, perl and rss apps, iframe, sso etc. could also
be moved to o.a.j.portlets. (see also my previous post).
---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org
RE: Jetspeed 2 java packages structure (Re: Jetspeed 2 M4 focus: Documentation !)
Posted by Scott T Weaver <sc...@binary-designs.net>.
> -----Original Message-----
> From: David Sean Taylor [mailto:david@bluesunrise.com]
> Sent: Tuesday, June 07, 2005 12:30 PM
> To: Jetspeed Developers List
> Subject: Re: Jetspeed 2 java packages structure (Re: Jetspeed 2 M4 focus:
> Documentation !)
>
> Scott T Weaver wrote:
> > I think another question we might want to ask ourselves is "Does having
> all
> > the individual sub-projects really have any true benefits?" I know
> > initially this was to show lines between the different components.
>
> It also makes it very easy to replace a component.
> If someone wants to override the page manager component, simply swap out
> the jar. If we merge all components into one jar it will make this kind
> of pluggable component integration more difficult for integrators.
I don't see how this makes it any more difficult than what we already have
in place. There has never been a need to remove the existing component jar
when creating a custom code to replace it. All the developer has to do is
drop in there custom jar/classes and change the Spring configs to point to
their custom classes. I don't see how being able to remove the default
implementation jar increases the efficiency of this process.
>
> > However,
> > this can be accomplished with good documentation and naming standards.
> > Also, moving things into a smaller number of subprojects would *GREATLY*
> > simplify our build scripts which, IMOHO, have gotten way out of control
> to
> > the point that synchronizing the Jetspeed 2 plugin with the actual build
> > process has become an incredibly painful task.
> >
>
> What if we based the entire build on the plugin?
> That way we wouldn't have both the maven.xml and plugin to maintain.
> Might be a good time to look at Maven 2
+1. That would be great to use the plugin to perform all builds. This
would probably require a major refactoring of the current plugin, but I feel
it needs it anyways.
As for Maven 2, that seems a bit scary. Just as all of our end users are
starting to tolerate Maven 1, we pull the rug right out from under them so
to speak. As much as Maven 2 is probably an improvement over Maven 1, I am
a bit leery to disenfranchise people with requiring them to learn yet
another build system. I guess it really depends on how much better 2 is,
unfortunately, I know nothing about 2 :(
>
> > This is just a quick suggestion of a new structure:
> >
> > |--commons* (no change)
> > |
> > |--jetspeed-api* (no change, possibly renamed to just plain, old "api")
> > |
> > |--components* (All component implementations currently in separate
> > | subprojects would go here)
> > |
> > |--engine* (All engine/container/pipeline stuff goes here)
> > |
> > |--management (All Jetspeed 2 specific management apps and portlets live
> > | here)
> > |
> > |--deployment* (Since the deployment system is somewhat complex, it
> gets
> > | its own subproject. I left it out of management as
> > | management should be an optional build requirement
> > | but deployment is mandatory.)
> > |
> > |--demos (All demo applications/portlets)
> > |
> > |--plugins (Maven plugin goes here along IDE-specific plugins.)
> >
> sounds good, i link the name 'engine', although 'portal' is good too
> i think i prefer 'applications' over demos though as they can be useful
> as is not just demos
Sure "applications" is fine.
>
> a few odd ones not covered here:
>
> content-server
I think we could stick that under engine.
> installer
Installer could go under deployment as an optional task to build it.
> layout-portlets
Hmmm, might do well as its own subproject.
> taglibs
This might also be able to live happily under engine.
>
> --
> David Sean Taylor
> Bluesunrise Software
> david@bluesunrise.com
> [office] +01 707 773-4646
> [mobile] +01 707 529 9194
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
> For additional commands, e-mail: jetspeed-dev-help@portals.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org
Re: Jetspeed 2 java packages structure (Re: Jetspeed 2 M4 focus:
Documentation !)
Posted by David Sean Taylor <da...@bluesunrise.com>.
Scott T Weaver wrote:
> I think another question we might want to ask ourselves is "Does having all
> the individual sub-projects really have any true benefits?" I know
> initially this was to show lines between the different components.
It also makes it very easy to replace a component.
If someone wants to override the page manager component, simply swap out
the jar. If we merge all components into one jar it will make this kind
of pluggable component integration more difficult for integrators.
> However,
> this can be accomplished with good documentation and naming standards.
> Also, moving things into a smaller number of subprojects would *GREATLY*
> simplify our build scripts which, IMOHO, have gotten way out of control to
> the point that synchronizing the Jetspeed 2 plugin with the actual build
> process has become an incredibly painful task.
>
What if we based the entire build on the plugin?
That way we wouldn't have both the maven.xml and plugin to maintain.
Might be a good time to look at Maven 2
> This is just a quick suggestion of a new structure:
>
> |--commons* (no change)
> |
> |--jetspeed-api* (no change, possibly renamed to just plain, old "api")
> |
> |--components* (All component implementations currently in separate
> | subprojects would go here)
> |
> |--engine* (All engine/container/pipeline stuff goes here)
> |
> |--management (All Jetspeed 2 specific management apps and portlets live
> | here)
> |
> |--deployment* (Since the deployment system is somewhat complex, it gets
> | its own subproject. I left it out of management as
> | management should be an optional build requirement
> | but deployment is mandatory.)
> |
> |--demos (All demo applications/portlets)
> |
> |--plugins (Maven plugin goes here along IDE-specific plugins.)
>
sounds good, i link the name 'engine', although 'portal' is good too
i think i prefer 'applications' over demos though as they can be useful
as is not just demos
a few odd ones not covered here:
content-server
installer
layout-portlets
taglibs
--
David Sean Taylor
Bluesunrise Software
david@bluesunrise.com
[office] +01 707 773-4646
[mobile] +01 707 529 9194
---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org
Re: Jetspeed 2 java packages structure (Re: Jetspeed 2 M4 focus: Documentation !)
Posted by Rajesh Jain <rj...@yahoo.com>.
IMHO, someone also needs to look at deeper package structures as well, there are packages with only one or few files. From a end-users prespective if the file names suggest the intent, then packages can be flattened. I was browsing through the svn j2 trunk, and I am a new user of Jetspeed (but not new to java world:-), I wish there were less packages.
Ate Douma <at...@douma.nu> wrote:
Scott T Weaver wrote:
> I think another question we might want to ask ourselves is "Does having all
> the individual sub-projects really have any true benefits?" I know
> initially this was to show lines between the different components. However,
> this can be accomplished with good documentation and naming standards.
> Also, moving things into a smaller number of subprojects would *GREATLY*
> simplify our build scripts which, IMOHO, have gotten way out of control to
> the point that synchronizing the Jetspeed 2 plugin with the actual build
> process has become an incredibly painful task.
>
> This is just a quick suggestion of a new structure:
>
> |--commons* (no change)
> |
> |--jetspeed-api* (no change, possibly renamed to just plain, old "api")
> |
> |--components* (All component implementations currently in separate
> | subprojects would go here)
> |
> |--engine* (All engine/container/pipeline stuff goes here)
> |
> |--management (All Jetspeed 2 specific management apps and portlets live
> | here)
> |
> |--deployment* (Since the deployment system is somewhat complex, it gets
> | its own subproject. I left it out of management as
> | management should be an optional build requirement
> | but deployment is mandatory.)
> |
> |--demos (All demo applications/portlets)
> |
> |--plugins (Maven plugin goes here along IDE-specific plugins.)
>
> * Signifies mandatory subproject for a minimal working build
>
> I left out all the bridges' api pieces as they will be moving into their own
> project.
>
> This leaves the random bits and pieces that are in the portal subproject,
> which we could iron out as we refactor. Please point out anything I missed
> and feel free to modify/suggest changes to the structure.
>
> Flame away,
> -Scott
Ok, I'll bite ;-)
I'm definitely -1 on this (merging all components into one subproject).
I just started with Jetspeed-2 around the time the big refactoring to a component based model took
place and I think it is a very smart thing done.
In my opinion, there is much more value in having clearly defined *and* separated components (based
on a clear contract/api) than only to show a "line" between the many functional parts of what makes
a portal (engine).
One point has already been mentioned by David: it makes it much easier to swap out one
implementation for another (for integrators for instance).
For me though, this is only one benefit, albeit an important one.
What about:
- much better identification of the different functional area's
- a much clearer and cleaner documentation path (but something which still needs to be done
of course)
- getting to "know" the internals of the portal and its many facets is much easier to tackle
Also, from a more technical view:
- a stronger enforcement of (classpath) independence and thus required recognition of
inter-component dependencies (which we should always try to keep a low as possible).
Mixing multiple components into one classpath will most likely lead to (much) increased Law of
Demeter violations.
- much easier independent testing
- The possibility to swap out a component with a different *version* of itself by just replacing
one jar.
Although we don't have reached the level of maturity yet where this is needed *now*, I surely
expect this to happen once we get past the 2.0-FINAL release.
What about wanting to release a new version of the persistence component because a new and much
quicker version of OJB is available. Why (would we have to) release a complete new portal only for
that?
A component does have a version, and we might just as well use it...
Merging the different components back into one subproject will kill off a major aspect of our
future options in my view. Although it might bring a quick and dirty simplification *now*, I think
we are going to pay a high price later ...
Maybe some functional parts have been split too far. I haven't reviewed the current codebase from
this perspective yet so I don't have an opinion on it yet.
If we've gone too far separating in some area's though, then lets fix that.
If the build setup is getting (too) difficult to maintain, then lets discuss that and see how we can
improve it.
But please, let us try to stick to CBD: divide, isolate and conquer.
Regards, Ate
(awaiting being flamed in turn now ;-)
>
>
>
>
>
>>-----Original Message-----
>>From: David Sean Taylor [mailto:david@bluesunrise.com]
>>Sent: Tuesday, June 07, 2005 3:15 AM
>>To: Jetspeed Developers List
>>Subject: Re: Jetspeed 2 java packages structure (Re: Jetspeed 2 M4 focus:
>>Documentation !)
>>
>>Raphaël Luta wrote:
>>
>>>David Sean Taylor wrote:
>>>
>>>>Is that along the lines you are proposing?
>>>>
>>>
>>>I didn't have any definite structure in mind and just wanted to start
>>>the thread, I just know what I don't like: that separate "physical"
>>>package share the same java namespace.
>>>
>>>Example:
>>>
>>>- jetspeed-api has some classes for org.apache.jetspeed.page.document
>>>but components/page-manager defines some classes there too.
>>
>>I agree with Ate that we should move all impls into impl directories
>>
>>
>>>- org.apache.jetspeed.security.impl is shared between portal
>>>and components/security
>>>
>>
>>yup we have a few of those with the core valves
>>Somehow the valves got moved out of the valve directory structure,
>>although it didn't start that way. Maybe we should move all valve impls
>>back to org.apache.jetspeed.portal.valves.impl
>>
>>
>>>- in the applications directory, we have sometimes
>>>org.apache.portals.applications, sometimes org.apache.jetspeed.portlets,
>>>org.apache.jetspeed.demo, org.apache.jetspeed.portlet,
>>>org.apache.portals.gems (not including the iBatis and Struts code)
>>>
>>
>>a lot of the demo portlets are early tests that could probably be either
>> cleaned up or thrown away. Since Gems got voted out of Apache, we can
>>drop that package. Also, Portals Applications was also voted out (much
>>to my dissappointment), but i still like the package name :P, thus I
>>propose org.apache.portals.applications as the root of all portlets
>>
>>so we would have org.apache.portals.applications.demo for example
>>or org.apache.portals.applications.database (to replace the database
>>browsers under gems)
>>
>>
>>
>>>I can understand why we would have 2 base packages one for
>>>jetspeed-specific
>>>and one more generic JSR-168 portlets but 5 packages is a lot :)
>>>
>>
>>yes perhaps a secondary package for jetspeed administrative portlet
>>applications such as
>>
>>org.apache.jetspeed.applications.admin
>>org.apache.jetspeed.applications.palm
>>...
>>
>>
>>>All in all, I think we'd get a lot of value in rationalizating the
>>>whole packages structure although I agree with Ate that doing it right
>>>is difficult.
>>>
>>>My objectives for the refactoring would be:
>>>
>>>- packages should not be shared between components, except one "util"
>>> package for generally useful code not tied to any Jetspeed
>>
>>fonctionality
>>
>>>- it should be possible by looking at the package to know if a class is
>>>part of the Jetspeed API, Portal implementation, Portlets or stand-alone
>>>component.
>>>
>>>- if possible, components should have all the classes rooted in a single
>>> package, although they may define sub-packages from there as they wish
>>>
>>>- components and portlets should follow predictable "patterns" of
>>
>>package
>>
>>> naming conventions.
>>>
>>>Would you agree with objectives or would add/remove some of these ?
>>>
>>>
>>
>>i agree
>>
>>--
>>David Sean Taylor
>>Bluesunrise Software
>>david@bluesunrise.com
>>[office] +01 707 773-4646
>>[mobile] +01 707 529 9194
>>
>>---------------------------------------------------------------------
>>To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
>>For additional commands, e-mail: jetspeed-dev-help@portals.apache.org
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
> For additional commands, e-mail: jetspeed-dev-help@portals.apache.org
>
>
>
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org
Re: Jetspeed 2 java packages structure (Re: Jetspeed 2 M4 focus:
Documentation !)
Posted by Ate Douma <at...@douma.nu>.
Scott T Weaver wrote:
> I think another question we might want to ask ourselves is "Does having all
> the individual sub-projects really have any true benefits?" I know
> initially this was to show lines between the different components. However,
> this can be accomplished with good documentation and naming standards.
> Also, moving things into a smaller number of subprojects would *GREATLY*
> simplify our build scripts which, IMOHO, have gotten way out of control to
> the point that synchronizing the Jetspeed 2 plugin with the actual build
> process has become an incredibly painful task.
>
> This is just a quick suggestion of a new structure:
>
> |--commons* (no change)
> |
> |--jetspeed-api* (no change, possibly renamed to just plain, old "api")
> |
> |--components* (All component implementations currently in separate
> | subprojects would go here)
> |
> |--engine* (All engine/container/pipeline stuff goes here)
> |
> |--management (All Jetspeed 2 specific management apps and portlets live
> | here)
> |
> |--deployment* (Since the deployment system is somewhat complex, it gets
> | its own subproject. I left it out of management as
> | management should be an optional build requirement
> | but deployment is mandatory.)
> |
> |--demos (All demo applications/portlets)
> |
> |--plugins (Maven plugin goes here along IDE-specific plugins.)
>
> * Signifies mandatory subproject for a minimal working build
>
> I left out all the bridges' api pieces as they will be moving into their own
> project.
>
> This leaves the random bits and pieces that are in the portal subproject,
> which we could iron out as we refactor. Please point out anything I missed
> and feel free to modify/suggest changes to the structure.
>
> Flame away,
> -Scott
Ok, I'll bite ;-)
I'm definitely -1 on this (merging all components into one subproject).
I just started with Jetspeed-2 around the time the big refactoring to a component based model took
place and I think it is a very smart thing done.
In my opinion, there is much more value in having clearly defined *and* separated components (based
on a clear contract/api) than only to show a "line" between the many functional parts of what makes
a portal (engine).
One point has already been mentioned by David: it makes it much easier to swap out one
implementation for another (for integrators for instance).
For me though, this is only one benefit, albeit an important one.
What about:
- much better identification of the different functional area's
- a much clearer and cleaner documentation path (but something which still needs to be done
of course)
- getting to "know" the internals of the portal and its many facets is much easier to tackle
Also, from a more technical view:
- a stronger enforcement of (classpath) independence and thus required recognition of
inter-component dependencies (which we should always try to keep a low as possible).
Mixing multiple components into one classpath will most likely lead to (much) increased Law of
Demeter violations.
- much easier independent testing
- The possibility to swap out a component with a different *version* of itself by just replacing
one jar.
Although we don't have reached the level of maturity yet where this is needed *now*, I surely
expect this to happen once we get past the 2.0-FINAL release.
What about wanting to release a new version of the persistence component because a new and much
quicker version of OJB is available. Why (would we have to) release a complete new portal only for
that?
A component does have a version, and we might just as well use it...
Merging the different components back into one subproject will kill off a major aspect of our
future options in my view. Although it might bring a quick and dirty simplification *now*, I think
we are going to pay a high price later ...
Maybe some functional parts have been split too far. I haven't reviewed the current codebase from
this perspective yet so I don't have an opinion on it yet.
If we've gone too far separating in some area's though, then lets fix that.
If the build setup is getting (too) difficult to maintain, then lets discuss that and see how we can
improve it.
But please, let us try to stick to CBD: divide, isolate and conquer.
Regards, Ate
(awaiting being flamed in turn now ;-)
>
>
>
>
>
>>-----Original Message-----
>>From: David Sean Taylor [mailto:david@bluesunrise.com]
>>Sent: Tuesday, June 07, 2005 3:15 AM
>>To: Jetspeed Developers List
>>Subject: Re: Jetspeed 2 java packages structure (Re: Jetspeed 2 M4 focus:
>>Documentation !)
>>
>>Raphaël Luta wrote:
>>
>>>David Sean Taylor wrote:
>>>
>>>>Is that along the lines you are proposing?
>>>>
>>>
>>>I didn't have any definite structure in mind and just wanted to start
>>>the thread, I just know what I don't like: that separate "physical"
>>>package share the same java namespace.
>>>
>>>Example:
>>>
>>>- jetspeed-api has some classes for org.apache.jetspeed.page.document
>>>but components/page-manager defines some classes there too.
>>
>>I agree with Ate that we should move all impls into impl directories
>>
>>
>>>- org.apache.jetspeed.security.impl is shared between portal
>>>and components/security
>>>
>>
>>yup we have a few of those with the core valves
>>Somehow the valves got moved out of the valve directory structure,
>>although it didn't start that way. Maybe we should move all valve impls
>>back to org.apache.jetspeed.portal.valves.impl
>>
>>
>>>- in the applications directory, we have sometimes
>>>org.apache.portals.applications, sometimes org.apache.jetspeed.portlets,
>>>org.apache.jetspeed.demo, org.apache.jetspeed.portlet,
>>>org.apache.portals.gems (not including the iBatis and Struts code)
>>>
>>
>>a lot of the demo portlets are early tests that could probably be either
>> cleaned up or thrown away. Since Gems got voted out of Apache, we can
>>drop that package. Also, Portals Applications was also voted out (much
>>to my dissappointment), but i still like the package name :P, thus I
>>propose org.apache.portals.applications as the root of all portlets
>>
>>so we would have org.apache.portals.applications.demo for example
>>or org.apache.portals.applications.database (to replace the database
>>browsers under gems)
>>
>>
>>
>>>I can understand why we would have 2 base packages one for
>>>jetspeed-specific
>>>and one more generic JSR-168 portlets but 5 packages is a lot :)
>>>
>>
>>yes perhaps a secondary package for jetspeed administrative portlet
>>applications such as
>>
>>org.apache.jetspeed.applications.admin
>>org.apache.jetspeed.applications.palm
>>...
>>
>>
>>>All in all, I think we'd get a lot of value in rationalizating the
>>>whole packages structure although I agree with Ate that doing it right
>>>is difficult.
>>>
>>>My objectives for the refactoring would be:
>>>
>>>- packages should not be shared between components, except one "util"
>>> package for generally useful code not tied to any Jetspeed
>>
>>fonctionality
>>
>>>- it should be possible by looking at the package to know if a class is
>>>part of the Jetspeed API, Portal implementation, Portlets or stand-alone
>>>component.
>>>
>>>- if possible, components should have all the classes rooted in a single
>>> package, although they may define sub-packages from there as they wish
>>>
>>>- components and portlets should follow predictable "patterns" of
>>
>>package
>>
>>> naming conventions.
>>>
>>>Would you agree with objectives or would add/remove some of these ?
>>>
>>>
>>
>>i agree
>>
>>--
>>David Sean Taylor
>>Bluesunrise Software
>>david@bluesunrise.com
>>[office] +01 707 773-4646
>>[mobile] +01 707 529 9194
>>
>>---------------------------------------------------------------------
>>To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
>>For additional commands, e-mail: jetspeed-dev-help@portals.apache.org
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
> For additional commands, e-mail: jetspeed-dev-help@portals.apache.org
>
>
>
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org
Re: Jetspeed 2 java packages structure (Re: Jetspeed 2 M4 focus:
Documentation !)
Posted by Roger Ruttimann <ro...@apache.org>.
Scott T Weaver wrote:
>I think another question we might want to ask ourselves is "Does having all
>the individual sub-projects really have any true benefits?" I know
>initially this was to show lines between the different components. However,
>this can be accomplished with good documentation and naming standards.
>Also, moving things into a smaller number of subprojects would *GREATLY*
>simplify our build scripts which, IMOHO, have gotten way out of control to
>the point that synchronizing the Jetspeed 2 plugin with the actual build
>process has become an incredibly painful task.
>
>
I agree that we ended up with too many sub-projects.
I like the proposed structure especially moving subprojects into components.
What's left out is the documentation. Raphael proposed to use forrest
which is great as long as we use one method for creating documentation
and everybody is committed to it.
>This is just a quick suggestion of a new structure:
>
>|--commons* (no change)
>|
>|--jetspeed-api* (no change, possibly renamed to just plain, old "api")
>|
>|--components* (All component implementations currently in separate
>| subprojects would go here)
>|
>|--engine* (All engine/container/pipeline stuff goes here)
>|
>|--management (All Jetspeed 2 specific management apps and portlets live
>| here)
>|
>|--deployment* (Since the deployment system is somewhat complex, it gets
>| its own subproject. I left it out of management as
>| management should be an optional build requirement
>| but deployment is mandatory.)
>|
>|--demos (All demo applications/portlets)
>|
>|--plugins (Maven plugin goes here along IDE-specific plugins.)
>
>* Signifies mandatory subproject for a minimal working build
>
>I left out all the bridges' api pieces as they will be moving into their own
>project.
>
>This leaves the random bits and pieces that are in the portal subproject,
>which we could iron out as we refactor. Please point out anything I missed
>and feel free to modify/suggest changes to the structure.
>
>Flame away,
>-Scott
>
>
>
>
>
>
>>-----Original Message-----
>>From: David Sean Taylor [mailto:david@bluesunrise.com]
>>Sent: Tuesday, June 07, 2005 3:15 AM
>>To: Jetspeed Developers List
>>Subject: Re: Jetspeed 2 java packages structure (Re: Jetspeed 2 M4 focus:
>>Documentation !)
>>
>>Raphaël Luta wrote:
>>
>>
>>>David Sean Taylor wrote:
>>>
>>>
>>>>Is that along the lines you are proposing?
>>>>
>>>>
>>>>
>>>I didn't have any definite structure in mind and just wanted to start
>>>the thread, I just know what I don't like: that separate "physical"
>>>package share the same java namespace.
>>>
>>>Example:
>>>
>>>- jetspeed-api has some classes for org.apache.jetspeed.page.document
>>>but components/page-manager defines some classes there too.
>>>
>>>
>>I agree with Ate that we should move all impls into impl directories
>>
>>
>>
>>>- org.apache.jetspeed.security.impl is shared between portal
>>>and components/security
>>>
>>>
>>>
>>yup we have a few of those with the core valves
>>Somehow the valves got moved out of the valve directory structure,
>>although it didn't start that way. Maybe we should move all valve impls
>>back to org.apache.jetspeed.portal.valves.impl
>>
>>
>>
>>>- in the applications directory, we have sometimes
>>>org.apache.portals.applications, sometimes org.apache.jetspeed.portlets,
>>>org.apache.jetspeed.demo, org.apache.jetspeed.portlet,
>>>org.apache.portals.gems (not including the iBatis and Struts code)
>>>
>>>
>>>
>>a lot of the demo portlets are early tests that could probably be either
>> cleaned up or thrown away. Since Gems got voted out of Apache, we can
>>drop that package. Also, Portals Applications was also voted out (much
>>to my dissappointment), but i still like the package name :P, thus I
>>propose org.apache.portals.applications as the root of all portlets
>>
>>so we would have org.apache.portals.applications.demo for example
>>or org.apache.portals.applications.database (to replace the database
>>browsers under gems)
>>
>>
>>
>>
>>>I can understand why we would have 2 base packages one for
>>>jetspeed-specific
>>>and one more generic JSR-168 portlets but 5 packages is a lot :)
>>>
>>>
>>>
>>yes perhaps a secondary package for jetspeed administrative portlet
>>applications such as
>>
>>org.apache.jetspeed.applications.admin
>>org.apache.jetspeed.applications.palm
>>...
>>
>>
>>
>>>All in all, I think we'd get a lot of value in rationalizating the
>>>whole packages structure although I agree with Ate that doing it right
>>>is difficult.
>>>
>>>My objectives for the refactoring would be:
>>>
>>>- packages should not be shared between components, except one "util"
>>> package for generally useful code not tied to any Jetspeed
>>>
>>>
>>fonctionality
>>
>>
>>>- it should be possible by looking at the package to know if a class is
>>>part of the Jetspeed API, Portal implementation, Portlets or stand-alone
>>>component.
>>>
>>>- if possible, components should have all the classes rooted in a single
>>> package, although they may define sub-packages from there as they wish
>>>
>>>- components and portlets should follow predictable "patterns" of
>>>
>>>
>>package
>>
>>
>>> naming conventions.
>>>
>>>Would you agree with objectives or would add/remove some of these ?
>>>
>>>
>>>
>>>
>>i agree
>>
>>--
>>David Sean Taylor
>>Bluesunrise Software
>>david@bluesunrise.com
>>[office] +01 707 773-4646
>>[mobile] +01 707 529 9194
>>
>>---------------------------------------------------------------------
>>To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
>>For additional commands, e-mail: jetspeed-dev-help@portals.apache.org
>>
>>
>
>
>
>---------------------------------------------------------------------
>To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
>For additional commands, e-mail: jetspeed-dev-help@portals.apache.org
>
>
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org
RE: Jetspeed 2 java packages structure (Re: Jetspeed 2 M4 focus: Documentation !)
Posted by Scott T Weaver <sc...@binary-designs.net>.
I think another question we might want to ask ourselves is "Does having all
the individual sub-projects really have any true benefits?" I know
initially this was to show lines between the different components. However,
this can be accomplished with good documentation and naming standards.
Also, moving things into a smaller number of subprojects would *GREATLY*
simplify our build scripts which, IMOHO, have gotten way out of control to
the point that synchronizing the Jetspeed 2 plugin with the actual build
process has become an incredibly painful task.
This is just a quick suggestion of a new structure:
|--commons* (no change)
|
|--jetspeed-api* (no change, possibly renamed to just plain, old "api")
|
|--components* (All component implementations currently in separate
| subprojects would go here)
|
|--engine* (All engine/container/pipeline stuff goes here)
|
|--management (All Jetspeed 2 specific management apps and portlets live
| here)
|
|--deployment* (Since the deployment system is somewhat complex, it gets
| its own subproject. I left it out of management as
| management should be an optional build requirement
| but deployment is mandatory.)
|
|--demos (All demo applications/portlets)
|
|--plugins (Maven plugin goes here along IDE-specific plugins.)
* Signifies mandatory subproject for a minimal working build
I left out all the bridges' api pieces as they will be moving into their own
project.
This leaves the random bits and pieces that are in the portal subproject,
which we could iron out as we refactor. Please point out anything I missed
and feel free to modify/suggest changes to the structure.
Flame away,
-Scott
> -----Original Message-----
> From: David Sean Taylor [mailto:david@bluesunrise.com]
> Sent: Tuesday, June 07, 2005 3:15 AM
> To: Jetspeed Developers List
> Subject: Re: Jetspeed 2 java packages structure (Re: Jetspeed 2 M4 focus:
> Documentation !)
>
> Raphaël Luta wrote:
> > David Sean Taylor wrote:
> >> Is that along the lines you are proposing?
> >>
> >
> > I didn't have any definite structure in mind and just wanted to start
> > the thread, I just know what I don't like: that separate "physical"
> > package share the same java namespace.
> >
> > Example:
> >
> > - jetspeed-api has some classes for org.apache.jetspeed.page.document
> > but components/page-manager defines some classes there too.
>
> I agree with Ate that we should move all impls into impl directories
>
> >
> > - org.apache.jetspeed.security.impl is shared between portal
> > and components/security
> >
> yup we have a few of those with the core valves
> Somehow the valves got moved out of the valve directory structure,
> although it didn't start that way. Maybe we should move all valve impls
> back to org.apache.jetspeed.portal.valves.impl
>
> > - in the applications directory, we have sometimes
> > org.apache.portals.applications, sometimes org.apache.jetspeed.portlets,
> > org.apache.jetspeed.demo, org.apache.jetspeed.portlet,
> > org.apache.portals.gems (not including the iBatis and Struts code)
> >
> a lot of the demo portlets are early tests that could probably be either
> cleaned up or thrown away. Since Gems got voted out of Apache, we can
> drop that package. Also, Portals Applications was also voted out (much
> to my dissappointment), but i still like the package name :P, thus I
> propose org.apache.portals.applications as the root of all portlets
>
> so we would have org.apache.portals.applications.demo for example
> or org.apache.portals.applications.database (to replace the database
> browsers under gems)
>
>
> > I can understand why we would have 2 base packages one for
> > jetspeed-specific
> > and one more generic JSR-168 portlets but 5 packages is a lot :)
> >
>
> yes perhaps a secondary package for jetspeed administrative portlet
> applications such as
>
> org.apache.jetspeed.applications.admin
> org.apache.jetspeed.applications.palm
> ...
>
> > All in all, I think we'd get a lot of value in rationalizating the
> > whole packages structure although I agree with Ate that doing it right
> > is difficult.
> >
> > My objectives for the refactoring would be:
> >
> > - packages should not be shared between components, except one "util"
> > package for generally useful code not tied to any Jetspeed
> fonctionality
> >
> > - it should be possible by looking at the package to know if a class is
> > part of the Jetspeed API, Portal implementation, Portlets or stand-alone
> > component.
> >
> > - if possible, components should have all the classes rooted in a single
> > package, although they may define sub-packages from there as they wish
> >
> > - components and portlets should follow predictable "patterns" of
> package
> > naming conventions.
> >
> > Would you agree with objectives or would add/remove some of these ?
> >
> >
> i agree
>
> --
> David Sean Taylor
> Bluesunrise Software
> david@bluesunrise.com
> [office] +01 707 773-4646
> [mobile] +01 707 529 9194
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
> For additional commands, e-mail: jetspeed-dev-help@portals.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org
Re: Jetspeed 2 java packages structure (Re: Jetspeed 2 M4 focus:
Documentation !)
Posted by David Sean Taylor <da...@bluesunrise.com>.
Raphaël Luta wrote:
> David Sean Taylor wrote:
>> Is that along the lines you are proposing?
>>
>
> I didn't have any definite structure in mind and just wanted to start
> the thread, I just know what I don't like: that separate "physical"
> package share the same java namespace.
>
> Example:
>
> - jetspeed-api has some classes for org.apache.jetspeed.page.document
> but components/page-manager defines some classes there too.
I agree with Ate that we should move all impls into impl directories
>
> - org.apache.jetspeed.security.impl is shared between portal
> and components/security
>
yup we have a few of those with the core valves
Somehow the valves got moved out of the valve directory structure,
although it didn't start that way. Maybe we should move all valve impls
back to org.apache.jetspeed.portal.valves.impl
> - in the applications directory, we have sometimes
> org.apache.portals.applications, sometimes org.apache.jetspeed.portlets,
> org.apache.jetspeed.demo, org.apache.jetspeed.portlet,
> org.apache.portals.gems (not including the iBatis and Struts code)
>
a lot of the demo portlets are early tests that could probably be either
cleaned up or thrown away. Since Gems got voted out of Apache, we can
drop that package. Also, Portals Applications was also voted out (much
to my dissappointment), but i still like the package name :P, thus I
propose org.apache.portals.applications as the root of all portlets
so we would have org.apache.portals.applications.demo for example
or org.apache.portals.applications.database (to replace the database
browsers under gems)
> I can understand why we would have 2 base packages one for
> jetspeed-specific
> and one more generic JSR-168 portlets but 5 packages is a lot :)
>
yes perhaps a secondary package for jetspeed administrative portlet
applications such as
org.apache.jetspeed.applications.admin
org.apache.jetspeed.applications.palm
...
> All in all, I think we'd get a lot of value in rationalizating the
> whole packages structure although I agree with Ate that doing it right
> is difficult.
>
> My objectives for the refactoring would be:
>
> - packages should not be shared between components, except one "util"
> package for generally useful code not tied to any Jetspeed fonctionality
>
> - it should be possible by looking at the package to know if a class is
> part of the Jetspeed API, Portal implementation, Portlets or stand-alone
> component.
>
> - if possible, components should have all the classes rooted in a single
> package, although they may define sub-packages from there as they wish
>
> - components and portlets should follow predictable "patterns" of package
> naming conventions.
>
> Would you agree with objectives or would add/remove some of these ?
>
>
i agree
--
David Sean Taylor
Bluesunrise Software
david@bluesunrise.com
[office] +01 707 773-4646
[mobile] +01 707 529 9194
---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org
Re: Jetspeed 2 java packages structure (Re: Jetspeed 2 M4 focus:
Documentation !)
Posted by Ate Douma <at...@douma.nu>.
David Sean Taylor wrote:
> Ate Douma wrote:
>
>>
>> +1
>> But, I don't like to see an artificial package name like 'api'. I much
>> prefer the commonly used separation and distinction of
>> core/implementation packages using an
>> impl subpackage.
>> And the same rule should apply for distinction of interfaces and
>> implementations:
>> if an Class is an implementation of an interface we should postfix it
>> with Impl.
>
>
> yes, i don't like api in the package path either
>
>>
>> A special case may be interfaces defined in the core (portal subproject).
>> Should these (all) be moved to jetspeed-api?
>
>
> not if they aren't meant to be public
> otherwise they can remain under impl
>
>> I would not be very much in favor as it would require exposure of
>> core/implementation
>> specific api. These interfaces are not meant to be used by
>> Portal/Portlet users/developers
>> but by integrators needing to configure/adapt the Jetspeed core
>> features itself.
>> On the other hand, there are maybe some which are quite independent
>> and as such could be
>> moved into jetspeed-api.
>>
> well, yes, if we find them to be public apis, then move them
>
>>
>> To get more to the point, do you only want to "cleanup", remove some
>> package mix ups between
>> different components/core or do you (also) want to define a more
>> strict separation of the
>> (type of) packages?
>> Something like a restricted set of root packages as below:
>> o.a.j.portal.
>> o.a.j.container.
>> o.a.j.components.
>> o.a.j.portlets.
>> o.a.j.applications.
>
>
> would o.a.j.portlets be for reusable portlets that are not a part of any
> application?
Yes, that was what I had in mind: shared/common (base) portlets and portlet utilities maybe.
Stuff like inter-portlet communications might also have to end up there.
Somewhere under Portal Bridges might also be possible although that doesn't "sound" right.
Those kinds of features (J2 agnostic) really don't have a home yet...
>
>
>> o.a.j.utils.
>> o.a.j.tools. (e.g. deployer)
>>
> overall +1, although see my comments on org.apache.portals.applications
> in my response to Raphael
>
>> In my opinion, the above separation would be a great improvement but
>> also touch almost every
>> class in the whole codebase and an awfull lot of work ...
>>
>> Although I think I would be in favor of this too, I can imagine some
>> will be strongly against it because then almost all custom
>> enhancements / integrations will have to be modified as result of it.
>> But, if we would "like" to do this: not doing it now probably means
>> never doing it...
>>
> All my current installations/integrations run against milestone builds.
> Shouldn't be too much trouble ...
> Im +1 for the refactoring, although I'd like to have a close look at the
> main refactoring of org.apache.jetspeed.portal and
> org.apache.jetspeed.container
>
> Regards,
>
---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org
Re: Jetspeed 2 java packages structure (Re: Jetspeed 2 M4 focus:
Documentation !)
Posted by David Sean Taylor <da...@bluesunrise.com>.
Ate Douma wrote:
>
> +1
> But, I don't like to see an artificial package name like 'api'. I much
> prefer the commonly used separation and distinction of
> core/implementation packages using an
> impl subpackage.
> And the same rule should apply for distinction of interfaces and
> implementations:
> if an Class is an implementation of an interface we should postfix it
> with Impl.
yes, i don't like api in the package path either
>
> A special case may be interfaces defined in the core (portal subproject).
> Should these (all) be moved to jetspeed-api?
not if they aren't meant to be public
otherwise they can remain under impl
> I would not be very much in favor as it would require exposure of
> core/implementation
> specific api. These interfaces are not meant to be used by
> Portal/Portlet users/developers
> but by integrators needing to configure/adapt the Jetspeed core features
> itself.
> On the other hand, there are maybe some which are quite independent and
> as such could be
> moved into jetspeed-api.
>
well, yes, if we find them to be public apis, then move them
>
> To get more to the point, do you only want to "cleanup", remove some
> package mix ups between
> different components/core or do you (also) want to define a more strict
> separation of the
> (type of) packages?
> Something like a restricted set of root packages as below:
> o.a.j.portal.
> o.a.j.container.
> o.a.j.components.
> o.a.j.portlets.
> o.a.j.applications.
would o.a.j.portlets be for reusable portlets that are not a part of any
application?
> o.a.j.utils.
> o.a.j.tools. (e.g. deployer)
>
overall +1, although see my comments on org.apache.portals.applications
in my response to Raphael
> In my opinion, the above separation would be a great improvement but
> also touch almost every
> class in the whole codebase and an awfull lot of work ...
>
> Although I think I would be in favor of this too, I can imagine some
> will be strongly against it because then almost all custom enhancements
> / integrations will have to be modified as result of it.
> But, if we would "like" to do this: not doing it now probably means
> never doing it...
>
All my current installations/integrations run against milestone builds.
Shouldn't be too much trouble ...
Im +1 for the refactoring, although I'd like to have a close look at the
main refactoring of org.apache.jetspeed.portal and
org.apache.jetspeed.container
Regards,
--
David Sean Taylor
Bluesunrise Software
david@bluesunrise.com
[office] +01 707 773-4646
[mobile] +01 707 529 9194
---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org
Re: Jetspeed 2 java packages structure (Re: Jetspeed 2 M4 focus:
Documentation !)
Posted by Ate Douma <at...@douma.nu>.
Raphaël Luta wrote:
> David Sean Taylor wrote:
>
>> Raphaël Luta wrote:
>
> > <snip>
>
>>
>>> #2 Start a thread on how to manage our java packages and adopt a
>>> clear package
>>> naming policy for the different main code blocks:
>>> - jetspeed-api
>>> - jetspeed engine core components
>>> - jetspeed engine optional components
>>> - application level code (admin stuff, portlet stuff, etc...)
>>> - generic utility code
>>>
>> So if I understand correctly, you are proposing that if a class is in
>> the api, say
>>
>> org.apache.jetspeed.aggregator.Aggregator
>>
>> change to:
>>
>> org.apache.jetspeed.api.aggregator.Aggregator
>>
>> another example, in the portal directory, we have
>>
>> org.apache.jetspeed.aggregator.impl.PageAggregatorImpl
>>
>> change to:
>>
>> org.apache.jetspeed.core.aggregator.impl.PageAggregatorImpl
>>
>> final example, in the components/capability directory:
>>
>> org.apache.jetspeed.capabilities.impl.CapabilityImpl
>>
>> change to:
>>
>> org.apache.jetspeed.components.capabilities.impl.CapabilityImpl
>>
>> Is that along the lines you are proposing?
>>
>
> I didn't have any definite structure in mind and just wanted to start
> the thread, I just know what I don't like: that separate "physical"
> package share the same java namespace.
>
> Example:
>
> - jetspeed-api has some classes for org.apache.jetspeed.page.document
> but components/page-manager defines some classes there too.
>
> - org.apache.jetspeed.security.impl is shared between portal
> and components/security
>
> - in the applications directory, we have sometimes
> org.apache.portals.applications, sometimes org.apache.jetspeed.portlets,
> org.apache.jetspeed.demo, org.apache.jetspeed.portlet,
> org.apache.portals.gems (not including the iBatis and Struts code)
>
> I can understand why we would have 2 base packages one for
> jetspeed-specific
> and one more generic JSR-168 portlets but 5 packages is a lot :)
>
> All in all, I think we'd get a lot of value in rationalizating the
> whole packages structure although I agree with Ate that doing it right
> is difficult.
>
> My objectives for the refactoring would be:
>
> - packages should not be shared between components, except one "util"
> package for generally useful code not tied to any Jetspeed fonctionality
+1
>
> - it should be possible by looking at the package to know if a class is
> part of the Jetspeed API, Portal implementation, Portlets or stand-alone
> component.
+1
But, I don't like to see an artificial package name like 'api'. I much
prefer the commonly used separation and distinction of core/implementation packages using an
impl subpackage.
And the same rule should apply for distinction of interfaces and implementations:
if an Class is an implementation of an interface we should postfix it with Impl.
A special case may be interfaces defined in the core (portal subproject).
Should these (all) be moved to jetspeed-api?
I would not be very much in favor as it would require exposure of core/implementation
specific api. These interfaces are not meant to be used by Portal/Portlet users/developers
but by integrators needing to configure/adapt the Jetspeed core features itself.
On the other hand, there are maybe some which are quite independent and as such could be
moved into jetspeed-api.
>
> - if possible, components should have all the classes rooted in a single
> package, although they may define sub-packages from there as they wish
+1
>
> - components and portlets should follow predictable "patterns" of package
> naming conventions.
+1
(also see my comment above)
>
> Would you agree with objectives or would add/remove some of these ?
To get more to the point, do you only want to "cleanup", remove some package mix ups between
different components/core or do you (also) want to define a more strict separation of the
(type of) packages?
Something like a restricted set of root packages as below:
o.a.j.portal.
o.a.j.container.
o.a.j.components.
o.a.j.portlets.
o.a.j.applications.
o.a.j.utils.
o.a.j.tools. (e.g. deployer)
In my opinion, the above separation would be a great improvement but also touch almost every
class in the whole codebase and an awfull lot of work ...
Although I think I would be in favor of this too, I can imagine some will be strongly against it
because then almost all custom enhancements / integrations will have to be modified as result of it.
But, if we would "like" to do this: not doing it now probably means never doing it...
Ate
---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org
Jetspeed 2 java packages structure (Re: Jetspeed 2 M4 focus: Documentation
!)
Posted by Raphaël Luta <ra...@apache.org>.
David Sean Taylor wrote:
> Raphaël Luta wrote:
> <snip>
>
>> #2 Start a thread on how to manage our java packages and adopt a clear
>> package
>> naming policy for the different main code blocks:
>> - jetspeed-api
>> - jetspeed engine core components
>> - jetspeed engine optional components
>> - application level code (admin stuff, portlet stuff, etc...)
>> - generic utility code
>>
> So if I understand correctly, you are proposing that if a class is in
> the api, say
>
> org.apache.jetspeed.aggregator.Aggregator
>
> change to:
>
> org.apache.jetspeed.api.aggregator.Aggregator
>
> another example, in the portal directory, we have
>
> org.apache.jetspeed.aggregator.impl.PageAggregatorImpl
>
> change to:
>
> org.apache.jetspeed.core.aggregator.impl.PageAggregatorImpl
>
> final example, in the components/capability directory:
>
> org.apache.jetspeed.capabilities.impl.CapabilityImpl
>
> change to:
>
> org.apache.jetspeed.components.capabilities.impl.CapabilityImpl
>
> Is that along the lines you are proposing?
>
I didn't have any definite structure in mind and just wanted to start
the thread, I just know what I don't like: that separate "physical"
package share the same java namespace.
Example:
- jetspeed-api has some classes for org.apache.jetspeed.page.document
but components/page-manager defines some classes there too.
- org.apache.jetspeed.security.impl is shared between portal
and components/security
- in the applications directory, we have sometimes
org.apache.portals.applications, sometimes org.apache.jetspeed.portlets,
org.apache.jetspeed.demo, org.apache.jetspeed.portlet,
org.apache.portals.gems (not including the iBatis and Struts code)
I can understand why we would have 2 base packages one for jetspeed-specific
and one more generic JSR-168 portlets but 5 packages is a lot :)
All in all, I think we'd get a lot of value in rationalizating the
whole packages structure although I agree with Ate that doing it right
is difficult.
My objectives for the refactoring would be:
- packages should not be shared between components, except one "util"
package for generally useful code not tied to any Jetspeed fonctionality
- it should be possible by looking at the package to know if a class is
part of the Jetspeed API, Portal implementation, Portlets or stand-alone component.
- if possible, components should have all the classes rooted in a single
package, although they may define sub-packages from there as they wish
- components and portlets should follow predictable "patterns" of package
naming conventions.
Would you agree with objectives or would add/remove some of these ?
--
Raphaël Luta - raphael@apache.org
Apache Portals - Enterprise Portal in Java
http://portals.apache.org/
---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org
Re: Jetspeed 2 M4 focus: Documentation !
Posted by Martin Dulisch <md...@gmail.com>.
2005/6/3, David Sean Taylor <da...@bluesunrise.com>:
>
> > #4 Rework the user documentation and developer design docs or HOWTO
> > Update and reorganize the existing design-docs, move to forrest
> >
>
> What about the Maven generated docs, can that be included in Forrest?
> Could you send us a link to an Apache project using Forrest as an example?
>
Many apache projects are using forrest. Have a look here:
http://forrest.apache.org/0.7/live-sites.html
Forrest uses xml as the source format for docs. So I think not the
maven generated docs could be included but the xml sources.
Martin
---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org
Re: Jetspeed 2 M4 focus: Documentation !
Posted by David Sean Taylor <da...@bluesunrise.com>.
Raphaël Luta wrote:
>
> How:
> ----
> Providing there's approval within the community for this drive, I
> propose that
> we tackle it in this order :
>
> #1 Move to SVN.
> This will make any refactoring/repackaging much easier.
>
+1
> #2 Start a thread on how to manage our java packages and adopt a clear
> package
> naming policy for the different main code blocks:
> - jetspeed-api
> - jetspeed engine core components
> - jetspeed engine optional components
> - application level code (admin stuff, portlet stuff, etc...)
> - generic utility code
>
So if I understand correctly, you are proposing that if a class is in
the api, say
org.apache.jetspeed.aggregator.Aggregator
change to:
org.apache.jetspeed.api.aggregator.Aggregator
another example, in the portal directory, we have
org.apache.jetspeed.aggregator.impl.PageAggregatorImpl
change to:
org.apache.jetspeed.core.aggregator.impl.PageAggregatorImpl
final example, in the components/capability directory:
org.apache.jetspeed.capabilities.impl.CapabilityImpl
change to:
org.apache.jetspeed.components.capabilities.impl.CapabilityImpl
Is that along the lines you are proposing?
> #3 Update Javadocs and assembly files as soon as possibly :
> - if possible go through all the different classes and document them
> at least
> at a basic level of details
> - at the very least, whenever working on a class make sure to comment
> this
> class before committing
>
Thats a lot of work, but yes, it must be done.
I think you will find that many classes are already well documented.
> #4 Rework the user documentation and developer design docs or HOWTO
> Update and reorganize the existing design-docs, move to forrest
>
What about the Maven generated docs, can that be included in Forrest?
Could you send us a link to an Apache project using Forrest as an example?
> Task #1 is underway
> Task #2 should be approached as a group and I think will be pretty easy
> to so thaks to IDE power.
> Task #3 really requires the active collaboration of everybody
> knowledgeable with
> the code
> I volunteer to drive #4 and complete the forrest site I've started.
>
Im glad to help on all of these tasks and agree the docs are very much
lacking.
--
David Sean Taylor
Bluesunrise Software
david@bluesunrise.com
[office] +01 707 773-4646
[mobile] +01 707 529 9194
---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org
RE: Jetspeed 2 M4 focus: Documentation !
Posted by Scott T Weaver <sc...@binary-designs.net>.
Raphaël,
I started component docs here,
http://wiki.apache.org/portals/Jetspeed2/PluggableEngineComponents, sometime
ago. Unfortunately, they are quite out of date :(
I agree 110% the documentation should be our focus now. I don't think any
of us will disagree that it is severely lacking. However, I know Randy
Watler has provided some excellent high-level docs on the refactoring of
navigation.
Regards,
Scott
> -----Original Message-----
> From: Raphaël Luta [mailto:raphael@apache.org]
> Sent: Friday, June 03, 2005 5:24 AM
> To: jetspeed-dev@portals.apache.org
> Subject: Jetspeed 2 M4 focus: Documentation !
>
> What:
> -----
> I'd like to propose a specific focus sor the upcoming M4 release:
> improving the
> documentation available on jetspeed 2 and possibly reorganise the
> repository to
> make it easier for new developpers (or returning developpers like me :) to
> get
> into the code.
>
> Why:
> ----
> - Every time I talk of J2 to external developers (integrators, and
> such...)
> complexity and lack of documentation is the top 1 grief when they have
> looked
> at using J2.
> - I'm developping a new feature right now (PagePreference) and I'm losing
> a
> *ridiculous* amount of time trying to understand how the stuff is
> organized
> and how everything interacts:
> - many classes have no javadocs explaining what this class is about
> - the java package structure is seemingly unrelated to the "physical"
> packaging, so it's basically just looking at a class name to know
> where
> it's located (jetspeed-api, commons, components, demo, etc..),
> against
> losing way too much energy trying to navigate.
> - the Spring assembly conf files are (mostly) undocumented
>
> If I'm feeling such a pain, I can really sympathize with an external
> portal
> integrator developers building on top of J2 and trying to get some results
> fast.
>
> How:
> ----
> Providing there's approval within the community for this drive, I propose
> that
> we tackle it in this order :
>
> #1 Move to SVN.
> This will make any refactoring/repackaging much easier.
>
> #2 Start a thread on how to manage our java packages and adopt a clear
> package
> naming policy for the different main code blocks:
> - jetspeed-api
> - jetspeed engine core components
> - jetspeed engine optional components
> - application level code (admin stuff, portlet stuff, etc...)
> - generic utility code
>
> #3 Update Javadocs and assembly files as soon as possibly :
> - if possible go through all the different classes and document them at
> least
> at a basic level of details
> - at the very least, whenever working on a class make sure to comment
> this
> class before committing
>
> #4 Rework the user documentation and developer design docs or HOWTO
> Update and reorganize the existing design-docs, move to forrest
>
> Task #1 is underway
> Task #2 should be approached as a group and I think will be pretty easy to
> so
> thaks to IDE power.
> Task #3 really requires the active collaboration of everybody
> knowledgeable with
> the code
> I volunteer to drive #4 and complete the forrest site I've started.
>
> --
> Raphaël Luta - raphael@apache.org
> Apache Portals - Enterprise Portal in Java
> http://portals.apache.org/
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
> For additional commands, e-mail: jetspeed-dev-help@portals.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org
RE: Jetspeed 2 M4 focus: Documentation !
Posted by Shah Amit <am...@hotmail.com>.
Hi all,
I am no expert on this one so please disregard if you find my comments
ridiculous !!! But regarding suggestion #4, I have a suggestion !!!!
I know that usually opensource projects lack in documentation and I can
understand why. Lot of times, the documentation that is there is in form of
random bits and pieces, and there is no "flow" saying learn this first, then
learn this second, then learn this third etc. etc. Due to this atleast I
have faced problems jumping back and forth around the documentation.
If there is a documentation that kind of flows --
Just one link that says Documentation and then like a chapter 1, chapter 2
etc. it would really be sweet !!!
Thanks,
Amit
----Original Message Follows----
From: Raphaël Luta <ra...@apache.org>
Reply-To: "Jetspeed Developers List" <je...@portals.apache.org>
To: jetspeed-dev@portals.apache.org
Subject: Jetspeed 2 M4 focus: Documentation !
Date: Fri, 03 Jun 2005 11:24:13 +0200
What:
-----
I'd like to propose a specific focus sor the upcoming M4 release: improving
the documentation available on jetspeed 2 and possibly reorganise the
repository to
make it easier for new developpers (or returning developpers like me :) to
get
into the code.
Why:
----
- Every time I talk of J2 to external developers (integrators, and such...)
complexity and lack of documentation is the top 1 grief when they have
looked
at using J2.
- I'm developping a new feature right now (PagePreference) and I'm losing a
*ridiculous* amount of time trying to understand how the stuff is organized
and how everything interacts:
- many classes have no javadocs explaining what this class is about
- the java package structure is seemingly unrelated to the "physical"
packaging, so it's basically just looking at a class name to know where
it's located (jetspeed-api, commons, components, demo, etc..), against
losing way too much energy trying to navigate.
- the Spring assembly conf files are (mostly) undocumented
If I'm feeling such a pain, I can really sympathize with an external portal
integrator developers building on top of J2 and trying to get some results
fast.
How:
----
Providing there's approval within the community for this drive, I propose
that
we tackle it in this order :
#1 Move to SVN.
This will make any refactoring/repackaging much easier.
#2 Start a thread on how to manage our java packages and adopt a clear
package
naming policy for the different main code blocks:
- jetspeed-api
- jetspeed engine core components
- jetspeed engine optional components
- application level code (admin stuff, portlet stuff, etc...)
- generic utility code
#3 Update Javadocs and assembly files as soon as possibly :
- if possible go through all the different classes and document them at
least
at a basic level of details
- at the very least, whenever working on a class make sure to comment
this
class before committing
#4 Rework the user documentation and developer design docs or HOWTO
Update and reorganize the existing design-docs, move to forrest
Task #1 is underway
Task #2 should be approached as a group and I think will be pretty easy to
so thaks to IDE power.
Task #3 really requires the active collaboration of everybody knowledgeable
with
the code
I volunteer to drive #4 and complete the forrest site I've started.
--
Raphaël Luta - raphael@apache.org
Apache Portals - Enterprise Portal in Java
http://portals.apache.org/
---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org