Project.xml globalisation

[unibrew]

Dear All :-)

I would like to propose our new project.xml structure. So, please go through it and check if everything we need is there, if there are no mistakes etc. It is important to consider this carefully because later changes might be paintful for us while doing migration and for our users. This is example of our project.xml structure now: http://labs.jboss.com/wiki/ProjectTemplate/file:project.xml
And this is how it will be:

<project>
 <id>jbosswiki</id>
 <name>JBoss Wiki</name>
 <company-name>The JBoss Labs Team</company-name>
 <logo>images/JBossWikiLogoMedium.gif</logo>
 <description>freezone/ProjectsMainPage.html</description>
 <jems>as</jems>
 <jems>tomcat</jems>
 <jems>portal</jems>
 <page>wiki</page>
 <page>blog</page>
 <page>downloads</page>
 <outside-link>
 <id>http://www.jboss.com/index.html?module=bb&op=viewforum&f=224</id>
 <name>JBoss Wiki Forum</name>
 </outside-link>
 <outside-link>
 <id>http://jira.jboss.com/jira/browse/JBWIKI</id>
 <name>JIRA Project</name>
 </outside-link>
 <outside-link>
 <id>http://labs.jboss.com/file-access/default/members/jbosswiki/freezone/docs/index.html</id>
 <name>Javadocs</name>
 </outside-link>
 <jira-adress>http://jira.jboss.com/jira/browse/JBWIKI</jira-adress>
 <svn-repo>http://anonsvn.labs.jboss.com/trunk/forge/portal-extensions/jbosswiki/</svn-repo>

This is content which already is supported by our project.xml, the only change in it is description tag. Now there will be just link to freezone, earlier there was(is) html content of project's main page.[/url]

Now the new features:

<fisheye>http://fisheye.jboss.com/jbosswiki</fisheye>
 <web-install>downloads/VickyInstaller</web-install>
 <cvs-repo>http://cvs.jboss.com/jbosswiki</cvs-repo>
 <view-cvs>http://viewcvs.jboss.com/jbosswiki</view-cvs>
 <docs>docs</docs>
 <wiki>http://labs.jboss.com/file-access/default/members/jbosswiki/freezone/docs/index.html</wiki>
 <user-forum>http://JBossForums.jboss.com/index.jsf?f=1</user-forum>
 <dev-forum>http://JBossForums.jboss.com/forums_body.jsf?f=2</dev-forum>

Did I forget something? What should be inside of DOCS tag? outside-link, link, nothing?

Next part of project.xml will be downloads with download counters. Our present downloads descriptor you can see here: http://labs.jboss.com/wiki/ProjectDownloads. Merging it into project.xml means that we will no longer have download.xml-s in download's subcategories. Everything must be in one file. So here is the proposition:

<downloads>

 <!-- SUBCATEGORIES -->
 <categories>
 <category>
 <id>Id of the subcategory = name of the subdirectory</id>
 <name>Screen name</name>
 <description>Description</description>
 <files visible="TRUE|false" order="asc|ascending|desc|descending|RANDOM" >
 <file visible="TRUE|false">
 <id>Name of the file</id>
 <name>Screen name of the file</name>
 <description>Description of the file</description>
 <size>Size of the file</size>
 <license>(LGPL, GPL, etc.).</license>
 <release>Release Alpha Beta Gamma</release>
 <button>
 <id>link</id>
 <name>Display name of the button.</name>
 <freezone>true|false</freezone>
 </button>
 </file>
 </files>
 <category>
 <!-- LIKE ABOVE -->
 </category>
 </category>
 </categories>

 <!-- ROOT CATEGORY -->
 <name>Name of the root category</name>
 <description>Description of the root category</description>

 <!-- COUNTERS' SETTINGS INHERITED BY SUBCATEGORIES UNLESS OVERRIDED -->
 <counters>
 <visible>TRUE|false</visible>
 <sort-order>asc|ascending|desc|descending|RANDOM</sort-order>
 </counters>

 <files visible="TRUE|false" order="asc|ascending|desc|descending|RANDOM" >
 <file visible="TRUE|false" >
 <id>Name of the file</id>
 <name>Screen name of the file</name>
 <description>Description of the file</description>
 <size>Size of the file</size>
 <license>(LGPL, GPL, etc.).</license>
 <release>Release Alpha Beta Gamma</release>
 <button>
 <id>link</id>
 <name>Display name of the button.</name>
 <freezone>true|false</freezone>
 </button>
 </file>
 </files>
 </downloads>

