FileDocCategorySizeDatePackage
Specification.javaAPI DocApache Ant 1.7021801Wed Dec 13 06:16:18 GMT 2006org.apache.tools.ant.taskdefs.optional.extension

Specification

public final class Specification extends Object

Utility class that represents either an available "Optional Package" (formerly known as "Standard Extension") as described in the manifest of a JAR file, or the requirement for such an optional package.

For more information about optional packages, see the document Optional Package Versioning in the documentation bundle for your Java2 Standard Edition package, in file guide/extensions/versioning.html.

Fields Summary
private static final String
MISSING
public static final Attributes$Name
SPECIFICATION_TITLE
Manifest Attribute Name object for SPECIFICATION_TITLE.
public static final Attributes$Name
SPECIFICATION_VERSION
Manifest Attribute Name object for SPECIFICATION_VERSION.
public static final Attributes$Name
SPECIFICATION_VENDOR
Manifest Attribute Name object for SPECIFICATION_VENDOR.
public static final Attributes$Name
IMPLEMENTATION_TITLE
Manifest Attribute Name object for IMPLEMENTATION_TITLE.
public static final Attributes$Name
IMPLEMENTATION_VERSION
Manifest Attribute Name object for IMPLEMENTATION_VERSION.
public static final Attributes$Name
IMPLEMENTATION_VENDOR
Manifest Attribute Name object for IMPLEMENTATION_VENDOR.
public static final Compatibility
COMPATIBLE
Enum indicating that extension is compatible with other Package Specification.
public static final Compatibility
REQUIRE_SPECIFICATION_UPGRADE
Enum indicating that extension requires an upgrade of specification to be compatible with other Package Specification.
public static final Compatibility
REQUIRE_VENDOR_SWITCH
Enum indicating that extension requires a vendor switch to be compatible with other Package Specification.
public static final Compatibility
REQUIRE_IMPLEMENTATION_CHANGE
Enum indicating that extension requires an upgrade of implementation to be compatible with other Package Specification.
public static final Compatibility
INCOMPATIBLE
This enum indicates that an extension is incompatible with other Package Specification in ways other than other enums indicate. For example, the other Package Specification may have a different ID.
private String
specificationTitle
The name of the Package Specification.
private DeweyDecimal
specificationVersion
The version number (dotted decimal notation) of the specification to which this optional package conforms.
private String
specificationVendor
The name of the company or organization that originated the specification to which this specification conforms.
private String
implementationTitle
The title of implementation.
private String
implementationVendor
The name of the company or organization that produced this implementation of this specification.
private String
implementationVersion
The version string for implementation. The version string is opaque.
private String[]
sections
The sections of jar that the specification applies to.
Constructors Summary
public Specification(String specificationTitle, String specificationVersion, String specificationVendor, String implementationTitle, String implementationVersion, String implementationVendor)
The constructor to create Package Specification object. Note that every component is allowed to be specified but only the specificationTitle is mandatory.

param
specificationTitle the name of specification.
param
specificationVersion the specification Version.
param
specificationVendor the specification Vendor.
param
implementationTitle the title of implementation.
param
implementationVersion the implementation Version.
param
implementationVendor the implementation Vendor.

        this(specificationTitle, specificationVersion, specificationVendor,
              implementationTitle, implementationVersion, implementationVendor,
              null);
public Specification(String specificationTitle, String specificationVersion, String specificationVendor, String implementationTitle, String implementationVersion, String implementationVendor, String[] sections)
The constructor to create Package Specification object. Note that every component is allowed to be specified but only the specificationTitle is mandatory.

param
specificationTitle the name of specification.
param
specificationVersion the specification Version.
param
specificationVendor the specification Vendor.
param
implementationTitle the title of implementation.
param
implementationVersion the implementation Version.
param
implementationVendor the implementation Vendor.
param
sections the sections/packages that Specification applies to.

        this.specificationTitle = specificationTitle;
        this.specificationVendor = specificationVendor;

        if (null != specificationVersion) {
            try {
                this.specificationVersion
                    = new DeweyDecimal(specificationVersion);
            } catch (final NumberFormatException nfe) {
                final String error = "Bad specification version format '"
                    + specificationVersion + "' in '" + specificationTitle
                    + "'. (Reason: " + nfe + ")";
                throw new IllegalArgumentException(error);
            }
        }

        this.implementationTitle = implementationTitle;
        this.implementationVendor = implementationVendor;
        this.implementationVersion = implementationVersion;

        if (null == this.specificationTitle) {
            throw new NullPointerException("specificationTitle");
        }

        String[] copy = null;
        if (null != sections) {
            copy = new String[ sections.length ];
            System.arraycopy(sections, 0, copy, 0, sections.length);
        }
        this.sections = copy;
Methods Summary
public CompatibilitygetCompatibilityWith(org.apache.tools.ant.taskdefs.optional.extension.Specification other)
Return a Compatibility enum indicating the relationship of this Package Specification with the specified Extension.

