Extension


1   /*
2    * Copyright (C) The Spice Group. All rights reserved.
3    *
4    * This software is published under the terms of the Spice
5    * Software License version 1.1, a copy of which has been included
6    * with this distribution in the LICENSE.txt file.
7    *
8    * This product includes software developed by the
9   �*�Apache Software Foundation (http://www.apache.org/).
10   */
11  package org.codehaus.loom.extension;
12  
13  import java.util.ArrayList  ;
14  import java.util.Iterator  ;
15  import java.util.Map  ;
16  import java.util.StringTokenizer  ;
17  import java.util.jar.Attributes  ;
18  import java.util.jar.Manifest  ;
19  
20  /**
21   * <p>Utility class that represents either an available "Optional Package"
22   * (formerly known as "Standard Extension") as described in the manifest of a
23   * JAR file, or the requirement for such an optional package.</p>
24   *
25   * <p>For more information about optional packages, see the document
26   * <em>Optional Package Versioning</em> in the documentation bundle for your
27   * Java2 Standard Edition package, in file <code>guide/extensions/versioning.html</code>.</p>
28   *
29   * @author <a HREF="mailto:craigmcc at apache.org">Craig R. McClanahan</a>
30   * @author Peter Donald
31   * @version $Revision: 1.1 $ $Date: 2004/04/19 21:40:38 $
32   */
33  public final class Extension
34  {
35      /**
36       * Manifest Attribute Name object for EXTENSION_LIST.
37       *
38       * @see Attributes.Name#EXTENSION_LIST
39       */
40      public static final Attributes.Name   EXTENSION_LIST = Attributes.Name.EXTENSION_LIST;
41      /**
42       * <code>Name</code> object for <code>Optional-Extension-List</code>
43       * manifest attribute used for declaring optional dependencies on installed
44       * extensions. Note that the dependencies declared by this method are not
45       * required for the library to operate but if present will be used. It is
46       * NOT part of the official "Optional Package" specification.
47       *
48       * @see <a HREF="http://java.sun.com/j2se/1.3/docs/guide/extensions/spec.html#dependnecy">
49       *      Installed extension dependency</a>
50       */
51      public static final Attributes.Name   OPTIONAL_EXTENSION_LIST =
52          new Attributes.Name  ( "Optional-Extension-List" );
53      /**
54       * Manifest Attribute Name object for EXTENSION_NAME.
55       *
56       * @see Attributes.Name#EXTENSION_NAME
57       */
58      public static final Attributes.Name   EXTENSION_NAME =
59          Attributes.Name.EXTENSION_NAME;
60      /**
61       * Manifest Attribute Name object for SPECIFICATION_VERSION.
62       *
63       * @see Attributes.Name#SPECIFICATION_VERSION
64       */
65      public static final Attributes.Name   SPECIFICATION_VERSION =
66          Attributes.Name.SPECIFICATION_VERSION;
67      /**
68       * Manifest Attribute Name object for SPECIFICATION_VENDOR.
69       *
70       * @see Attributes.Name#SPECIFICATION_VENDOR
71       */
72      public static final Attributes.Name   SPECIFICATION_VENDOR =
73          Attributes.Name.SPECIFICATION_VENDOR;
74      /**
75       * Manifest Attribute Name object for IMPLEMENTATION_VERSION.
76       *
77       * @see Attributes.Name#IMPLEMENTATION_VERSION
78       */
79      public static final Attributes.Name   IMPLEMENTATION_VERSION =
80          Attributes.Name.IMPLEMENTATION_VERSION;
81      /**
82       * Manifest Attribute Name object for IMPLEMENTATION_VENDOR.
83       *
84       * @see Attributes.Name#IMPLEMENTATION_VENDOR
85       */
86      public static final Attributes.Name   IMPLEMENTATION_VENDOR =
87          Attributes.Name.IMPLEMENTATION_VENDOR;
88      /**
89       * Manifest Attribute Name object for IMPLEMENTATION_URL.
90       *
91       * @see Attributes.Name#IMPLEMENTATION_URL
92       */
93      public static final Attributes.Name   IMPLEMENTATION_URL =
94          Attributes.Name.IMPLEMENTATION_URL;
95      /**
96       * Manifest Attribute Name object for IMPLEMENTATION_VENDOR_ID.
97       *
98       * @see Attributes.Name#IMPLEMENTATION_VENDOR_ID
99       */
100     public static final Attributes.Name   IMPLEMENTATION_VENDOR_ID =
101         Attributes.Name.IMPLEMENTATION_VENDOR_ID;
102     /** Enum indicating that extension is compatible with other extension. */
103     public static final Compatability COMPATIBLE =
104         new Compatability( "COMPATIBLE" );
105     /**
106      * Enum indicating that extension requires an upgrade of specification to be
107      * compatible with other extension.
108      */
109     public static final Compatability REQUIRE_SPECIFICATION_UPGRADE =
110         new Compatability( "REQUIRE_SPECIFICATION_UPGRADE" );
111     /**
112      * Enum indicating that extension requires a vendor switch to be compatible
113      * with other extension.
114      */
115     public static final Compatability REQUIRE_VENDOR_SWITCH =
116         new Compatability( "REQUIRE_VENDOR_SWITCH" );
117     /**
118      * Enum indicating that extension requires an upgrade of implementation to
119      * be compatible with other extension.
120      */
121     public static final Compatability REQUIRE_IMPLEMENTATION_UPGRADE =
122         new Compatability( "REQUIRE_IMPLEMENTATION_UPGRADE" );
123     /**
124      * Enum indicating that extension is incompatible with other extension in
125      * ways other than other enums indicate). ie For example the other extension
126      * may have a different ID.
127      */
128     public static final Compatability INCOMPATIBLE =
129         new Compatability( "INCOMPATIBLE" );
130     /** The name of the optional package being made available, or required. */
131     private String   m_extensionName;
132     /**
133      * The version number (dotted decimal notation) of the specification to
134      * which this optional package conforms.
135      */
136     private DeweyDecimal m_specificationVersion;
137     /**
138      * The name of the company or organization that originated the specification
139      * to which this optional package conforms.
140      */
141     private String   m_specificationVendor;
142     /**
143      * The unique identifier of the company that produced the optional package
144      * contained in this JAR file.
145      */
146     private String   m_implementationVendorID;
147     /**
148      * The name of the company or organization that produced this implementation
149      * of this optional package.
150      */
151     private String   m_implementationVendor;
152     /**
153      * The version number (dotted decimal notation) for this implementation of
154      * the optional package.
155      */
156     private String   m_implementationVersion;
157     /**
158      * The URL from which the most recent version of this optional package can
159      * be obtained if it is not already installed.
160      */
161     private String   m_implementationURL;
162 
163     /**
164      * Return an array of <code>Extension</code> objects representing optional
165      * packages that are available in the JAR file associated with the specified
166      * <code>Manifest</code>.  If there are no such optional packages, a
167      * zero-length array is returned.
168      *
169      * @param manifest Manifest to be parsed
170      * @return the "available" extensions in specified manifest
171      */
172     public static Extension[] getAvailable( final Manifest   manifest )
173     {
174         if( null == manifest )
175         {
176             return new Extension[ 0 ];
177         }
178         final ArrayList   results = new ArrayList  ();
179         final Attributes   mainAttributes = manifest.getMainAttributes();
180         if( null != mainAttributes )
181         {
182             final Extension extension = getExtension( "", mainAttributes );
183             if( null != extension )
184             {
185                 results.add( extension );
186             }
187         }
188         final Map   entries = manifest.getEntries();
189         final Iterator   keys = entries.keySet().iterator();
190         while( keys.hasNext() )
191         {
192             final String   key = (String  )keys.next();
193             final Attributes   attributes = (Attributes  )entries.get( key );
194             final Extension extension = getExtension( "", attributes );
195             if( null != extension )
196             {
197                 results.add( extension );
198             }
199         }
200         return (Extension[])results.toArray( new Extension[ results.size() ] );
201     }
202 
203     /**
204      * Retrieve the set of <code>Extension</code> objects that are available by
205      * the specified Manifest objects. If there are no such optional packages, a
206      * zero-length list is returned.
207      *
208      * @param manifests the manifests to scan
209      * @return the extensions
210      */
211     public static Extension[] getAvailable( final Manifest  [] manifests )
212     {
213         final ArrayList   set = new ArrayList  ();
214         for( int i = 0; i < manifests.length; i++ )
215         {
216             final Extension[] extensions = getAvailable( manifests[ i ] );
217             for( int j = 0; j < extensions.length; j++ )
218             {
219                 set.add( extensions[ j ] );
220             }
221         }
222         return (Extension[])set.toArray( new Extension[ set.size() ] );
223     }
224 
225     /**
226      * Return the set of <code>Extension</code> objects representing optional
227      * packages that are required by the application contained in the JAR file
228      * associated with the specified <code>Manifest</code>.  If there are no
229      * such optional packages, a zero-length list is returned.
230      *
231      * @param manifest Manifest to be parsed
232      * @return the dependencies that are specified in manifes
233      */
234     public static Extension[] getRequired( final Manifest   manifest )
235     {
236         return getListed( manifest, EXTENSION_LIST );
237     }
238 
239     /**
240      * Retrieve the set of <code>Extension</code> objects that are required by
241      * the specified Manifest objects. If there are no such optional packages, a
242      * zero-length list is returned.
243      *
244      * @param manifests the manifests to scan
245      * @return the extensions
246      */
247     public static Extension[] getRequired( final Manifest  [] manifests )
248     {
249         final ArrayList   set = new ArrayList  ();
250         for( int i = 0; i < manifests.length; i++ )
251         {
252             final Extension[] extensions = getRequired( manifests[ i ] );
253             for( int j = 0; j < extensions.length; j++ )
254             {
255                 set.add( extensions[ j ] );
256             }
257         }
258         return (Extension[])set.toArray( new Extension[ set.size() ] );
259     }
260 
261     /**
262      * Return the set of <code>Extension</code> objects representing "Optional
263      * Packages" that the application declares they will use if present. If
264      * there are no such optional packages, a zero-length list is returned.
265      *
266      * @param manifest Manifest to be parsed
267      * @return the optional dependencies that are specified in manifest
268      */
269     public static Extension[] getOptions( final Manifest   manifest )
270     {
271         return getListed( manifest, OPTIONAL_EXTENSION_LIST );
272     }
273 
274     /**
275      * Add Extension to the specified manifest Attributes.
276      *
277      * @param attributes the attributes of manifest to add to
278      * @param extension the extension
279      */
280     public static void addExtension( final Extension extension,
281                                      final Attributes   attributes )
282     {
283         addExtension( extension, "", attributes );
284     }
285 
286     /**
287      * Add Extension to the specified manifest Attributes. Use the specified
288      * prefix so that dependencies can added with a prefix such as "java3d-"
289      * etc.
290      *
291      * @param attributes the attributes of manifest to add to
292      * @param extension the extension
293      * @param prefix the name to prefix to extension
294      */
295     public static void addExtension( final Extension extension,
296                                      final String   prefix,
297                                      final Attributes   attributes )
298     {
299         attributes.putValue( prefix + EXTENSION_NAME,
300                              extension.getExtensionName() );
301         final String   specificationVendor = extension.getSpecificationVendor();
302         if( null != specificationVendor )
303         {
304             attributes.putValue( prefix + SPECIFICATION_VENDOR,
305                                  specificationVendor );
306         }
307         final DeweyDecimal specificationVersion = extension.getSpecificationVersion();
308         if( null != specificationVersion )
309         {
310             attributes.putValue( prefix + SPECIFICATION_VERSION,
311                                  specificationVersion.toString() );
312         }
313         final String   implementationVendorID = extension.getImplementationVendorID();
314         if( null != implementationVendorID )
315         {
316             attributes.putValue( prefix + IMPLEMENTATION_VENDOR_ID,
317                                  implementationVendorID );
318         }
319         final String   implementationVendor = extension.getImplementationVendor();
320         if( null != implementationVendor )
321         {
322             attributes.putValue( prefix + IMPLEMENTATION_VENDOR,
323                                  implementationVendor );
324         }
325         final String   implementationVersion = extension.getImplementationVersion();
326         if( null != implementationVersion )
327         {
328             attributes.putValue( prefix + IMPLEMENTATION_VERSION,
329                                  implementationVersion.toString() );
330         }
331         final String   implementationURL = extension.getImplementationURL();
332         if( null != implementationURL )
333         {
334             attributes.putValue( prefix + IMPLEMENTATION_URL,
335                                  implementationURL );
336         }
337     }
338 
339     /**
340      * The constructor to create Extension object. Note that every component is
341      * allowed to be specified but only the extensionName is mandatory.
342      *
343      * @param extensionName the name of extension.
344      * @param specificationVersion the specification Version of extension.
345      * @param specificationVendor the specification Vendor of extension.
346      * @param implementationVersion the implementation Version of extension.
347      * @param implementationVendor the implementation Vendor of extension.
348      * @param implementationVendorId the implementation VendorId of extension.
349      * @param implementationURL the implementation URL of extension.
350      */
351     public Extension( final String   extensionName,
352                       final String   specificationVersion,
353                       final String   specificationVendor,
354                       final String   implementationVersion,
355                       final String   implementationVendor,
356                       final String   implementationVendorId,
357                       final String   implementationURL )
358     {
359         if( null == extensionName )
360         {
361             throw new NullPointerException  ( "extensionName" );
362         }
363         m_extensionName = extensionName;
364         m_specificationVendor = specificationVendor;
365         if( null != specificationVersion )
366         {
367             try
368             {
369                 m_specificationVersion =
370                 new DeweyDecimal( specificationVersion );
371             }
372             catch( final NumberFormatException   nfe )
373             {
374                 final String   error = "Bad specification version format '" +
375                     specificationVersion +
376                     "' in '" + extensionName + "'. (Reason: " + nfe + ")";
377                 throw new IllegalArgumentException  ( error );
378             }
379         }
380         m_implementationURL = implementationURL;
381         m_implementationVendor = implementationVendor;
382         m_implementationVendorID = implementationVendorId;
383         m_implementationVersion = implementationVersion;
384     }
385 
386     /**
387      * Get the name of the extension.
388      *
389      * @return the name of the extension
390      */
391     public String   getExtensionName()
392     {
393         return m_extensionName;
394     }
395 
396     /**
397      * Get the vendor of the extensions specification.
398      *
399      * @return the vendor of the extensions specification.
400      */
401     public String   getSpecificationVendor()
402     {
403         return m_specificationVendor;
404     }
405 
406     /**
407      * Get the version of the extensions specification.
408      *
409      * @return the version of the extensions specification.
410      */
411     public DeweyDecimal getSpecificationVersion()
412     {
413         return m_specificationVersion;
414     }
415 
416     /**
417      * Get the url of the extensions implementation.
418      *
419      * @return the url of the extensions implementation.
420      */
421     public String   getImplementationURL()
422     {
423         return m_implementationURL;
424     }
425 
426     /**
427      * Get the vendor of the extensions implementation.
428      *
429      * @return the vendor of the extensions implementation.
430      */
431     public String   getImplementationVendor()
432     {
433         return m_implementationVendor;
434     }
435 
436     /**
437      * Get the vendorID of the extensions implementation.
438      *
439      * @return the vendorID of the extensions implementation.
440      */
441     public String   getImplementationVendorID()
442     {
443         return m_implementationVendorID;
444     }
445 
446     /**
447      * Get the version of the extensions implementation.
448      *
449      * @return the version of the extensions implementation.
450      */
451     public String   getImplementationVersion()
452     {
453         return m_implementationVersion;
454     }
455 
456     /**
457      * Return a Compatibility enum indicating the relationship of this
458      * <code>Extension</code> with the specified <code>Extension</code>.
459      *
460      * @param required Description of the required optional package
461      * @return the enum indicating the compatability (or lack thereof) of
462      *         specifed extension
463      */
464     public Compatability getCompatibilityWith( final Extension required )
465     {
466         // Extension Name must match
467         if( !m_extensionName.equals( required.getExtensionName() ) )
468         {
469             return INCOMPATIBLE;
470         }
471         // Available specification version must be >= required
472         final DeweyDecimal specificationVersion = required.getSpecificationVersion();
473         if( null != specificationVersion )
474         {
475             if( null == m_specificationVersion ||
476                 !isCompatible( m_specificationVersion, specificationVersion ) )
477             {
478                 return REQUIRE_SPECIFICATION_UPGRADE;
479             }
480         }
481         // Implementation Vendor ID must match
482         final String   implementationVendorId = required.getImplementationVendorID();
483         if( null != implementationVendorId )
484         {
485             if( null == m_implementationVendorID ||
486                 !m_implementationVendorID.equals( implementationVendorId ) )
487             {
488                 return REQUIRE_VENDOR_SWITCH;
489             }
490         }
491 
492         // This available optional package satisfies the requirements
493         return COMPATIBLE;
494     }
495 
496     /**
497      * Return <code>true</code> if the specified <code>Extension</code> (which
498      * represents an optional package required by an application) is satisfied
499      * by this <code>Extension</code> (which represents an optional package that
500      * is already installed.  Otherwise, return <code>false</code>.
501      *
502      * @param required Description of the required optional package
503      * @return true if the specified extension is compatible with this
504      *         extension
505      */
506     public boolean isCompatibleWith( final Extension required )
507     {
508         return ( COMPATIBLE == getCompatibilityWith( required ) );
509     }
510 
511     /**
512      * Return a String representation of this object.
513      *
514      * @return string representation of object.
515      */
516     public String   toString()
517     {
518         final String   lineSeparator = System.getProperty( "line.separator" );
519         final String   brace = ": ";
520         final StringBuffer   sb = new StringBuffer  ( EXTENSION_NAME.toString() );
521         sb.append( brace );
522         sb.append( m_extensionName );
523         sb.append( lineSeparator );
524         if( null != m_specificationVersion )
525         {
526             sb.append( SPECIFICATION_VERSION );
527             sb.append( brace );
528             sb.append( m_specificationVersion );
529             sb.append( lineSeparator );
530         }
531         if( null != m_specificationVendor )
532         {
533             sb.append( SPECIFICATION_VENDOR );
534             sb.append( brace );
535             sb.append( m_specificationVendor );
536             sb.append( lineSeparator );
537         }
538         if( null != m_implementationVersion )
539         {
540             sb.append( IMPLEMENTATION_VERSION );
541             sb.append( brace );
542             sb.append( m_implementationVersion );
543             sb.append( lineSeparator );
544         }
545         if( null != m_implementationVendorID )
546         {
547             sb.append( IMPLEMENTATION_VENDOR_ID );
548             sb.append( brace );
549             sb.append( m_implementationVendorID );
550             sb.append( lineSeparator );
551         }
552         if( null != m_implementationVendor )
553         {
554             sb.append( IMPLEMENTATION_VENDOR );
555             sb.append( brace );
556             sb.append( m_implementationVendor );
557             sb.append( lineSeparator );
558         }
559         if( null != m_implementationURL )
560         {
561             sb.append( IMPLEMENTATION_URL );
562             sb.append( brace );
563             sb.append( m_implementationURL );
564             sb.append( lineSeparator );
565         }
566         return sb.toString();
567     }
568 
569     /**
570      * Return <code>true</code> if the first version number is greater than or
571      * equal to the second; otherwise return <code>false</code>.
572      *
573      * @param first First version number (dotted decimal)
574      * @param second Second version number (dotted decimal)
575      */
576     private boolean isCompatible( final DeweyDecimal first,
577                                   final DeweyDecimal second )
578     {
579         return first.isGreaterThanOrEqual( second );
580     }
581 
582     /**
583      * Retrieve all the extensions listed under a particular key (Usually
584      * EXTENSION_LIST or OPTIONAL_EXTENSION_LIST).
585      *
586      * @param manifest the manifest to extract extensions from
587      * @param listKey the key used to get list (Usually EXTENSION_LIST or
588      * OPTIONAL_EXTENSION_LIST)
589      * @return the list of listed extensions
590      */
591     private static Extension[] getListed( final Manifest   manifest,
592                                           final Attributes.Name   listKey )
593     {
594         final ArrayList   results = new ArrayList  ();
595         final Attributes   mainAttributes = manifest.getMainAttributes();
596         if( null != mainAttributes )
597         {
598             getExtension( mainAttributes, results, listKey );
599         }
600         final Map   entries = manifest.getEntries();
601         final Iterator   keys = entries.keySet().iterator();
602         while( keys.hasNext() )
603         {
604             final String   key = (String  )keys.next();
605             final Attributes   attributes = (Attributes  )entries.get( key );
606             getExtension( attributes, results, listKey );
607         }
608         return (Extension[])results.toArray( new Extension[ 0 ] );
609     }
610 
611     /**
612      * Add required optional packages defined in the specified attributes entry,
613      * if any.
614      *
615      * @param attributes Attributes to be parsed
616      * @param required list to add required optional packages to
617      * @param listKey the key to use to lookup list, usually EXTENSION_LIST or
618      * OPTIONAL_EXTENSION_LIST
619      */
620     private static void getExtension( final Attributes   attributes,
621                                       final ArrayList   required,
622                                       final Attributes.Name   listKey )
623     {
624         final String   names = attributes.getValue( listKey );
625         if( null == names )
626         {
627             return;
628         }
629         final String  [] extentions = split( names, " " );
630         for( int i = 0; i < extentions.length; i++ )
631         {
632             final String   prefix = extentions[ i ] + "-";
633             final Extension extension = getExtension( prefix, attributes );
634             if( null != extension )
635             {
636                 required.add( extension );
637             }
638         }
639     }
640 
641     /**
642      * Splits the string on every token into an array of strings.
643      *
644      * @param string the string
645      * @param onToken the token
646      * @return the resultant array
647      */
648     private static final String  [] split( final String   string,
649                                          final String   onToken )
650     {
651         final StringTokenizer   tokenizer = new StringTokenizer  ( string,
652                                                                onToken );
653         final String  [] result = new String  [ tokenizer.countTokens() ];
654         for( int i = 0; i < result.length; i++ )
655         {
656             result[ i ] = tokenizer.nextToken();
657         }
658         return result;
659     }
660 
661     /**
662      * Extract an Extension from Attributes. Prefix indicates the prefix checked
663      * for each string. Usually the prefix is <em>"&lt;extension&gt;-"</em> if
664      * looking for a <b>Required</b> extension. If you are looking for an
665      * <b>Available</b> extension then the prefix is <em>""</em>.
666      *
667      * @param prefix the prefix for each attribute name
668      * @param attributes Attributes to searched
669      * @return the new Extension object, or null
670      */
671     private static Extension getExtension( final String   prefix,
672                                            final Attributes   attributes )
673     {
674         //WARNING: We trim the values of all the attributes because
675         //Some extension declarations are badly defined (ie have spaces
676         //after version or vendorID)
677         final String   nameKey = prefix + EXTENSION_NAME;
678         final String   name = getTrimmedString( attributes.getValue( nameKey ) );
679         if( null == name )
680         {
681             return null;
682         }
683         final String   specVendorKey = prefix + SPECIFICATION_VENDOR;
684         final String   specVendor = getTrimmedString(
685             attributes.getValue( specVendorKey ) );
686         final String   specVersionKey = prefix + SPECIFICATION_VERSION;
687         final String   specVersion = getTrimmedString(
688             attributes.getValue( specVersionKey ) );
689         final String   impVersionKey = prefix + IMPLEMENTATION_VERSION;
690         final String   impVersion = getTrimmedString(
691             attributes.getValue( impVersionKey ) );
692         final String   impVendorKey = prefix + IMPLEMENTATION_VENDOR;
693         final String   impVendor = getTrimmedString(
694             attributes.getValue( impVendorKey ) );
695         final String   impVendorIDKey = prefix + IMPLEMENTATION_VENDOR_ID;
696         final String   impVendorId = getTrimmedString(
697             attributes.getValue( impVendorIDKey ) );
698         final String   impURLKey = prefix + IMPLEMENTATION_URL;
699         final String   impURL = getTrimmedString(
700             attributes.getValue( impURLKey ) );
701         return new Extension( name, specVersion, specVendor, impVersion,
702                               impVendor, impVendorId, impURL );
703     }
704 
705     /**
706      * Trim the supplied string if the string is non-null
707      *
708      * @param value the string to trim or null
709      * @return the trimmed string or null
710      */
711     private static String   getTrimmedString( final String   value )
712     {
713         if( null == value )
714         {
715             return null;
716         }
717         else
718         {
719             return value.trim();
720         }
721     }
722 }
723
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags