Re: Should or must Apache Portals create and maintain its own Portlet API (JSR-168/286) spec implementation?

[David Jencks]

On May 10, 2009, at 3:04 PM, Ate Douma wrote:
Hi David,

Thanks for the work on this, and especially for cleaning up the  
license headers mess :)
We're now much closer to what is needed I think, but there are still  
a few things to sort out before we can start releasing these.

First of all, I think the current groupId which is still  
javax.portlet, need to be changed to org.apache.portals.
Once that's done, we can start updating Pluto, Jetspeed and APA  
(trunks) to use our own portlet-api artifacts.
done.


Secondly, the /portals/portlet-spec/site folder should be moved to / 
portals/site/portlet-spec, where it can be cleaned up restructured  
as much as we like. But at least, by moving it from here it won't be  
in the way anymore for the planned release.

It's at portlet-specs/trunk/site now so it won't interfere with the  
release.  Moving it is probably a good idea anyway.


And thirdly, I think we need to decide about the OSGi bundle  
generation.
To be honest, I'm not very much in favor *right now* to use the  
Felix plugin for this.
As you're already detected, the result is not quite similar to what  
was produced manually (for portlet-api-2.0).
AFAIK, the manually produced OSGi meta-data *is* correct and how it  
should be.
For instance, I think the two most important OSGi tags, Bundle- 
SymbolicName and Bundle-Version, should be (and remain) java.portlet  
and 2.0 respectively, independent of our our groupId/artifactId/ 
version, as this jar (OSGi bundle) is expected to be a "drop in" for  
specifically this *spec* version.

I learned more about osgi the last couple of days :-)
bundle-symbolic-name needs to identify these bundles as different from  
the ones sun may or may not supply.  It doesn't have anything to do  
with what's inside :-)  So I think we should continue with the default  
from the maven-bundle-plugin of <groupId>.<artifactId>, here  
org.apache.portals.portlet-api_1.0_spec etc.

bundle version identities the version of the bundle, not the package  
version of anything inslde.  So I think the standard procedure is to  
start at 1.0.0.

We do need to make sure that the packages inside have version either  
2.0 or 2.0.0.  After a lot of headaches I discovered that the bundle- 
version and the versions for each exported package have nothing to do  
with one another.


To me, the Felix plugin doesn't seem to provide much added value but  
instead a higher degree of complexity and unsureness how to use it  
properly and correctly.

If we can get it to produce slightly more reasonable output by the end  
of tomorrow I think we should use it.  For instance it has pointed out  
that the packages in Export-Packages should have uses clauses, at  
least for the servlet package needed.  If no answer from feiix arrives  
by tomorrow then I agree we should use the manual manifest setup.....  
but informed by the bundle plugin output.

thanks
david jencks



With the rather critical amount of release steps coming up (portals- 
pom-1.1 -> these portlet-specs -> Pluto 2.0 -> multiple APA-1.0  
projects -> Jetspeed 2.2) which are all depending on the previous  
release step, I strongly urge everyone involved to keep the amount  
of remaining tasks to the minimum and most practical. Switching back  
to the manual OSGi bundle generation should be good enough for now  
IMO.

Once the whole of these planned releases are done and over, I have  
no objections to further investigate how to do this "right" (if  
needed) and release an update of the spec jars later on. Which is  
the whole point of now maintaining these ourselves. But lets start  
out with the minimum required to get rolling.

If nobody objects, I think we can do the above 3 steps by tomorrow  
and create a release 1.0 proposal right after portals-pom-1.1 has  
been released itself.

Regards,

Ate

