https://ant.apache.org/: master POM (The Apache Software Foundation) 
/*
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You under the Apache License, Version 2.0
 *  (the "License"); you may not use this file except in compliance with
 *  the License.  You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 *
 */
package org.apache.tools.ant.taskdefs.optional.extension;

import java.text.ParseException;
import java.util.ArrayList;
import java.util.Collections;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.jar.Attributes;
import java.util.jar.Manifest;
import java.util.stream.Stream;

import org.apache.tools.ant.util.DeweyDecimal;


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.


/**
 * <p>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.</p>
 *
 * <p>For more information about optional packages, see the document
 * <em>Optional Package Versioning</em> in the documentation bundle for your
 * Java2 Standard Edition package, in file
 * <code>guide/extensions/versioning.html</code>.</p>
 *
 */
public final class Specification {

    private static final String MISSING = "Missing ";

    
Manifest Attribute Name object for SPECIFICATION_TITLE.

/**
     * Manifest Attribute Name object for SPECIFICATION_TITLE.
     */
    public static final Attributes.Name SPECIFICATION_TITLE
        = Attributes.Name.SPECIFICATION_TITLE;

    
Manifest Attribute Name object for SPECIFICATION_VERSION.

/**
     * Manifest Attribute Name object for SPECIFICATION_VERSION.
     */
    public static final Attributes.Name SPECIFICATION_VERSION
        = Attributes.Name.SPECIFICATION_VERSION;

    
Manifest Attribute Name object for SPECIFICATION_VENDOR.

/**
     * Manifest Attribute Name object for SPECIFICATION_VENDOR.
     */
    public static final Attributes.Name SPECIFICATION_VENDOR
        = Attributes.Name.SPECIFICATION_VENDOR;

    
Manifest Attribute Name object for IMPLEMENTATION_TITLE.

/**
     * Manifest Attribute Name object for IMPLEMENTATION_TITLE.
     */
    public static final Attributes.Name IMPLEMENTATION_TITLE
        = Attributes.Name.IMPLEMENTATION_TITLE;

    
Manifest Attribute Name object for IMPLEMENTATION_VERSION.

/**
     * Manifest Attribute Name object for IMPLEMENTATION_VERSION.
     */
    public static final Attributes.Name IMPLEMENTATION_VERSION
        = Attributes.Name.IMPLEMENTATION_VERSION;

    
Manifest Attribute Name object for IMPLEMENTATION_VENDOR.

/**
     * Manifest Attribute Name object for IMPLEMENTATION_VENDOR.
     */
    public static final Attributes.Name IMPLEMENTATION_VENDOR
        = Attributes.Name.IMPLEMENTATION_VENDOR;

    
Enum indicating that extension is compatible with other Package
Specification.

/**
     * Enum indicating that extension is compatible with other Package
     * Specification.
     */
    public static final Compatibility COMPATIBLE =
        new Compatibility("COMPATIBLE");

    
Enum indicating that extension requires an upgrade
of specification to be compatible with other Package Specification.

/**
     * Enum indicating that extension requires an upgrade
     * of specification to be compatible with other Package Specification.
     */
    public static final Compatibility REQUIRE_SPECIFICATION_UPGRADE =
        new Compatibility("REQUIRE_SPECIFICATION_UPGRADE");

    
Enum indicating that extension requires a vendor
switch to be compatible with other Package Specification.

/**
     * Enum indicating that extension requires a vendor
     * switch to be compatible with other Package Specification.
     */
    public static final Compatibility REQUIRE_VENDOR_SWITCH =
        new Compatibility("REQUIRE_VENDOR_SWITCH");

    
Enum indicating that extension requires an upgrade
of implementation to be compatible with other Package Specification.

/**
     * Enum indicating that extension requires an upgrade
     * of implementation to be compatible with other Package Specification.
     */
    public static final Compatibility REQUIRE_IMPLEMENTATION_CHANGE =
        new Compatibility("REQUIRE_IMPLEMENTATION_CHANGE");

    
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.

/**
     * 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.
     */
    public static final Compatibility INCOMPATIBLE =
        new Compatibility("INCOMPATIBLE");

    
The name of the Package Specification.

/**
     * The name of the Package Specification.
     */
    private String specificationTitle;

    
The version number (dotted decimal notation) of the specification
to which this optional package conforms.

/**
     * The version number (dotted decimal notation) of the specification
     * to which this optional package conforms.
     */
    private DeweyDecimal specificationVersion;

    
The name of the company or organization that originated the
specification to which this specification conforms.

/**
     * The name of the company or organization that originated the
     * specification to which this specification conforms.
     */
    private String specificationVendor;

    
The title of implementation.

/**
     * The title of implementation.
     */
    private String implementationTitle;

    
The name of the company or organization that produced this
implementation of this specification.

/**
     * The name of the company or organization that produced this
     * implementation of this specification.
     */
    private String implementationVendor;

    
The version string for implementation. The version string is
opaque.

/**
     * The version string for implementation. The version string is
     * opaque.
     */
    private String implementationVersion;

    
The sections of jar that the specification applies to.

/**
     * The sections of jar that the specification applies to.
     */
    private String[] sections;

    
Return an array of Package Specification objects.
If there are no such optional packages, a zero-length array is returned.

Params:
  • manifest – Manifest to be parsed
Throws:
  • ParseException – if the attributes of the specifications cannot
be parsed according to their expected formats.
Returns:the Package Specifications extensions in specified manifest
/**
     * Return an array of <code>Package Specification</code> 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.
     */
    public static Specification[] getSpecifications(final Manifest manifest)
        throws ParseException {
        if (null == manifest) {
            return new Specification[0];
        }
        final List<Specification> results = new ArrayList<>();

        for (Map.Entry<String, Attributes> e : manifest.getEntries().entrySet()) {
            Optional.ofNullable(getSpecification(e.getKey(), e.getValue()))
                .ifPresent(results::add);
        }
        return removeDuplicates(results)
            .toArray(new Specification[removeDuplicates(results).size()]);
    }

    
The constructor to create Package Specification object.
Note that every component is allowed to be specified
but only the specificationTitle is mandatory.

Params:
  • specificationTitle – the name of specification.
  • specificationVersion – the specification Version.
  • specificationVendor – the specification Vendor.
  • implementationTitle – the title of implementation.
  • implementationVersion – the implementation Version.
  • implementationVendor – the implementation Vendor.
/**
     * 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.
     */
    public Specification(final String specificationTitle,
                          final String specificationVersion,
                          final String specificationVendor,
                          final String implementationTitle,
                          final String implementationVersion,
                          final String implementationVendor) {
        this(specificationTitle, specificationVersion, specificationVendor,
              implementationTitle, implementationVersion, implementationVendor,
              null);
    }

    
The constructor to create Package Specification object.
Note that every component is allowed to be specified
but only the specificationTitle is mandatory.

Params:
  • specificationTitle – the name of specification.
  • specificationVersion – the specification Version.
  • specificationVendor – the specification Vendor.
  • implementationTitle – the title of implementation.
  • implementationVersion – the implementation Version.
  • implementationVendor – the implementation Vendor.
  • sections – the sections/packages that Specification applies to.
/**
     * 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.
     */
    public Specification(final String specificationTitle,
                          final String specificationVersion,
                          final String specificationVendor,
                          final String implementationTitle,
                          final String implementationVersion,
                          final String implementationVendor,
                          final String[] sections) {
        this.specificationTitle = specificationTitle;
        this.specificationVendor = specificationVendor;

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

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

        if (null == this.specificationTitle) {
            throw new NullPointerException("specificationTitle");
        }
        this.sections = sections == null ? null : sections.clone();
    }

    
Get the title of the specification.

Returns:the title of specification
/**
     * Get the title of the specification.
     *
     * @return the title of specification
     */
    public String getSpecificationTitle() {
        return specificationTitle;
    }

    
Get the vendor of the specification.

Returns:the vendor of the specification.
/**
     * Get the vendor of the specification.
     *
     * @return the vendor of the specification.
     */
    public String getSpecificationVendor() {
        return specificationVendor;
    }

    
Get the title of the specification.

Returns:the title of the specification.
/**
     * Get the title of the specification.
     *
     * @return the title of the specification.
     */
    public String getImplementationTitle() {
        return implementationTitle;
    }

    
Get the version of the specification.

Returns:the version of the specification.
/**
     * Get the version of the specification.
     *
     * @return the version of the specification.
     */
    public DeweyDecimal getSpecificationVersion() {
        return specificationVersion;
    }

    
Get the vendor of the extensions implementation.

Returns:the vendor of the extensions implementation.
/**
     * Get the vendor of the extensions implementation.
     *
     * @return the vendor of the extensions implementation.
     */
    public String getImplementationVendor() {
        return implementationVendor;
    }

    
Get the version of the implementation.

Returns:the version of the implementation.
/**
     * Get the version of the implementation.
     *
     * @return the version of the implementation.
     */
    public String getImplementationVersion() {
        return implementationVersion;
    }

    
Return an array containing sections to which specification applies
or null if relevant to no sections.

Returns:an array containing sections to which specification applies
        or null if relevant to no sections.
/**
     * Return an array containing sections to which specification applies
     * or null if relevant to no sections.
     *
     * @return an array containing sections to which specification applies
     *         or null if relevant to no sections.
     */
    public String[] getSections() {
        return sections == null ? null : sections.clone();
    }

    
Return a Compatibility enum indicating the relationship of this
Package Specification with the specified
Extension.

Params:
  • other – the other specification
Returns:the enum indicating the compatibility (or lack thereof)
        of specified Package Specification
/**
     * Return a Compatibility enum indicating the relationship of this
     * <code>Package Specification</code> with the specified
     * <code>Extension</code>.
     *
     * @param other the other specification
     * @return the enum indicating the compatibility (or lack thereof)
     *         of specified Package Specification
     */
    public Compatibility getCompatibilityWith(final Specification other) {
        // 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 && (null == otherSpecificationVersion
                || !isCompatible(specificationVersion, otherSpecificationVersion))) {
            return REQUIRE_SPECIFICATION_UPGRADE;
        }

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

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

        // This available optional package satisfies the requirements
        return COMPATIBLE;
    }

    
