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