param
other the other specification
return
the enum indicating the compatibility (or lack thereof) of specifed Package Specification

        // Specification Name must match
        if (!specificationTitle.equals(other.getSpecificationTitle())) {
            return INCOMPATIBLE;
        }

        // Available specification version must be >= required
        final DeweyDecimal otherSpecificationVersion
            = other.getSpecificationVersion();
        if (null != specificationVersion) {
            if (null == otherSpecificationVersion
                || !isCompatible(specificationVersion, otherSpecificationVersion)) {
                return REQUIRE_SPECIFICATION_UPGRADE;
            }
        }

        // Implementation Vendor ID must match
        final String otherImplementationVendor
            = other.getImplementationVendor();
        if (null != implementationVendor) {
            if (null == otherImplementationVendor
                || !implementationVendor.equals(otherImplementationVendor)) {
                return REQUIRE_VENDOR_SWITCH;
            }
        }

        // Implementation version must be >= required
        final String otherImplementationVersion
            = other.getImplementationVersion();
        if (null != implementationVersion) {
            if (null == otherImplementationVersion
                || !implementationVersion.equals(otherImplementationVersion)) {
                return REQUIRE_IMPLEMENTATION_CHANGE;
            }
        }

        // This available optional package satisfies the requirements
        return COMPATIBLE;
public java.lang.StringgetImplementationTitle()
Get the title of the specification.

return
the title of the specification.

        return implementationTitle;
public java.lang.StringgetImplementationVendor()
Get the vendor of the extensions implementation.

return
the vendor of the extensions implementation.

        return implementationVendor;
public java.lang.StringgetImplementationVersion()
Get the version of the implementation.

return
the version of the implementation.

        return implementationVersion;
public java.lang.String[]getSections()
Return an array containing sections to which specification applies or null if relevent to no sections.

return
an array containing sections to which specification applies or null if relevent to no sections.

        if (null == sections) {
            return null;
        }
        final String[] newSections = new String[ sections.length ];
        System.arraycopy(sections, 0, newSections, 0, sections.length);
        return newSections;
private static org.apache.tools.ant.taskdefs.optional.extension.SpecificationgetSpecification(java.lang.String section, java.util.jar.Attributes attributes)
Extract an Package Specification from Attributes.

param
attributes Attributes to searched
return
the new Specification object, or null

        //WARNING: We trim the values of all the attributes because
        //Some extension declarations are badly defined (ie have spaces
        //after version or vendor)
        final String name
            = getTrimmedString(attributes.getValue(SPECIFICATION_TITLE));
        if (null == name) {
            return null;
        }

        final String specVendor
            = getTrimmedString(attributes.getValue(SPECIFICATION_VENDOR));
        if (null == specVendor) {
            throw new ParseException(MISSING + SPECIFICATION_VENDOR, 0);
        }

        final String specVersion
            = getTrimmedString(attributes.getValue(SPECIFICATION_VERSION));
        if (null == specVersion) {
            throw new ParseException(MISSING + SPECIFICATION_VERSION, 0);
        }

        final String impTitle
            = getTrimmedString(attributes.getValue(IMPLEMENTATION_TITLE));
        if (null == impTitle) {
            throw new ParseException(MISSING + IMPLEMENTATION_TITLE, 0);
        }

        final String impVersion
            = getTrimmedString(attributes.getValue(IMPLEMENTATION_VERSION));
        if (null == impVersion) {
            throw new ParseException(MISSING + IMPLEMENTATION_VERSION, 0);
        }

        final String impVendor
            = getTrimmedString(attributes.getValue(IMPLEMENTATION_VENDOR));
        if (null == impVendor) {
            throw new ParseException(MISSING + IMPLEMENTATION_VENDOR, 0);
        }

        return new Specification(name, specVersion, specVendor,
                                  impTitle, impVersion, impVendor,
                                  new String[]{section});
public java.lang.StringgetSpecificationTitle()
Get the title of the specification.

return
the title of speciication

        return specificationTitle;
public java.lang.StringgetSpecificationVendor()
Get the vendor of the specification.

return
the vendor of the specification.

        return specificationVendor;
public DeweyDecimalgetSpecificationVersion()
Get the version of the specification.

return
the version of the specification.

        return specificationVersion;
public static org.apache.tools.ant.taskdefs.optional.extension.Specification[]getSpecifications(java.util.jar.Manifest manifest)
Return an array of Package Specification objects. If there are no such optional packages, a zero-length array is returned.

param
manifest Manifest to be parsed
return
the Package Specifications extensions in specified manifest
throws
ParseException if the attributes of the specifications cannot be parsed according to their expected formats.


                                                          
         
          
        if (null == manifest) {
            return new Specification[ 0 ];
        }

        final ArrayList results = new ArrayList();

        final Map entries = manifest.getEntries();
        final Iterator keys = entries.keySet().iterator();
        while (keys.hasNext()) {
            final String key = (String) keys.next();
            final Attributes attributes = (Attributes) entries.get(key);
            final Specification specification
                = getSpecification(key, attributes);
            if (null != specification) {
                results.add(specification);
            }
        }

        final ArrayList trimmedResults = removeDuplicates(results);
        return (Specification[]) trimmedResults.toArray(new Specification[trimmedResults.size()]);