Return true if the specified package
is satisfied by this Specification. Otherwise, return
false.

Params:
  • other – the specification
Returns:true if the specification is compatible with this specification
/**
     * Return <code>true</code> if the specified <code>package</code>
     * is satisfied by this <code>Specification</code>. Otherwise, return
     * <code>false</code>.
     *
     * @param other the specification
     * @return true if the specification is compatible with this specification
     */
    public boolean isCompatibleWith(final Specification other) {
        return COMPATIBLE == getCompatibilityWith(other);
    }

    
Return a String representation of this object.

Returns:string representation of object.
/**
     * Return a String representation of this object.
     *
     * @return string representation of object.
     */
    @Override
    public String toString() {
        final String format = "%s: %s%n";

        final StringBuilder sb = new StringBuilder(String.format(format,
                SPECIFICATION_TITLE, specificationTitle));

        if (null != specificationVersion) {
            sb.append(String.format(format, SPECIFICATION_VERSION, specificationVersion));
        }

        if (null != specificationVendor) {
            sb.append(String.format(format, SPECIFICATION_VENDOR, specificationVendor));
        }

        if (null != implementationTitle) {
            sb.append(String.format(format, IMPLEMENTATION_TITLE, implementationTitle));
        }

        if (null != implementationVersion) {
            sb.append(String.format(format, IMPLEMENTATION_VERSION, implementationVersion));
        }

        if (null != implementationVendor) {
            sb.append(String.format(format, IMPLEMENTATION_VENDOR, implementationVendor));
        }

        return sb.toString();
    }

    
