[jdom-interest] Manifest

[Ken Roberts]

On Sat, 2004-10-09 at 09:49, Elliotte Harold wrote:

> Ken Roberts wrote:
> 
> > 
> >     <!-- the old part
> >     <jar jarfile="${build.dir}/${name}.jar"
> >          basedir="${build.dest}"
> >          excludes="META-INF/MANIFEST.MF"
> >          manifest="${build.dest}/META-INF/MANIFEST.MF"/>
> >     -->
> >     <!-- the new part -->
> >     <property name="version" value="1.0"/>
> >     <property name="vendor"  value="jdom.org"/>
> >     <jar jarfile="${build.dir}/${name}.jar">
> >       <manifest>
> >         <attribute name="Built-By" value="${user.name}"/>
> >         <!--Make something for the whole jar-->
> >         <attribute name="Specification-Title"   value="JDOM Classes"/>
> >         <attribute name="Specification-Version" value="${version}"/>
> >         <attribute name="Specification-Vendor"  value="${vendor}"/>
> >         <attribute name="Implementation-Title"   value="org.jdom"/>
> >         <attribute name="Implementation-Version" value="${version}"/>
> >         <attribute name="Implementation-Vendor"  value="${vendor}"/>
> >         <!--Make something for the individual nested packages-->
> >         <section name="org/jdom/input">
> >           <attribute name="Specification-Title"   value="JDOM input 
> > classes"/>
> 
> 
> Why do you call out the individual packages separately here? Wouldn't it 
> be enough to have one batch of attributes in the main section? It's not 
> as if the individual packages are versioned separately from the main 
> release.
> 
> Also, could you please elaborate on what exactly you use these 
> attributes for and how you use them? Thanks.


Until I saw the MANIFEST.MF file distributed with jdom, I did not know
you even COULD give separate attributes for each package.  The initial
post I made builds the manifest that is distributed with the source.

The second post I made is the result of research I should have done
before the first one.  As long as you have "default" attributes you can
add just that information which changes in each package and the rest
will "trickle down."  For my personal purposes, just the default
attributes are adequate.

Now for the usefulness of this information and what I do with it:

The manifest is designed into .jar files so that the package can be
queried for version information.  It's designed to be queried by
software, so that the dependent software can find out what version of
(jdom) it has and either adjust its calls, disable or enable features or
refuse to operate altogether.

A code snippet would be as follows:

import java.lang.Package  // totally unnecessary but for clarity

public class PackageTester {
...
    Package pkg = Class.forName("org.jdom.Document").getPackage();
    if(!(pkg.isCompatibleWith("1.0") {
      throw new Exception("The JDOM module is too old to be used.");
    }
    // or
    if(pkg.getImplementationVersion().equals("1.0.3")) {
      throw new Exception("The JDOM module you used has a bug that
disables the ABC module!  Versions 1.0-1.0.2 and anything after 1.0.3
work fine.");
    // or
    if(!pkg.getImplementationVersion().equals("1.0.3")) {
      throw new Exception("This application requires version 1.0.3 of
jdom, exactly.  Any other version is untested.");

This is fairly primitive, but you can see that testing for a run/no run
situation is pretty easy.  Considering the number of software packages
that are now being used on server side, and the convoluted class paths
that can be found, it's important to know that somebody didn't drop in a
different version than you are interested in, or if you're trying to
upgrade you would want to be sure your upgrade took.

We print module versions out on the java console (server log and client
jc) on deployment and load respectively, so any error report has all
that information.

It's unfortunate that so many open source projects do not contain a
useful MANIFEST.MF in this way.  I'm trying to do my part in fixing that
in a constructive way.

FYI, the Package documentation requires that version numbers be positive
integers separated by dots, so "1.2.4" works but "1.0-rc3" throws a
NumberFormatException.

Sorry for so many long posts, and thank you for your time.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://servlets.com/pipermail/jdom-interest/attachments/20041010/015ef0ef/attachment.htm