David Jencks wrote:
I've been working on this, see PORTALS-14.
I updated to use the portals 1.1 pom now under vote.  I have some  
comments in that thread.
It may or may not be a good idea, but I updated the names to  
portlet-api_x.0_spec with version 1.0-SNAPSHOT for both specs.  If  
we don't like it we can change it back.
I added use of the felix bundle plugin for osgi metadata.  It is  
generating different info than the hand-supplied info previously in  
the 2.0 spec.  Here's what the bundle plugin comes up with:
Manifest-Version: 1.0
Export-Package:  
javax.portlet.filter;uses:="javax.portlet,org.w3c.dom,
javax.servlet.http,javax.xml.namespace";version="1.0.0.SNAPSHOT",java
x.portlet;uses:="org.w3c.dom,javax.servlet.http,javax.xml.namespace";
version="1.0.0.SNAPSHOT"
Implementation-Title: Java Portlet Specification V2.0
Implementation-Version: 1.0-SNAPSHOT
Tool: Bnd-0.0.227
Bundle-Name: portlet-api_2.0_spec
Created-By: 1.6.0_07 (Apple Inc.)
Bundle-Vendor: Apache Software Foundation
Bundle-Version: 1.0.0.SNAPSHOT
Bnd-LastModified: 1241824729053
Bundle-ManifestVersion: 2
Bundle-License: http://www.apache.org/licenses/LICENSE-2.0.html
Bundle-Description: The Java Portlet API version 2.0 developed by the
Java Community Process JSR-286 Expert Group.
Import-Package:  
javax.portlet;version="1.0.0.SNAPSHOT",javax.portlet.f
ilter;version="1.0.0.SNAPSHOT",javax.servlet.http,javax.xml.namespace
,org.w3c.dom
Bundle-SymbolicName: javax.portlet.portlet-api_2.0_spec
Bundle-DocURL: http://portals.apache.org/
Here's the manually constructed manifest:
Manifest-Version: 1.0
Archiver-Version: Plexus Archiver
Created-By: Apache Maven
Built-By: david
Build-Jdk: 1.6.0_07
Specification-Title: Java Portlet Specification V2.0
Specification-Version: 1.0-SNAPSHOT
Specification-Vendor: Apache Software Foundation
Implementation-Title: Java Portlet Specification V2.0
Implementation-Version: 1.0-SNAPSHOT
Implementation-Vendor-Id: javax.portlet
Implementation-Vendor: Apache Software Foundation
Bundle-DocURL: http://www.jcp.org/en/jsr/detail?id=286
Bundle-ManifestVersion: 2
Bundle-Name: JSR 286
Bundle-SymbolicName: javax.portlet
Bundle-Version: 2.0
Export-Package: javax.portlet;version="2.0.0",
                  javax.portlet.filter;version="2.0.0"
Import-Package: org.w3c.dom,
                  javax.xml.namespace,
                  javax.servlet.http; version="2.4.0"
I'm not enough of an osgi expert to completely understand these  
but..... there are some obvious problems with the felix-generated  
entries in the version of import/exports.  However at this point  
I'd like to investigate what's going on with this a bit more before  
recommending one or the other approach.
thanks
david jencks
On May 8, 2009, at 12:55 AM, Ate Douma wrote:
Hi David,

First of all, thanks again for helping out on this!

I have some inline comments below.

Regards,

Ate

David Jencks wrote:
See https://issues.apache.org/jira/browse/PORTALS-12 and 
https://issues.apache.org/jira/browse/PORTALS-13
portlet 2.0:
I removed the ibm copyrights from the source files and the  
license.txt file and added the copyright notice to the NOTICE  
file. I added the portals-pom as parent and used the maven-remote- 
resources plugin to generate the LICENSE and NOTICE files.  I  
also added the LICENSE and NOTICE files to the root of the svn  
source.
portlet 1.0:
I changed the license header from apache 1.1 to the current  
header, allowing its release post- march-2004 :-).  I also added  
the portals-pom as parent and used the maven-remote-resources  
plugin to generate the requred LICENSE and NOTICE files, and  
added these at the root of svn source.
Other stuff I think needs to happen:
1. remove the portlet.xml.txt files unless they serve some actual  
purpose.
+1, I don't see any purpose at all.
It is just an example portlet.xml which I think accidentally  
landed in the source tree.

2. in 2.0, remove the statement that the spec is provisional  
found in every file
+1

3. remove the portal-site src and pom completely, use the maven  
generated site instead for each spec level.
We have some other plans about site management for all of portals  
by moving that out of the main release cycle svn trees for each  
project and instead maintain it separately (without trunk/tags  
folders) based off /portals/site, with a master portals-site pom  
and sub projects inherit from it (but not necessarily as parent  
pom modules as maven-site plugin is too broken to deal with that  
correctly).
This does pose a problem for code based generated docs like  
reports and javadoc, but I think we can and should simply check  
those in and integrate them manually in the corresponding (sub)  
project site xdocs.
Anyway, I'll write a formal proposal/vote email for doing this for  
all Portals projects shortly, and then in more detail.