If an attribute value is written in capital letters it means that this is default setting. The tree structure of download' categories might be achieved by two solutions. One is tree structure of XML: category-in-category-in-category-like style. Or second solution where category id describes what subcategory it is by parsing it's ID e.g.: subCat1/subCat12/subcat123.

Finally, Polls. Nothing special here, just copy of what is now in poll.xml.

<polls>
 <poll>
 <question>Isn't this xml structure simple?</question>
 <answer>Yes</answer>
 <answer>No</answer>
 <answer>I don't know</answer>
 </poll>
 <poll>
 .......
 </poll>
 </polls>
</project>

All the tasks connected with this subject can be found as dependants of this task: http://jira.jboss.com/jira/browse/JBLAB-679

I'm wondering also how we will move that changes into life. How, when and who will merge the descriptors?

Cheers
-------------------------
Ryszard Kozmik
JBoss Labs Intern

[wrzep]

"unibrew" wrote:
So, please go through it and check if everything we need is there, if there are no mistakes etc. It is important to consider this carefully because later changes might be paintful for us while doing migration and for our users.

To start with, project.xml has changed a bit.

1. Repository and jira location are defined more flexible:

<repository type="svn">http://anonsvn.labs.jboss.com/labs/jbosslabs/trunk</repository>
<issue-tracker type="jira">http://jira.jboss.com/jira/browse/JBLAB</issue-tracker>

2. Navigation.

Adam is working on new, project-oriented, navigation. Now, you define project menu as following:

<menu>
 <page display="Blog">blog</page>
 <page display="Freezone">freezone</page>
 <page display="Downloads">downloads</page>
 <link display="An outside link">http://jboss.com</link>
</menu>

3. Navigation, one more time.

Hope it will be implemented soon. As repository location is already defined (see 1.), there's no use repeating it inside menu entry. Instead of:

<menu> ...
 <link display="Source Repository">http://anonsvn.labs.jboss.com/labs/jbosslabs/trunk</link>
</menu>

let's have:

<menu> ...
 <link type="repository" display="Source Repository"/>
</menu>

Obviously, same thing for the issue tracker.

So, repo location is a project attribute. Every portlet can ask for project repository. Navigation uses this to display proper link.

As you mentioned, we may want the same for:
- fisheye/viewcvs,
- dev/user forums.
(How about CruiseControl?)

Cheers :)

[wrzep]

My next question is: Why we want to move all project info into project.xml?

IMHO, there are few things to improve here, but having all information in one file might not be really handy as it will make project.xml file longer and difficult to read.

Please consider the following use cases:

1. Setting up a new project.

More sophisticated project.xml means more efforts to just add a simple project. Even if user doesn't want to have downloads page, project specific ads and pools, we should include them in the project.xml template, which makes it less readable.

2. Adding a new file to the downloads section.

Someone wants to add a file to downloads. Let him go to his project dir in the cms. downloads.xml file catches his sight and he knows where he should go to do so.
If downloads conf were inside project.xml, he will be forced to browse the file searching for place where downloads are defined.

Having all information in one file might be tempting, but, to my way of thinking, it will make project configuration more complicated. I'd suggest considering what should be defined inside project.xml and what not so that we can keep it all simple ;-)

What's your opinion?

[unibrew]

Hi

Thanks a lot for long and constructive criticism :-).

"wrzep" wrote:
1. Repository and jira location are defined more flexible:

<repository type="svn">http://anonsvn.labs.jboss.com/labs/jbosslabs/trunk</repository>
<issue-tracker type="jira">http://jira.jboss.com/jira/browse/JBLAB</issue-tracker>

Indeed, I looked now at the sources and you are right but why the wikis are not updated. I was making this post from them.

