toolchain/gcc/libjava/java/lang/Package.java

   1 /* Package.java -- information about a package
   2    Copyright (C) 2000, 2001, 2002, 2003 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38 package java.lang;
  39
  40 import java.net.URL;
  41 import java.util.NoSuchElementException;
  42 import java.util.StringTokenizer;
  43
  44 /**
  45  * Everything you ever wanted to know about a package. This class makes it
  46  * possible to attach specification and implementation information to a
  47  * package as explained in the
  48  * <a href="http://java.sun.com/products/jdk/1.3/docs/guide/versioning/spec/VersioningSpecification.html#PackageVersionSpecification">Package Versioning Specification</a>
  49  * section of the
  50  * <a href="http://java.sun.com/products/jdk/1.3/docs/guide/versioning/spec/VersioningSpecification.html">Product Versioning Specification</a>.
  51  * It also allows packages to be sealed with respect to the originating URL.
  52  *
  53  * <p>The most useful method is the <code>isCompatibleWith()</code> method that
  54  * compares a desired version of a specification with the version of the
  55  * specification as implemented by a package. A package is considered
  56  * compatible with another version if the version of the specification is
  57  * equal or higher then the requested version. Version numbers are represented
  58  * as strings of positive numbers separated by dots (e.g. "1.2.0").
  59  * The first number is called the major number, the second the minor,
  60  * the third the micro, etc. A version is considered higher then another
  61  * version if it has a bigger major number then the another version or when
  62  * the major numbers of the versions are equal if it has a bigger minor number
  63  * then the other version, etc. (If a version has no minor, micro, etc numbers
  64  * then they are considered the be 0.)
  65  *
  66  * @author Mark Wielaard <mark@klomp.org>
  67  * @see ClassLoader#definePackage(String, String, String, String, String,
  68  *      String, String, URL)
  69  * @since 1.2
  70  * @status updated to 1.4
  71  */
  72 public class Package
  73 {
  74   /** The name of the Package */
  75   final private String name;
  76
  77   /** The name if the implementation */
  78   final private String implTitle;
  79
  80   /** The vendor that wrote this implementation */
  81   final private String implVendor;
  82
  83   /** The version of this implementation */
  84   final private String implVersion;
  85
  86   /** The name of the specification */
  87   final private String specTitle;
  88
  89   /** The name of the specification designer */
  90   final private String specVendor;
  91
  92   /** The version of this specification */
  93   final private String specVersion;
  94
  95   /** If sealed the origin of the package classes, otherwise null */
  96   final private URL sealed;
  97
  98   /**
  99    * A package local constructor for the Package class. All parameters except
 100    * the <code>name</code> of the package may be <code>null</code>.
 101    * There are no public constructors defined for Package; this is a package
 102    * local constructor that is used by java.lang.Classloader.definePackage().
 103    *
 104    * @param name The name of the Package
 105    * @param specTitle The name of the specification
 106    * @param specVendor The name of the specification designer
 107    * @param specVersion The version of this specification
 108    * @param implTitle The name of the implementation
 109    * @param implVendor The vendor that wrote this implementation
 110    * @param implVersion The version of this implementation
 111    * @param sealed If sealed the origin of the package classes
 112    */
 113   Package(String name,
 114           String specTitle, String specVendor, String specVersion,
 115           String implTitle, String implVendor, String implVersion, URL sealed)
 116   {
 117     if (name == null)
 118       throw new IllegalArgumentException("null Package name");
 119
 120     this.name = name;
 121     this.implTitle = implTitle;
 122     this.implVendor = implVendor;
 123     this.implVersion = implVersion;
 124     this.specTitle = specTitle;
 125     this.specVendor = specVendor;
 126     this.specVersion = specVersion;
 127     this.sealed = sealed;
 128   }
 129
 130   /**
 131    * Returns the Package name in dot-notation.
 132    *
 133    * @return the non-null package name
 134    */
 135   public String getName()
 136   {
 137     return name;
 138   }
 139
 140   /**
 141    * Returns the name of the specification, or null if unknown.
 142    *
 143    * @return the specification title
 144    */
 145   public String getSpecificationTitle()
 146   {
 147     return specTitle;
 148   }
 149
 150   /**
 151    * Returns the version of the specification, or null if unknown.
 152    *
 153    * @return the specification version
 154    */
 155   public String getSpecificationVersion()
 156   {
 157     return specVersion;
 158   }
 159
 160   /**
 161    * Returns the name of the specification designer, or null if unknown.
 162    *
 163    * @return the specification vendor
 164    */
 165   public String getSpecificationVendor()
 166   {
 167     return specVendor;
 168   }
 169
 170   /**
 171    * Returns the name of the implementation, or null if unknown.
 172    *
 173    * @return the implementation title
 174    */
 175   public String getImplementationTitle()
 176   {
 177     return implTitle;
 178   }
 179
 180   /**
 181    * Returns the version of this implementation, or null if unknown.
 182    *
 183    * @return the implementation version
 184    */
 185   public String getImplementationVersion()
 186   {
 187     return implVersion;
 188   }
 189
 190   /**
 191    * Returns the vendor that wrote this implementation, or null if unknown.
 192    *
 193    * @return the implementation vendor
 194    */
 195   public String getImplementationVendor()
 196   {
 197     return implVendor;
 198   }
 199
 200   /**
 201    * Returns true if this Package is sealed.
 202    *
 203    * @return true if the package is sealed
 204    */
 205   public boolean isSealed()
 206   {
 207     return sealed != null;
 208   }
 209
 210   /**
 211    * Returns true if this Package is sealed and the origin of the classes is
 212    * the given URL.
 213    *
 214    * @param url the URL to test
 215    * @return true if the package is sealed by this URL
 216    * @throws NullPointerException if url is null
 217    */
 218   public boolean isSealed(URL url)
 219   {
 220     return url.equals(sealed);
 221   }
 222
 223   /**
 224    * Checks if the version of the specification is higher or at least as high
 225    * as the desired version. Comparison is done by sequentially comparing
 226    * dotted decimal numbers from the parameter and from
 227    * <code>getSpecificationVersion</code>.
 228    *
 229    * @param version the (minimal) desired version of the specification
 230    * @throws NumberFormatException if either version string is invalid
 231    * @throws NullPointerException if either version string is null
 232    */
 233   public boolean isCompatibleWith(String version)
 234   {
 235     StringTokenizer versionTokens = new StringTokenizer(version, ".");
 236     StringTokenizer specTokens = new StringTokenizer(specVersion, ".");
 237     try
 238       {
 239         while (versionTokens.hasMoreElements())
 240           {
 241             int vers = Integer.parseInt(versionTokens.nextToken());
 242             int spec = Integer.parseInt(specTokens.nextToken());
 243             if (spec < vers)
 244               return false;
 245             else if (spec > vers)
 246               return true;
 247             // They must be equal, next Token please!
 248           }
 249       }
 250     catch (NoSuchElementException e)
 251       {
 252         // This must have been thrown by spec.nextToken() so return false.
 253         return false;
 254       }
 255     // They must have been exactly the same version.
 256     // Or the specVersion has more subversions. That is also good.
 257     return true;
 258   }
 259
 260   /**
 261    * Returns the named package if it is known by the callers class loader.
 262    * It may return null if the package is unknown, when there is no
 263    * information on that particular package available or when the callers
 264    * classloader is null.
 265    *
 266    * @param name the name of the desired package
 267    * @return the package by that name in the current ClassLoader
 268    */
 269   public static Package getPackage(String name)
 270   {
 271     // Get the caller's classloader
 272     ClassLoader cl = VMSecurityManager.currentClassLoader();
 273     return cl != null ? cl.getPackage(name) : null;
 274   }
 275
 276   /**
 277    * Returns all the packages that are known to the callers class loader.
 278    * It may return an empty array if the classloader of the caller is null.
 279    *
 280    * @return an array of all known packages
 281    */
 282   public static Package[] getPackages()
 283   {
 284     // Get the caller's classloader
 285     Class c = VMSecurityManager.getClassContext()[1];
 286     ClassLoader cl = c.getClassLoader();
 287     // Sun's implementation returns the packages loaded by the bootstrap
 288     // classloader if cl is null, but right now our bootstrap classloader
 289     // does not create any Packages.
 290     return cl != null ? cl.getPackages() : new Package[0];
 291   }
 292
 293   /**
 294    * Returns the hashCode of the name of this package.
 295    *
 296    * @return the hash code
 297    */
 298   public int hashCode()
 299   {
 300     return name.hashCode();
 301   }
 302
 303   /**
 304    * Returns a string representation of this package. It is specified to
 305    * be <code>"package " + getName() + (getSpecificationTitle() == null
 306    * ? "" : ", " + getSpecificationTitle()) + (getSpecificationVersion()
 307    * == null ? "" : ", version " + getSpecificationVersion())</code>.
 308    *
 309    * @return the string representation of the package
 310    */
 311   public String toString()
 312   {
 313     return ("package " + name + (specTitle == null ? "" : ", " + specTitle)
 314             + (specVersion == null ? "" : ", version " + specVersion));
 315   }
 316 } // class Package