Return true if the first version number is greater than
or equal to the second; otherwise return false.

Params:
  • first – First version number (dotted decimal)
  • second – Second version number (dotted decimal)
/**
     * Return <code>true</code> if the first version number is greater than
     * or equal to the second; otherwise return <code>false</code>.
     *
     * @param first First version number (dotted decimal)
     * @param second Second version number (dotted decimal)
     */
    private boolean isCompatible(final DeweyDecimal first,
                                 final DeweyDecimal second) {
        return first.isGreaterThanOrEqual(second);
    }

    
Combine all specifications objects that are identical except
for the sections.

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


Params:
  • list – the array of results to trim
Returns:an array list with all duplicates removed
/**
     * Combine all specifications objects that are identical except
     * for the sections.
     *
     * <p>Note this is very inefficient and should probably be fixed
     * in the future.</p>
     *
     * @param list the array of results to trim
     * @return an array list with all duplicates removed
     */
    private static List<Specification> removeDuplicates(final List<Specification> list) {
        final List<Specification> results = new ArrayList<>();
        final List<String> sections = new ArrayList<>();
        while (!list.isEmpty()) {
            final Specification specification = list.remove(0);
            for (final Iterator<Specification> iterator =
                list.iterator(); iterator.hasNext();) {
                final Specification other = iterator.next();
                if (isEqual(specification, other)) {
                    Optional.ofNullable(other.getSections())
                        .ifPresent(s -> Collections.addAll(sections, s));
                    iterator.remove();
                }
            }
            results.add(mergeInSections(specification, sections));
            // Reset list of sections
            sections.clear();
        }
        return results;
    }

    