Considering navigation, cool but I don't wanna be the one rewriting all those project.xml-s to fit those and other changes ;-). (No visible wiki change too)

"wrzep" wrote:
My next question is: Why we want to move all project info into project.xml?

IMHO, there are few things to improve here, but having all information in one file might not be really handy as it will make project.xml file longer and difficult to read.

hehe, nice bolds. I must admit I felt the same when I was assigned to those tasks. Those project.xml-s might become bloaty with all this data. One of the the reasons to do this globalisation is having everything in one place so that users wouldn't have to walk around many wikis, many xml-s to define their project. However, I think our target is to have everything managable by web GUIs so I'm not sure ...

Cheers
------------------------
Ryszard Kozmik
JBoss Labs Intern

[adamw]

Hello,
as Pawe? already told you, the menu definition has changed :). And I think if we are supposed to have only one file, we should do the admin interface quickly ...

Another thing about the structure of the internal Projects class (and ProjectsDescriptor). Over time, these classes became quite messy. Projects is almost only a go-through to Project(s)Descriptor. And in ProjectDescriptor, we sometimes have to use ugly hacks to parse things like menu or repository information. So maybe it's time for a change :).

As I already wrote in reply to Adrian's post, we could make the Projects class behave like a service (though it wouldn't be a service in the JBossAS sense). Then we would not only have "Semantic Labs" but also "SOA Labs" ;-). Parts of it are there already: the Projects class enables to access things like Menu, Repository and Jira information - these are simple beans. Why not the rest should be like this? Just have projects.getProject(prjId).getInformation() would return a bean containing project id, info etc. Same for other parts - downloads for example. This would simplify things a lot.

What do you think?

[unibrew]

"adamw" wrote:
Parts of it are there already: the Projects class enables to access things like Menu, Repository and Jira information - these are simple beans. Why not the rest should be like this? Just have projects.getProject(prjId).getInformation() would return a bean containing project id, info etc. Same for other parts - downloads for example. This would simplify things a lot.

Yeah, I was going to make new things in that way but redoing old to fit this style must be done too... and will be done :-).

Thanks,
Rysiek

[adamw]

Hello,
one more thing about redoing the Projects class: now it relies on a static map that holds instances etc, not as a proper service shold look like. So, as part of service-orientating labs, maybe we could make it behave like a service - one that is also remotely accessible - Pawel already needs this, and we don't know about future uses :).

--
Cheers,
Adam

[dsicore]

What "services" are we talking about here?

[unibrew]

Hi

Adam thought about services described by @Service annotation - MBeans. I'm not sure if it is best place for using them, they have a little bit different purpose, I guess. I would rather like to use Stateless Session Bean.
Nevertheless, those services would have Local and Remote interfaces. Moreover they could serve data through WebService (I don't know what for, just an idea ;-) ).
I had discussion with Adam about his SOA idea of Labs and serving everything what is possible via services. So, there would be DownloadsService, RepositoryService, NavigationService etc. from which everyone could gain information about project.
A little bit different view of that would be making just ProjectsService which would give possibility to gain all different data about projects by giving JavaBeans-like objects DownloadsBean , RepositoryBean etc.
The question is if we want more JavaBeans or more Services ;-).
In both situations ProjectsService would be the root for gaining projects' info.

Cheers,
Rysiek

[adamw]

Hello,
of course we can access the data with SLSBs or anything else, what I meant (and wanted to achieve using the @Service annotation) is to have the XMLs and all other data parsed in the background (and only parsed when a descriptor changes) - like it is now using the cache. Of course, it's achievable with the SLSBs method too :).

I guess we have to define more precisely what we mean by a "Labs Service".

--
Cheers,
Adam

[unibrew]

Hello

Yeah, I wouldn't change a thing in the idea how projects' xml descriptors are parsed now. So, we would still use ResourceWatchers and Cache to update and keep the data gained from XMLs. The only improvement is that all this data would be served through SSB or MBeans. Information about projects will be available straight from drawed from cache objects and/or from Services(localy, remotely).

"adamw" wrote:
I guess we have to define more precisely what we mean by a "Labs Service".

Please propose some definition. What else would you like to see? :-)

Thanks in advance,
Rysiek