4. make the svn tree look like:
https://svn.apache.org/repos/asf/portals/portlet-spec
+tags
\trunk
  +portlet-api-1.0
  \portlet-api-2.0
+1

Somewhat to my surprise we've found this structure to work fine  
with the geronimo specs and the release plugin.
5. use the felix bundle plugin to insert osgi metadata
+0, we already do this for portlet-api-2.0 within the pom itself,  
not sure if more is needed here.
I guess Carsten might have some additional ideas about this.

6. remove just about everything from the poms and use the release  
profile instead
+1, we're about to provide a vote on an updated portals-pom-1.1  
which will use apache 6 pom

7. make the portals-pom specify use of m-r-r-plugin always.
You mean maven-remote-resources-plugin, right?
Probably +1, haven't reviewed in detail what possible side-effects  
that could have though.

8 update portals-pom to use apache 6 pom as soon as it's available.
See above, and FYI: apache 6 pom is already released and available

9. (maybe) maybe I'm biased :-) but I prefer to use geronimo  
servlet specs because I know a bit about their quality.  I'd  
rather build against the geronimo servlet 2.5 spec even though  
it's uplevel for what's needed than the 2.3 and 2.4 servlet specs  
that I don't know much about.
-1
Not all end users are using a servlet 2.5 container yet, and  
adding a dependency on that could cause problems if they  
inadvertently then would use features from that not supported in  
their runtime environment.

If everyone agrees these are good changes I think I could find  
the time to do them soon.  I'd also be happy if someone else does  
them :-)
Whoever gets there first :)
You're very welcome to help out further with this, much appreciated.

thanks
david jencks
On May 6, 2009, at 1:00 PM, Ate Douma wrote:
David Jencks wrote:
My manager thinks it's OK for me, as an IBM employee, to update  
the sources to conform with apache standards, I will try to get  
to it today or tomorrow.
Cool!

Thanks for helping out with this David.

Regards,

Ate

thanks
david jencks
On May 4, 2009, at 4:35 PM, David Jencks wrote:
Hi Ate,

I haven't heard back from my manager yet, I pinged him again.   
I think it's ok to add the apache license header for now, but  
it would definitely be better to get it fixed, especially as  
the existing license.txt file does not contain a license at all.

thanks
david jencks

On May 4, 2009, at 3:26 AM, Ate Douma wrote:

David Jencks wrote:
On Apr 18, 2009, at 1:37 PM, Ate Douma wrote:

<snip/>


In addition, there is this license.txt within the source  
tree containing the following:

� Copyright IBM Corp. 2006, 2007
All rights reserved.

Should that file remain or maybe should we move that  
statement to our NOTICE.txt instead?

Furthermore, every portlet-api-2.0 source file also  
contains the "Copyright 2006 IBM Corporation." in the header.
IIUC the recommended route is to move these copyright  
notices to the NOTICE file.  However someone from IBM has to  
do it.  I'm from IBM but right now I wouldn't be comfortable  
removing them without input from at least one author or IBM  
legal.  I'll ask my boss and see what happens.

David Jencks, do you have any feedback on this issue?
I'd like to move forward with this proposal ASAP but its a  
little unclear to me how we can and/or are allowed to proceed  
now.

I would think at least we are allowed to *add* the ASF  
licence header to the sources while (for now) retaining the  
the IBM copyright notices therein.
And the license.txt file I would think should be fine to be  
removed when we move the content to our own NOTICE file.
The remaining question for me is, should we only provide the  
standard ASF LICENSE file, or should that in addition *also*  
contain the content of the original IBM license.txt?

Thanks,

Ate



Note that none of such copyright statements are found in  
the portlet-api-1.0 source, not even from SUN.
On the other hand, the portlet-api-1.0 sources do have the  
ASF 1.1 license header, not the 2.0 license header.
I'm not too familiar with what is required when a new  
release is put out, but I think if we would do this, those  
need to be replaced with ASF 2.0 license headers now, right?
yes, and I think we can do that without any legal arguments  
from anyone.
thanks
david jencks


Regards,

Ate

Carsten