home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / net / JarURLConnection.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  8.7 KB  |  303 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)JarURLConnection.java    1.17 98/06/16
  3.  *
  4.  * Copyright 1997, 1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.net;
  16.  
  17. import java.io.IOException;
  18. import java.util.jar.JarFile;
  19. import java.util.jar.JarEntry;
  20. import java.util.jar.Attributes;
  21. import java.util.jar.Manifest;
  22. import java.security.Permission;
  23.  
  24. /** 
  25.  * A URL Connection to a Java ARchive (JAR) file or an entry in a JAR
  26.  * file.
  27.  *
  28.  * <p>The syntax of a JAR URL is:
  29.  *
  30.  * <pre>
  31.  * jar:<url>!/{entry}
  32.  * </pre>
  33.  *
  34.  * <p>for example:
  35.  *
  36.  * <p><code>
  37.  * jar:http://www.foo.com/bar/baz.jar!/COM/foo/Quux.class<br>
  38.  * </code>
  39.  *
  40.  * <p>Jar URLs should be used to either refer to single JAR entries or
  41.  * as base URLs, to refer to JAR files as codebases, or relative
  42.  * URLs. The example above is a full JAR URL, which refers to a JAR
  43.  * entry. If the entry name is omitted, the URL refers to the whole
  44.  * JAR file:
  45.  *
  46.  * <code>
  47.  * jar:http://www.foo.com/bar/baz.jar!/
  48.  * </code>
  49.  * 
  50.  * <p>Users should cast the generic URLConnection to a
  51.  * JarURLConnection when they know that the URL they created is a JAR
  52.  * URL, and they need JAR-specific functionality. For example:
  53.  *
  54.  * <code>
  55.  * URL url = new URL("jar:file:/home/duke/duke.jar!/");
  56.  * JarURLConnection jarConnection = (JarURLConnection)url.openConnection();
  57.  * Manifest manifest = jarConnection.getManifest();
  58.  * </code>
  59.  *
  60.  * <p>Examples:
  61.  * 
  62.  * <dl>
  63.  * 
  64.  * <dt>A Jar entry
  65.  * <dd><code>jar:http://www.foo.com/bar/baz.jar!/COM/foo/Quux.class</code>
  66.  *
  67.  * <dt>A Jar file
  68.  * <dd><code>jar:http://www.foo.com/bar/baz.jar!/</code>
  69.  *
  70.  * <dt>A Jar directory
  71.  * <dd><code>jar:http://www.foo.com/bar/baz.jar!/COM/foo/</code>
  72.  *
  73.  * </dl>
  74.  *
  75.  * <p><code>!/</code> is refered to as the <em>separator</em>.
  76.  *
  77.  * <p>When constructing a JAR url, the following rules apply:
  78.  *
  79.  * <ul>
  80.  *
  81.  * <li>if there is no context URL and the specification passed to the
  82.  * URL constructor doesn't contains a separator, the URL is considered
  83.  * to refer to a JarFile.
  84.  *
  85.  * <li>if there is a context URL, the context URL is assumed to refer
  86.  * to a JAR file or a Jar directory.
  87.  *
  88.  * <li>if the specification begins with a '/', the Jar directory is
  89.  * ignored, and the spec is considered to be at the root of the Jar
  90.  * file.
  91.  *
  92.  * <p>Examples:
  93.  *
  94.  * <dt>context: <b>jar:http://www.foo.com/bar/jar.jar!/</b>, 
  95.  * spec:<b>baz/entry.txt<b>
  96.  *
  97.  * <dd>url:<b>jar:http://www.foo.com/bar/baz/jar.jar!/baz/entry.txt<b>
  98.  *
  99.  * <dt>context: <b>jar:http://www.foo.com/bar/jar.jar!/baz</b>, 
  100.  * spec:<b>entry.txt<b>
  101.  *
  102.  * <dd>url:<b>jar:http://www.foo.com/bar/baz/jar.jar!/baz/entry.txt<b>
  103.  *
  104.  * <dt>context: <b>jar:http://www.foo.com/bar/jar.jar!/baz</b>, 
  105.  * spec:<b>/entry.txt<b>
  106.  *
  107.  * <dd>url:<b>jar:http://www.foo.com/bar/baz/jar.jar!/entry.txt<b>
  108.  *
  109.  * </dl>
  110.  *
  111.  * </ul>
  112.  *
  113.  * @see java.net.URL
  114.  * @see java.net.URLConnection
  115.  *
  116.  * @see java.util.jar.JarFile
  117.  * @see java.util.jar.JarInputStream
  118.  * @see java.util.jar.Manifest
  119.  * @see java.util.zip.ZipEntry
  120.  *
  121.  * @author Benjamin Renaud
  122.  * @since JDK1.2 
  123.  */
  124. public abstract class JarURLConnection extends URLConnection {
  125.  
  126.     private URL jarFileURL;
  127.     private String entryName;
  128.  
  129.     /**
  130.      * The connection to the JAR file URL, if the connection has been
  131.      * initiated. This should be set by connect.
  132.      */
  133.     protected URLConnection jarFileURLConnection;
  134.  
  135.     protected JarURLConnection(URL url) throws MalformedURLException {
  136.     super(url);
  137.     parseSpecs(url);
  138.     }    
  139.  
  140.     /* get the specs for a given url out of the cache, and compute and
  141.      * cache them if they're not there. 
  142.      */
  143.     private void parseSpecs(URL url) throws MalformedURLException {
  144.     String spec = url.getFile();
  145.  
  146.     int separator = spec.indexOf('!');
  147.     /*
  148.      * REMIND: we don't handle nested JAR URLs
  149.      */
  150.     if (separator == -1) {
  151.         throw new MalformedURLException("no ! found in url spec:" + spec);
  152.     }
  153.  
  154.     jarFileURL = new URL(spec.substring(0, separator++));
  155.     entryName = null;
  156.  
  157.     /* if ! is the last letter of the innerURL, entryName is null */
  158.     if (++separator != spec.length()) {
  159.         entryName = spec.substring(separator, spec.length());
  160.     }
  161.     }
  162.  
  163.     /**
  164.      * Returns the URL for the Jar file for this connection.
  165.      *
  166.      * @return the URL for the Jar file for this connection.
  167.      */
  168.     public URL getJarFileURL() {
  169.     return jarFileURL;
  170.     }
  171.  
  172.     /**   
  173.      * Return the entry name for this connection. This method
  174.      * returns null if the JAR file URL corresponding to this
  175.      * connection points to a JAR file and not a JAR file entry.
  176.      *
  177.      * @return the entry name for this connection, if any.  
  178.      */
  179.     public String getEntryName() {
  180.     return entryName;
  181.     }
  182.  
  183.     /**   
  184.      * Return the JAR file for this connection. The returned object is
  185.      * not modifiable, and will throw UnsupportedOperationException
  186.      * if the caller attempts to modify it.
  187.      *
  188.      * @return the JAR file for this connection. If the connection is
  189.      * a connection to an entry of a JAR file, the JAR file object is
  190.      * returned
  191.      *
  192.      * @exception IOException if an IOException occurs while trying to
  193.      * connect to the JAR file for this connection.
  194.      *
  195.      * @see #connect
  196.      */
  197.     public abstract JarFile getJarFile() throws IOException;
  198.  
  199.     /**
  200.      * Returns the Manifest for this connection, or null if none. The
  201.      * returned object is not modifiable, and will throw
  202.      * UnsupportedOperationException if the caller attempts to modify
  203.      * it.
  204.      *
  205.      * @return the manifest object corresponding to the JAR file object
  206.      * for this connection.
  207.      *
  208.      * @exception IOException if getting the JAR file for this
  209.      * connection causes an IOException to be trown.
  210.      *
  211.      * @see #getJarFile
  212.      */
  213.     public Manifest getManifest() throws IOException {
  214.     return getJarFile().getManifest();
  215.     }
  216.         
  217.     /**  
  218.      * Return the JAR entry object for this connection, if any. This
  219.      * method returns null if the JAR file URL corresponding to this
  220.      * connection points to a JAR file and not a JAR file entry. The
  221.      * returned object is not modifiable, and will throw
  222.      * UnsupportedOperationException if the caller attempts to modify
  223.      * it.  
  224.      *
  225.      * @return the JAR entry object for this connection, or null if
  226.      * the JAR URL for this connection points to a JAR file.
  227.      *
  228.      * @exception IOException if getting the JAR file for this
  229.      * connection causes an IOException to be trown.
  230.      *
  231.      * @see #getJarFile
  232.      * @see #getJarEntry
  233.      */
  234.     public JarEntry getJarEntry() throws IOException {
  235.     return getJarFile().getJarEntry(entryName);
  236.     }
  237.  
  238.     /**
  239.      * Return the Attributes object for this connection if the URL
  240.      * for it points to a JAR file entry, null otherwise.
  241.      * 
  242.      * @return the Attributes object for this connection if the URL
  243.      * for it points to a JAR file entry, null otherwise.  
  244.      *
  245.      * @exception IOException if getting the JAR entry causes an
  246.      * IOException to be thrown.
  247.      *
  248.      * @see #getJarEntry
  249.      */
  250.     public Attributes getAttributes() throws IOException {
  251.     JarEntry e = getJarEntry();
  252.     return e != null ? e.getAttributes() : null;
  253.     }
  254.   
  255.     /**    
  256.      * Returns the main Attributes for the JAR file for this
  257.      * connection.
  258.      *
  259.      * @return the main Attributes for the JAR file for this
  260.      * connection.
  261.      *
  262.      * @exception IOException if getting the manifest causes an
  263.      * IOException to be thrown.
  264.      *
  265.      * @see #getJarFile
  266.      * @see #getManifest 
  267.      */
  268.     public Attributes getMainAttributes() throws IOException { 
  269.     Manifest man = getManifest();
  270.     return man != null ? man.getMainAttributes() : null;
  271.     }
  272.    
  273.     /**
  274.     /**
  275.      * Return the Certificate object for this connection if the URL
  276.      * for it points to a JAR file entry, null otherwise. This method 
  277.      * can only be called once
  278.      * the connection has been completely verified by reading
  279.      * from the input stream until the end of the stream has been
  280.      * reached. Otherwise, this method will return <code>null</code>
  281.      * 
  282.      * @return the Certificate object for this connection if the URL
  283.      * for it points to a JAR file entry, null otherwise.  
  284.      *
  285.      * @exception IOException if getting the JAR entry causes an
  286.      * IOException to be thrown.
  287.      *
  288.      * @see #getJarEntry
  289.      */
  290.     public java.security.cert.Certificate[] getCertificates()
  291.      throws IOException
  292.     {
  293.     JarEntry e = getJarEntry();
  294.     return e != null ? e.getCertificates() : null;
  295.     }
  296. }
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.