private static java.lang.StringgetTrimmedString(java.lang.String value)
Trim the supplied string if the string is non-null

param
value the string to trim or null
return
the trimmed string or null

        return value == null ? null : value.trim();
private booleanisCompatible(DeweyDecimal first, DeweyDecimal second)
Return true if the first version number is greater than or equal to the second; otherwise return false.

param
first First version number (dotted decimal)
param
second Second version number (dotted decimal)

        return first.isGreaterThanOrEqual(second);
public booleanisCompatibleWith(org.apache.tools.ant.taskdefs.optional.extension.Specification other)
Return true if the specified package is satisfied by this Specification. Otherwise, return false.

param
other the specification
return
true if the specification is compatible with this specification

        return (COMPATIBLE == getCompatibilityWith(other));
private static booleanisEqual(org.apache.tools.ant.taskdefs.optional.extension.Specification specification, org.apache.tools.ant.taskdefs.optional.extension.Specification other)
Test if two specifications are equal except for their sections.

param
specification one specificaiton
param
other the ohter specification
return
true if two specifications are equal except for their sections, else false

        return
            specification.getSpecificationTitle().equals(other.getSpecificationTitle())
            && specification.getSpecificationVersion().isEqual(other.getSpecificationVersion())
            && specification.getSpecificationVendor().equals(other.getSpecificationVendor())
            && specification.getImplementationTitle().equals(other.getImplementationTitle())
            && specification.getImplementationVersion().equals(other.getImplementationVersion())
            && specification.getImplementationVendor().equals(other.getImplementationVendor());
private static org.apache.tools.ant.taskdefs.optional.extension.SpecificationmergeInSections(org.apache.tools.ant.taskdefs.optional.extension.Specification specification, java.util.ArrayList sectionsToAdd)
Merge the specified sections into specified section and return result. If no sections to be added then just return original specification.

param
specification the specification
param
sectionsToAdd the list of sections to merge
return
the merged specification

        if (0 == sectionsToAdd.size()) {
            return specification;
        }
        sectionsToAdd.addAll(Arrays.asList(specification.getSections()));

        final String[] sections =
            (String[]) sectionsToAdd.toArray(new String[sectionsToAdd.size()]);

        return new Specification(specification.getSpecificationTitle(),
                specification.getSpecificationVersion().toString(),
                specification.getSpecificationVendor(),
                specification.getImplementationTitle(),
                specification.getImplementationVersion(),
                specification.getImplementationVendor(),
                sections);
private static java.util.ArrayListremoveDuplicates(java.util.ArrayList list)
Combine all specifications objects that are identical except for the sections.

Note this is very inefficent and should probably be fixed in the future.

param
list the array of results to trim
return
an array list with all duplicates removed

        final ArrayList results = new ArrayList();
        final ArrayList sections = new ArrayList();
        while (list.size() > 0) {
            final Specification specification = (Specification) list.remove(0);
            final Iterator iterator = list.iterator();
            while (iterator.hasNext()) {
                final Specification other = (Specification) iterator.next();
                if (isEqual(specification, other)) {
                    final String[] otherSections = other.getSections();
                    if (null != sections) {
                        sections.addAll(Arrays.asList(otherSections));
                    }
                    iterator.remove();
                }
            }

            final Specification merged =
                mergeInSections(specification, sections);
            results.add(merged);
            //Reset list of sections
            sections.clear();
        }

        return results;
public java.lang.StringtoString()
Return a String representation of this object.

return
string representation of object.

        final String brace = ": ";

        final StringBuffer sb
            = new StringBuffer(SPECIFICATION_TITLE.toString());
        sb.append(brace);
        sb.append(specificationTitle);
        sb.append(StringUtils.LINE_SEP);

        if (null != specificationVersion) {
            sb.append(SPECIFICATION_VERSION);
            sb.append(brace);
            sb.append(specificationVersion);
            sb.append(StringUtils.LINE_SEP);
        }

        if (null != specificationVendor) {
            sb.append(SPECIFICATION_VENDOR);
            sb.append(brace);
            sb.append(specificationVendor);
            sb.append(StringUtils.LINE_SEP);
        }

        if (null != implementationTitle) {
            sb.append(IMPLEMENTATION_TITLE);
            sb.append(brace);
            sb.append(implementationTitle);
            sb.append(StringUtils.LINE_SEP);
        }

        if (null != implementationVersion) {
            sb.append(IMPLEMENTATION_VERSION);
            sb.append(brace);
            sb.append(implementationVersion);
            sb.append(StringUtils.LINE_SEP);
        }

        if (null != implementationVendor) {
            sb.append(IMPLEMENTATION_VENDOR);
            sb.append(brace);
            sb.append(implementationVendor);
            sb.append(StringUtils.LINE_SEP);
        }

        return sb.toString();