- 001
/* - 002
* @(#)Package.java 1.48 05/11/30 - 003 *
- 004 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
- 005 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
- 006
*/ - 007
- 008package java.lang;
- 009
- 010import java.io.InputStream;
- 011import java.util.Enumeration;
- 012
- 013import java.util.StringTokenizer;
- 014import java.io.File;
- 015import java.io.FileInputStream;
- 016import java.io.FileNotFoundException;
- 017import java.io.IOException;
- 018import java.net.URL;
- 019import java.net.MalformedURLException;
- 020import java.security.AccessController;
- 021import java.security.PrivilegedAction;
- 022
- 023import java.util.jar.JarInputStream;
- 024import java.util.jar.Manifest;
- 025import java.util.jar.Attributes;
- 026import java.util.jar.Attributes.Name;
- 027import java.util.jar.JarException;
- 028import java.util.Map;
- 029import java.util.HashMap;
- 030import java.util.Iterator;
- 031
- 032import sun.net.www.ParseUtil;
- 033
- 034import java.lang.annotation.Annotation;
- 035
- 036/**
- 037 * <code>Package</code> objects contain version information
- 038 * about the implementation and specification of a Java package.
- 039 * This versioning information is retrieved and made available
- 040 * by the {@link ClassLoader <code>ClassLoader</code>} instance that
- 041 * loaded the class(es). Typically, it is stored in the manifest that is
- 042 * distributed with the classes.
- 043 *
- 044 * <p>The set of classes that make up the package may implement a
- 045 * particular specification and if so the specification title, version number,
- 046 * and vendor strings identify that specification.
- 047 * An application can ask if the package is
- 048 * compatible with a particular version, see the {@link #isCompatibleWith
- 049 * <code>isCompatibleWith</code>} method for details.
- 050 *
- 051 * <p>Specification version numbers use a syntax that consists of positive
- 052 * decimal integers separated by periods ".", for example "2.0" or
- 053 * "1.2.3.4.5.6.7". This allows an extensible number to be used to represent
- 054 * major, minor, micro, etc. versions. The version specification is described
- 055 * by the following formal grammar:
- 056 * <blockquote>
- 057 * <dl>
- 058 * <dt><i>SpecificationVersion:
- 059 * <dd>Digits RefinedVersion<sub>opt</sub></i>
- 060
- 061 * <p><dt><i>RefinedVersion:</i>
- 062 * <dd><code>.</code> <i>Digits</i>
- 063 * <dd><code>.</code> <i>Digits RefinedVersion</i>
- 064 *
- 065 * <p><dt><i>Digits:
- 066 * <dd>Digit
- 067 * <dd>Digits</i>
- 068 *
- 069 * <p><dt><i>Digit:</i>
- 070 * <dd>any character for which {@link Character#isDigit} returns <code>true</code>,
- 071 * e.g. 0, 1, 2, ...
- 072 * </dl>
- 073 * </blockquote>
- 074 *
- 075 * <p>The implementation title, version, and vendor strings identify an
- 076 * implementation and are made available conveniently to enable accurate
- 077 * reporting of the packages involved when a problem occurs. The contents
- 078 * all three implementation strings are vendor specific. The
- 079 * implementation version strings have no specified syntax and should
- 080 * only be compared for equality with desired version identifiers.
- 081 *
- 082 * <p>Within each <code>ClassLoader</code> instance all classes from the same
- 083 * java package have the same Package object. The static methods allow a package
- 084 * to be found by name or the set of all packages known to the current class
- 085 * loader to be found.
- 086 *
- 087 * @see ClassLoader#definePackage
- 088 */
- 089public class Package implements java.lang.reflect.AnnotatedElement {
- 090 /**
- 091 * Return the name of this package.
- 092 *
- 093 * @return The fully-qualified name of this package as defined in the
- 094 * <em>Java Language Specification, Third Edition</em>
- 095 * <a href="http://java.sun.com/docs/books/jls/third_edition/html/names.html#6.5.3">
- 096 * §6.5.3</a>, for example, <tt>java.lang</tt>
- 097 */
- 098 public String getName() {
- 099 return pkgName;
- 100 }
- 101
- 102
- 103 /**
- 104 * Return the title of the specification that this package implements.
- 105 * @return the specification title, null is returned if it is not known.
- 106 */
- 107 public String getSpecificationTitle() {
- 108 return specTitle;
- 109 }
- 110
- 111 /**
- 112 * Returns the version number of the specification
- 113 * that this package implements.
- 114 * This version string must be a sequence of positive decimal
- 115 * integers separated by "."'s and may have leading zeros.
- 116 * When version strings are compared the most significant
- 117 * numbers are compared.
- 118 * @return the specification version, null is returned if it is not known.
- 119 */
- 120 public String getSpecificationVersion() {
- 121 return specVersion;
- 122 }
- 123
- 124 /**
- 125 * Return the name of the organization, vendor,
- 126 * or company that owns and maintains the specification
- 127 * of the classes that implement this package.
- 128 * @return the specification vendor, null is returned if it is not known.
- 129 */
- 130 public String getSpecificationVendor() {
- 131 return specVendor;
- 132 }
- 133
- 134 /**
- 135 * Return the title of this package.
- 136 * @return the title of the implementation, null is returned if it is not known.
- 137 */
- 138 public String getImplementationTitle() {
- 139 return implTitle;
- 140 }
- 141
- 142 /**
- 143 * Return the version of this implementation. It consists of any string
- 144 * assigned by the vendor of this implementation and does
- 145 * not have any particular syntax specified or expected by the Java
- 146 * runtime. It may be compared for equality with other
- 147 * package version strings used for this implementation
- 148 * by this vendor for this package.
- 149 * @return the version of the implementation, null is returned if it is not known.
- 150 */
- 151 public String getImplementationVersion() {
- 152 return implVersion;
- 153 }
- 154
- 155 /**
- 156 * Returns the name of the organization,
- 157 * vendor or company that provided this implementation.
- 158 * @return the vendor that implemented this package..
- 159 */
- 160 public String getImplementationVendor() {
- 161 return implVendor;
- 162 }
- 163
- 164 /**
- 165 * Returns true if this package is sealed.
- 166 *
- 167 * @return true if the package is sealed, false otherwise
- 168 */
- 169 public boolean isSealed() {
- 170 return sealBase != null;
- 171 }
- 172
- 173 /**
- 174 * Returns true if this package is sealed with respect to the specified
- 175 * code source url.
- 176 *
- 177 * @param url the code source url
- 178 * @return true if this package is sealed with respect to url
- 179 */
- 180 public boolean isSealed(URL url) {
- 181 return url.equals(sealBase);
- 182 }
- 183
- 184 /**
- 185 * Compare this package's specification version with a
- 186 * desired version. It returns true if
- 187 * this packages specification version number is greater than or equal
- 188 * to the desired version number. <p>
- 189 *
- 190 * Version numbers are compared by sequentially comparing corresponding
- 191 * components of the desired and specification strings.
- 192 * Each component is converted as a decimal integer and the values
- 193 * compared.
- 194 * If the specification value is greater than the desired
- 195 * value true is returned. If the value is less false is returned.
- 196 * If the values are equal the period is skipped and the next pair of
- 197 * components is compared.
- 198 *
- 199 * @param desired the version string of the desired version.
- 200 * @return true if this package's version number is greater
- 201 * than or equal to the desired version number
- 202 *
- 203 * @exception NumberFormatException if the desired or current version
- 204 * is not of the correct dotted form.
- 205 */
- 206 public boolean isCompatibleWith(String desired)
- 207 throws NumberFormatException
- 208 {
- 209 if (specVersion == null || specVersion.length() < 1) {
- 210 throw new NumberFormatException("Empty version string");
- 211 }
- 212
- 213 String [] sa = specVersion.split("\\.", -1);
- 214 int [] si = new int[sa.length];
- 215 for (int i = 0; i < sa.length; i++) {
- 216 si[i] = Integer.parseInt(sa[i]);
- 217 if (si[i] < 0)
- 218 throw NumberFormatException.forInputString("" + si[i]);
- 219 }
- 220
- 221 String [] da = desired.split("\\.", -1);
- 222 int [] di = new int[da.length];
- 223 for (int i = 0; i < da.length; i++) {
- 224 di[i] = Integer.parseInt(da[i]);
- 225 if (di[i] < 0)
- 226 throw NumberFormatException.forInputString("" + di[i]);
- 227 }
- 228
- 229 int len = Math.max(di.length, si.length);
- 230 for (int i = 0; i < len; i++) {
- 231 int d = (i < di.length ? di[i] : 0);
- 232 int s = (i < si.length ? si[i] : 0);
- 233 if (s < d)
- 234 return false;
- 235 if (s > d)
- 236 return true;
- 237 }
- 238 return true;
- 239 }
- 240
- 241 /**
- 242 * Find a package by name in the callers <code>ClassLoader</code> instance.
- 243 * The callers <code>ClassLoader</code> instance is used to find the package
- 244 * instance corresponding to the named class. If the callers
- 245 * <code>ClassLoader</code> instance is null then the set of packages loaded
- 246 * by the system <code>ClassLoader</code> instance is searched to find the
- 247 * named package. <p>
- 248 *
- 249 * Packages have attributes for versions and specifications only if the class
- 250 * loader created the package instance with the appropriate attributes. Typically,
- 251 * those attributes are defined in the manifests that accompany the classes.
- 252 *
- 253 * @param name a package name, for example, java.lang.
- 254 * @return the package of the requested name. It may be null if no package
- 255 * information is available from the archive or codebase.
- 256 */
- 257 public static Package getPackage(String name) {
- 258 ClassLoader l = ClassLoader.getCallerClassLoader();
- 259 if (l != null) {
- 260 return l.getPackage(name);
- 261 } else {
- 262 return getSystemPackage(name);
- 263 }
- 264 }
- 265
- 266 /**
- 267 * Get all the packages currently known for the caller's <code>ClassLoader</code>
- 268 * instance. Those packages correspond to classes loaded via or accessible by
- 269 * name to that <code>ClassLoader</code> instance. If the caller's
- 270 * <code>ClassLoader</code> instance is the bootstrap <code>ClassLoader</code>
- 271 * instance, which may be represented by <code>null</code> in some implementations,
- 272 * only packages corresponding to classes loaded by the bootstrap
- 273 * <code>ClassLoader</code> instance will be returned.
- 274 *
- 275 * @return a new array of packages known to the callers <code>ClassLoader</code>
- 276 * instance. An zero length array is returned if none are known.
- 277 */
- 278 public static Package[] getPackages() {
- 279 ClassLoader l = ClassLoader.getCallerClassLoader();
- 280 if (l != null) {
- 281 return l.getPackages();
- 282 } else {
- 283 return getSystemPackages();
- 284 }
- 285 }
- 286
- 287 /**
- 288 * Get the package for the specified class.
- 289 * The class's class loader is used to find the package instance
- 290 * corresponding to the specified class. If the class loader
- 291 * is the bootstrap class loader, which may be represented by
- 292 * <code>null</code> in some implementations, then the set of packages
- 293 * loaded by the bootstrap class loader is searched to find the package.
- 294 * <p>
- 295 * Packages have attributes for versions and specifications only
- 296 * if the class loader created the package
- 297 * instance with the appropriate attributes. Typically those
- 298 * attributes are defined in the manifests that accompany
- 299 * the classes.
- 300 *
- 301 * @param class the class to get the package of.
- 302 * @return the package of the class. It may be null if no package
- 303 * information is available from the archive or codebase. */
- 304 static Package getPackage(Class c) {
- 305 String name = c.getName();
- 306 int i = name.lastIndexOf('.');
- 307 if (i != -1) {
- 308 name = name.substring(0, i);
- 309 ClassLoader cl = c.getClassLoader();
- 310 if (cl != null) {
- 311 return cl.getPackage(name);
- 312 } else {
- 313 return getSystemPackage(name);
- 314 }
- 315 } else {
- 316 return null;
- 317 }
- 318 }
- 319
- 320 /**
- 321 * Return the hash code computed from the package name.
- 322 * @return the hash code computed from the package name.
- 323 */
- 324 public int hashCode(){
- 325 return pkgName.hashCode();
- 326 }
- 327
- 328 /**
- 329 * Returns the string representation of this Package.
- 330 * Its value is the string "package " and the package name.
- 331 * If the package title is defined it is appended.
- 332 * If the package version is defined it is appended.
- 333 * @return the string representation of the package.
- 334 */
- 335 public String toString() {
- 336 String spec = specTitle;
- 337 String ver = specVersion;
- 338 if (spec != null && spec.length() > 0)
- 339 spec = ", " + spec;
- 340 else
- 341 spec = "";
- 342 if (ver != null && ver.length() > 0)
- 343 ver = ", version " + ver;
- 344 else
- 345 ver = "";
- 346 return "package " + pkgName + spec + ver;
- 347 }
- 348
- 349 private Class<?> getPackageInfo() {
- 350 if (packageInfo == null) {
- 351 try {
- 352 packageInfo = Class.forName(pkgName + ".package-info", false, loader);
- 353 } catch (ClassNotFoundException ex) {
- 354 // store a proxy for the package info that has no annotations
- 355 class PackageInfoProxy {}
- 356 packageInfo = PackageInfoProxy.class;
- 357 }
- 358 }
- 359 return packageInfo;
- 360 }
- 361
- 362 /**
- 363 * @throws NullPointerException {@inheritDoc}
- 364 * @since 1.5
- 365 */
- 366 public <A extends Annotation> A getAnnotation(Class<A> annotationClass) {
- 367 return getPackageInfo().getAnnotation(annotationClass);
- 368 }
- 369
- 370 /**
- 371 * @throws NullPointerException {@inheritDoc}
- 372 * @since 1.5
- 373 */
- 374 public boolean isAnnotationPresent(
- 375 Class<? extends Annotation> annotationClass) {
- 376 return getPackageInfo().isAnnotationPresent(annotationClass);
- 377 }
- 378
- 379 /**
- 380 * @since 1.5
- 381 */
- 382 public Annotation[] getAnnotations() {
- 383 return getPackageInfo().getAnnotations();
- 384 }
- 385
- 386 /**
- 387 * @since 1.5
- 388 */
- 389 public Annotation[] getDeclaredAnnotations() {
- 390 return getPackageInfo().getDeclaredAnnotations();
- 391 }
- 392
- 393 /**
- 394 * Construct a package instance with the specified version
- 395 * information.
- 396 * @param pkgName the name of the package
- 397 * @param spectitle the title of the specification
- 398 * @param specversion the version of the specification
- 399 * @param specvendor the organization that maintains the specification
- 400 * @param impltitle the title of the implementation
- 401 * @param implversion the version of the implementation
- 402 * @param implvendor the organization that maintains the implementation
- 403 * @return a new package for containing the specified information.
- 404 */
- 405 Package(String name,
- 406 String spectitle, String specversion, String specvendor,
- 407 String impltitle, String implversion, String implvendor,
- 408 URL sealbase, ClassLoader loader)
- 409 {
- 410 pkgName = name;
- 411 implTitle = impltitle;
- 412 implVersion = implversion;
- 413 implVendor = implvendor;
- 414 specTitle = spectitle;
- 415 specVersion = specversion;
- 416 specVendor = specvendor;
- 417 sealBase = sealbase;
- 418 this.loader = loader;
- 419 }
- 420
- 421 /*
- 422 * Construct a package using the attributes from the specified manifest.
- 423 *
- 424 * @param name the package name
- 425 * @param man the optional manifest for the package
- 426 * @param url the optional code source url for the package
- 427 */
- 428 private Package(String name, Manifest man, URL url, ClassLoader loader) {
- 429 String path = name.replace('.', '/').concat("/");
- 430 String sealed = null;
- 431 String specTitle= null;
- 432 String specVersion= null;
- 433 String specVendor= null;
- 434 String implTitle= null;
- 435 String implVersion= null;
- 436 String implVendor= null;
- 437 URL sealBase= null;
- 438 Attributes attr = man.getAttributes(path);
- 439 if (attr != null) {
- 440 specTitle = attr.getValue(Name.SPECIFICATION_TITLE);
- 441 specVersion = attr.getValue(Name.SPECIFICATION_VERSION);
- 442 specVendor = attr.getValue(Name.SPECIFICATION_VENDOR);
- 443 implTitle = attr.getValue(Name.IMPLEMENTATION_TITLE);
- 444 implVersion = attr.getValue(Name.IMPLEMENTATION_VERSION);
- 445 implVendor = attr.getValue(Name.IMPLEMENTATION_VENDOR);
- 446 sealed = attr.getValue(Name.SEALED);
- 447 }
- 448 attr = man.getMainAttributes();
- 449 if (attr != null) {
- 450 if (specTitle == null) {
- 451 specTitle = attr.getValue(Name.SPECIFICATION_TITLE);
- 452 }
- 453 if (specVersion == null) {
- 454 specVersion = attr.getValue(Name.SPECIFICATION_VERSION);
- 455 }
- 456 if (specVendor == null) {
- 457 specVendor = attr.getValue(Name.SPECIFICATION_VENDOR);
- 458 }
- 459 if (implTitle == null) {
- 460 implTitle = attr.getValue(Name.IMPLEMENTATION_TITLE);
- 461 }
- 462 if (implVersion == null) {
- 463 implVersion = attr.getValue(Name.IMPLEMENTATION_VERSION);
- 464 }
- 465 if (implVendor == null) {
- 466 implVendor = attr.getValue(Name.IMPLEMENTATION_VENDOR);
- 467 }
- 468 if (sealed == null) {
- 469 sealed = attr.getValue(Name.SEALED);
- 470 }
- 471 }
- 472 if ("true".equalsIgnoreCase(sealed)) {
- 473 sealBase = url;
- 474 }
- 475 pkgName = name;
- 476 this.specTitle = specTitle;
- 477 this.specVersion = specVersion;
- 478 this.specVendor = specVendor;
- 479 this.implTitle = implTitle;
- 480 this.implVersion = implVersion;
- 481 this.implVendor = implVendor;
- 482 this.sealBase = sealBase;
- 483 this.loader = loader;
- 484 }
- 485
- 486 /*
- 487 * Returns the loaded system package for the specified name.
- 488 */
- 489 static Package getSystemPackage(String name) {
- 490 synchronized (pkgs) {
- 491 Package pkg = (Package)pkgs.get(name);
- 492 if (pkg == null) {
- 493 name = name.replace('.', '/').concat("/");
- 494 String fn = getSystemPackage0(name);
- 495 if (fn != null) {
- 496 pkg = defineSystemPackage(name, fn);
- 497 }
- 498 }
- 499 return pkg;
- 500 }
- 501 }
- 502
- 503 /*
- 504 * Return an array of loaded system packages.
- 505 */
- 506 static Package[] getSystemPackages() {
- 507 // First, update the system package map with new package names
- 508 String[] names = getSystemPackages0();
- 509 synchronized (pkgs) {
- 510 for (int i = 0; i < names.length; i++) {
- 511 defineSystemPackage(names[i], getSystemPackage0(names[i]));
- 512 }
- 513 return (Package[])pkgs.values().toArray(new Package[pkgs.size()]);
- 514 }
- 515 }
- 516
- 517 private static Package defineSystemPackage(final String iname,
- 518 final String fn)
- 519 {
- 520 return (Package) AccessController.doPrivileged(new PrivilegedAction() {
- 521 public Object run() {
- 522 String name = iname;
- 523 // Get the cached code source url for the file name
- 524 URL url = (URL)urls.get(fn);
- 525 if (url == null) {
- 526 // URL not found, so create one
- 527 File file = new File(fn);
- 528 try {
- 529 url = ParseUtil.fileToEncodedURL(file);
- 530 } catch (MalformedURLException e) {
- 531 }
- 532 if (url != null) {
- 533 urls.put(fn, url);
- 534 // If loading a JAR file, then also cache the manifest
- 535 if (file.isFile()) {
- 536 mans.put(fn, loadManifest(fn));
- 537 }
- 538 }
- 539 }
- 540 // Convert to "."-separated package name
- 541 name = name.substring(0, name.length() - 1).replace('/', '.');
- 542 Package pkg;
- 543 Manifest man = (Manifest)mans.get(fn);
- 544 if (man != null) {
- 545 pkg = new Package(name, man, url, null);
- 546 } else {
- 547 pkg = new Package(name, null, null, null,
- 548 null, null, null, null, null);
- 549 }
- 550 pkgs.put(name, pkg);
- 551 return pkg;
- 552 }
- 553 });
- 554 }
- 555
- 556 /*
- 557 * Returns the Manifest for the specified JAR file name.
- 558 */
- 559 private static Manifest loadManifest(String fn) {
- 560 try {
- 561 FileInputStream fis = new FileInputStream(fn);
- 562 JarInputStream jis = new JarInputStream(fis, false);
- 563 Manifest man = jis.getManifest();
- 564 jis.close();
- 565 return man;
- 566 } catch (IOException e) {
- 567 return null;
- 568 }
- 569 }
- 570
- 571 // The map of loaded system packages
- 572 private static Map pkgs = new HashMap(31);
- 573
- 574 // Maps each directory or zip file name to its corresponding url
- 575 private static Map urls = new HashMap(10);
- 576
- 577 // Maps each code source url for a jar file to its manifest
- 578 private static Map mans = new HashMap(10);
- 579
- 580 private static native String getSystemPackage0(String name);
- 581 private static native String[] getSystemPackages0();
- 582
- 583 /*
- 584 * Private storage for the package name and attributes.
- 585 */
- 586 private final String pkgName;
- 587 private final String specTitle;
- 588 private final String specVersion;
- 589 private final String specVendor;
- 590 private final String implTitle;
- 591 private final String implVersion;
- 592 private final String implVendor;
- 593 private final URL sealBase;
- 594 private transient final ClassLoader loader;
- 595 private transient Class packageInfo;
- 596}
