You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@avalon.apache.org by do...@apache.org on 2002/04/01 12:32:40 UTC
cvs commit: jakarta-avalon-excalibur/extension/src/java/org/apache/avalon/excalibur/extension Specification.java
donaldp 02/04/01 02:32:40
Added: extension/src/java/org/apache/avalon/excalibur/extension
Specification.java
Log:
Start to implement a PackageSpecification parsing/reading mechanism similar to Extension parsing/reading mechanism
Revision Changes Path
1.1 jakarta-avalon-excalibur/extension/src/java/org/apache/avalon/excalibur/extension/Specification.java
Index: Specification.java
===================================================================
/*
* Copyright (C) The Apache Software Foundation. All rights reserved.
*
* This software is published under the terms of the Apache Software License
* version 1.1, a copy of which has been included with this distribution in
* the LICENSE.txt file.
*/
package org.apache.avalon.excalibur.extension;
import java.text.ParseException;
import java.util.ArrayList;
import java.util.Iterator;
import java.util.Map;
import java.util.jar.Attributes;
import java.util.jar.Manifest;
/**
* <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>
*
* @author <a href="mailto:peter@apache.org">Peter Donald</a>
* @version $Revision: 1.1 $ $Date: 2002/04/01 10:32:40 $
*/
public final class Specification
{
/**
* Manifest Attribute Name object for SPECIFICATION_TITLE.
* @see Attributes.Name#SPECIFICATION_TITLE
*/
public static final Attributes.Name SPECIFICATION_TITLE = Attributes.Name.SPECIFICATION_TITLE;
/**
* Manifest Attribute Name object for SPECIFICATION_VERSION.
* @see Attributes.Name#SPECIFICATION_VERSION
*/
public static final Attributes.Name SPECIFICATION_VERSION = Attributes.Name.SPECIFICATION_VERSION;
/**
* Manifest Attribute Name object for SPECIFICATION_VENDOR.
* @see Attributes.Name#SPECIFICATION_VENDOR
*/
public static final Attributes.Name SPECIFICATION_VENDOR = Attributes.Name.SPECIFICATION_VENDOR;
/**
* Manifest Attribute Name object for IMPLEMENTATION_TITLE.
* @see Attributes.Name#IMPLEMENTATION_TITLE
*/
public static final Attributes.Name IMPLEMENTATION_TITLE = Attributes.Name.IMPLEMENTATION_TITLE;
/**
* Manifest Attribute Name object for IMPLEMENTATION_VERSION.
* @see Attributes.Name#IMPLEMENTATION_VERSION
*/
public static final Attributes.Name IMPLEMENTATION_VERSION = Attributes.Name.IMPLEMENTATION_VERSION;
/**
* Manifest Attribute Name object for IMPLEMENTATION_VENDOR.
* @see Attributes.Name#IMPLEMENTATION_VENDOR
*/
public static final Attributes.Name IMPLEMENTATION_VENDOR = Attributes.Name.IMPLEMENTATION_VENDOR;
/**
* Enum indicating that extension is compatible with other Package
* Specification.
*/
public static final Compatability COMPATIBLE =
new Compatability( "COMPATIBLE" );
/**
* Enum indicating that extension requires an upgrade
* of specification to be compatible with other Package Specification.
*/
public static final Compatability REQUIRE_SPECIFICATION_UPGRADE =
new Compatability( "REQUIRE_SPECIFICATION_UPGRADE" );
/**
* Enum indicating that extension requires a vendor
* switch to be compatible with other Package Specification.
*/
public static final Compatability REQUIRE_VENDOR_SWITCH =
new Compatability( "REQUIRE_VENDOR_SWITCH" );
/**
* Enum indicating that extension requires an upgrade
* of implementation to be compatible with other Package Specification.
*/
public static final Compatability REQUIRE_IMPLEMENTATION_CHANGE =
new Compatability( "REQUIRE_IMPLEMENTATION_CHANGE" );
/**
* Enum indicating that extension is incompatible with
* other Package Specification in ways other than other enums
* indicate). ie For example the other Package Specification
* may have a different ID.
*/
public static final Compatability INCOMPATIBLE =
new Compatability( "INCOMPATIBLE" );
/**
* The name of the Package Specification.
*/
private String m_specificationTitle;
/**
* The version number (dotted decimal notation) of the specification
* to which this optional package conforms.
*/
private DeweyDecimal m_specificationVersion;
/**
* The name of the company or organization that originated the
* specification to which this specification conforms.
*/
private String m_specificationVendor;
/**
* The title of implementation.
*/
private String m_implementationTitle;
/**
* The name of the company or organization that produced this
* implementation of this specification.
*/
private String m_implementationVendor;
/**
* The version string for implementation. The version string is
* opaque.
*/
private String m_implementationVersion;
/**
* 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
*/
public static Specification[] getPackageSpecifications( final Manifest manifest )
throws ParseException
{
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( attributes );
if( null != specification )
{
results.add( specification );
}
}
return (Specification[])results.toArray( new Specification[ 0 ] );
}
/**
* 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 )
{
m_specificationTitle = specificationTitle;
m_specificationVendor = specificationVendor;
if( null != specificationVersion )
{
try
{
m_specificationVersion = new DeweyDecimal( specificationVersion );
}
catch( final NumberFormatException nfe )
{
final String error = "Bad specification version format '" + specificationVersion +
"' in '" + specificationTitle + "'. (Reason: " + nfe + ")";
throw new IllegalArgumentException( error );
}
}
m_implementationTitle = implementationTitle;
m_implementationVendor = implementationVendor;
m_implementationVersion = implementationVersion;
if( null == m_specificationTitle )
{
throw new NullPointerException( "specificationTitle" );
}
}
/**
* Get the title of the specification.
*
* @return the title of speciication
*/
public String getSpecificationTitle()
{
return m_specificationTitle;
}
/**
* Get the vendor of the specification.
*
* @return the vendor of the specification.
*/
public String getSpecificationVendor()
{
return m_specificationVendor;
}
/**
* Get the title of the specification.
*
* @return the title of the specification.
*/
public String getImplementationTitle()
{
return m_implementationTitle;
}
/**
* Get the version of the specification.
*
* @return the version of the specification.
*/
public DeweyDecimal getSpecificationVersion()
{
return m_specificationVersion;
}
/**
* Get the vendor of the extensions implementation.
*
* @return the vendor of the extensions implementation.
*/
public String getImplementationVendor()
{
return m_implementationVendor;
}
/**
* Get the version of the implementation.
*
* @return the version of the implementation.
*/
public String getImplementationVersion()
{
return m_implementationVersion;
}
/**
* 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 compatability (or lack thereof)
* of specifed Package Specification
*/
public Compatability getCompatibilityWith( final Specification other )
{
// Specification Name must match
if( !m_specificationTitle.equals( other.getSpecificationTitle() ) )
{
return INCOMPATIBLE;
}
// Available specification version must be >= required
final DeweyDecimal specificationVersion = other.getSpecificationVersion();
if( null != specificationVersion )
{
if( null == m_specificationVersion ||
!isCompatible( m_specificationVersion, specificationVersion ) )
{
return REQUIRE_SPECIFICATION_UPGRADE;
}
}
// Implementation Vendor ID must match
final String implementationVendor = other.getImplementationVendor();
if( null != implementationVendor )
{
if( null == m_implementationVendor ||
!m_implementationVendor.equals( implementationVendor ) )
{
return REQUIRE_VENDOR_SWITCH;
}
}
// Implementation version must be >= required
final String implementationVersion = other.getImplementationVersion();
if( null != implementationVersion )
{
if( null == m_implementationVersion ||
!m_implementationVersion.equals( implementationVersion ) )
{
return REQUIRE_IMPLEMENTATION_CHANGE;
}
}
// This available optional package satisfies the requirements
return COMPATIBLE;
}
/**
* 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.
*
* @return string representation of object.
*/
public String toString()
{
final String lineSeparator = System.getProperty( "line.separator" );
final String brace = ": ";
final StringBuffer sb = new StringBuffer( SPECIFICATION_TITLE.toString() );
sb.append( brace );
sb.append( m_specificationTitle );
sb.append( lineSeparator );
if( null != m_specificationVersion )
{
sb.append( SPECIFICATION_VERSION );
sb.append( brace );
sb.append( m_specificationVersion );
sb.append( lineSeparator );
}
if( null != m_specificationVendor )
{
sb.append( SPECIFICATION_VENDOR );
sb.append( brace );
sb.append( m_specificationVendor );
sb.append( lineSeparator );
}
if( null != m_implementationTitle )
{
sb.append( IMPLEMENTATION_TITLE );
sb.append( brace );
sb.append( m_implementationTitle );
sb.append( lineSeparator );
}
if( null != m_implementationVersion )
{
sb.append( IMPLEMENTATION_VERSION );
sb.append( brace );
sb.append( m_implementationVersion );
sb.append( lineSeparator );
}
if( null != m_implementationVendor )
{
sb.append( IMPLEMENTATION_VENDOR );
sb.append( brace );
sb.append( m_implementationVendor );
sb.append( lineSeparator );
}
return sb.toString();
}
/**
* 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 );
}
/**
* 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 )
{
if( null == value )
{
return null;
}
else
{
return value.trim();
}
}
/**
* Extract an Package Specification from Attributes.
*
* @param attributes Attributes to searched
* @return the new Specification object, or null
*/
private static Specification getSpecification( 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 );
}
}
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>