Test if two specifications are equal except for their sections.

Params:
  • specification – one specification
  • other – the other specification
Returns:true if two specifications are equal except for their
        sections, else false
/**
     * Test if two specifications are equal except for their sections.
     *
     * @param specification one specification
     * @param other the other specification
     * @return true if two specifications are equal except for their
     *         sections, else false
     */
    private static boolean isEqual(final Specification specification,
                                    final Specification other) {
        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());
    }

    
Merge the specified sections into specified section and return result.
If no sections to be added then just return original specification.

Params:
  • specification – the specification
  • sectionsToAdd – the list of sections to merge
Returns:the merged specification
/**
     * 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
     */
    private static Specification mergeInSections(final Specification specification,
                                              final List<String> sectionsToAdd) {
        if (sectionsToAdd.isEmpty()) {
            return specification;
        }
        Stream<String> sections = Stream.concat(Optional.ofNullable(specification.getSections())
                        .map(Stream::of).orElse(Stream.empty()), sectionsToAdd.stream());

        return new Specification(specification.getSpecificationTitle(),
                specification.getSpecificationVersion().toString(),
                specification.getSpecificationVendor(),
                specification.getImplementationTitle(),
                specification.getImplementationVersion(),
                specification.getImplementationVendor(), sections.toArray(String[]::new));
    }

    
Trim the supplied string if the string is non-null

Params:
  • value – the string to trim or null
Returns:the trimmed string or null
/**
     * Trim the supplied string if the string is non-null
     *
     * @param value the string to trim or null
     * @return the trimmed string or null
     */
    private static String getTrimmedString(final String value) {
        return value == null ? null : value.trim();
    }

    
Extract an Package Specification from Attributes.

Params:
  • attributes – Attributes to searched
Returns:the new Specification object, or null
/**
     * Extract an Package Specification from Attributes.
     *
     * @param attributes Attributes to searched
     * @return the new Specification object, or null
     */
    private static Specification getSpecification(final String section,
                                                   final Attributes attributes)
        throws ParseException {
        //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});
    }
}