1 /*
   2  * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.net;
  27 
  28 import java.io.IOException;
  29 import java.util.jar.JarFile;
  30 import java.util.jar.JarEntry;
  31 import java.util.jar.Attributes;
  32 import java.util.jar.Manifest;
  33 import java.security.Permission;
  34 import sun.net.www.ParseUtil;
  35 
  36 /**
  37  * A URL Connection to a Java ARchive (JAR) file or an entry in a JAR
  38  * file.
  39  *
  40  * <p>The syntax of a JAR URL is:
  41  *
  42  * <pre>
  43  * jar:&lt;url&gt;!/{entry}
  44  * </pre>
  45  *
  46  * <p>for example:
  47  *
  48  * <p>{@code jar:http://www.foo.com/bar/baz.jar!/COM/foo/Quux.class}
  49  *
  50  * <p>Jar URLs should be used to refer to a JAR file or entries in
  51  * a JAR file. The example above is a JAR URL which refers to a JAR
  52  * entry. If the entry name is omitted, the URL refers to the whole
  53  * JAR file:
  54  *
  55  * {@code jar:http://www.foo.com/bar/baz.jar!/}
  56  *
  57  * <p>Users should cast the generic URLConnection to a
  58  * JarURLConnection when they know that the URL they created is a JAR
  59  * URL, and they need JAR-specific functionality. For example:
  60  *
  61  * <pre>
  62  * URL url = new URL("jar:file:/home/duke/duke.jar!/");
  63  * JarURLConnection jarConnection = (JarURLConnection)url.openConnection();
  64  * Manifest manifest = jarConnection.getManifest();
  65  * </pre>
  66  *
  67  * <p>JarURLConnection instances can only be used to read from JAR files.
  68  * It is not possible to get a {@link java.io.OutputStream} to modify or write
  69  * to the underlying JAR file using this class.
  70  * <p>Examples:
  71  *
  72  * <dl>
  73  *
  74  * <dt>A Jar entry
  75  * <dd>{@code jar:http://www.foo.com/bar/baz.jar!/COM/foo/Quux.class}
  76  *
  77  * <dt>A Jar file
  78  * <dd>{@code jar:http://www.foo.com/bar/baz.jar!/}
  79  *
  80  * <dt>A Jar directory
  81  * <dd>{@code jar:http://www.foo.com/bar/baz.jar!/COM/foo/}
  82  *
  83  * </dl>
  84  *
  85  * <p>{@code !/} is referred to as the <em>separator</em>.
  86  *
  87  * <p>When constructing a JAR url via {@code new URL(context, spec)},
  88  * the following rules apply:
  89  *
  90  * <ul>
  91  *
  92  * <li>if there is no context URL and the specification passed to the
  93  * URL constructor doesn't contain a separator, the URL is considered
  94  * to refer to a JarFile.
  95  *
  96  * <li>if there is a context URL, the context URL is assumed to refer
  97  * to a JAR file or a Jar directory.
  98  *
  99  * <li>if the specification begins with a '/', the Jar directory is
 100  * ignored, and the spec is considered to be at the root of the Jar
 101  * file.
 102  *
 103  * <p>Examples:
 104  *
 105  * <dl>
 106  *
 107  * <dt>context: <b>jar:http://www.foo.com/bar/jar.jar!/</b>,
 108  * spec:<b>baz/entry.txt</b>
 109  *
 110  * <dd>url:<b>jar:http://www.foo.com/bar/jar.jar!/baz/entry.txt</b>
 111  *
 112  * <dt>context: <b>jar:http://www.foo.com/bar/jar.jar!/baz</b>,
 113  * spec:<b>entry.txt</b>
 114  *
 115  * <dd>url:<b>jar:http://www.foo.com/bar/jar.jar!/baz/entry.txt</b>
 116  *
 117  * <dt>context: <b>jar:http://www.foo.com/bar/jar.jar!/baz</b>,
 118  * spec:<b>/entry.txt</b>
 119  *
 120  * <dd>url:<b>jar:http://www.foo.com/bar/jar.jar!/entry.txt</b>
 121  *
 122  * </dl>
 123  *
 124  * </ul>
 125  *
 126  * <p>Subclasses of {@code JarURLConnection} that support multi-release JAR files
 127  * should support URLs that refer to JAR runtime versioned entries. Such a URL
 128  * is a URL referring to an entry modified to include the fragment
 129  * {@code runtime}.  Subclasses that do not support multi-release JAR files
 130  * should ignore the fragment and process such URLs as if the fragment were not
 131  * present.  For example:
 132  *
 133  * <p>{@code jar:http://www.foo.com/bar/jar.jar!/baz/entry#runtime}
 134  *
 135  * <p>For information about multi-release jar files, see the specification for
 136  * {@link JarFile}.
 137  *
 138  * @see java.net.URL
 139  * @see java.net.URLConnection
 140  *
 141  * @see java.util.jar.JarFile
 142  * @see java.util.jar.JarInputStream
 143  * @see java.util.jar.Manifest
 144  * @see java.util.zip.ZipEntry
 145  *
 146  * @author Benjamin Renaud
 147  * @since 1.2
 148  */
 149 public abstract class JarURLConnection extends URLConnection {
 150 
 151     private URL jarFileURL;
 152     private String entryName;
 153 
 154     /**
 155      * The connection to the JAR file URL, if the connection has been
 156      * initiated. This should be set by connect.
 157      */
 158     protected URLConnection jarFileURLConnection;
 159 
 160     /**
 161      * Creates the new JarURLConnection to the specified URL.
 162      * @param url the URL
 163      * @throws MalformedURLException if no legal protocol
 164      * could be found in a specification string or the
 165      * string could not be parsed.
 166      */
 167 
 168     protected JarURLConnection(URL url) throws MalformedURLException {
 169         super(url);
 170         parseSpecs(url);
 171     }
 172 
 173     /* get the specs for a given url out of the cache, and compute and
 174      * cache them if they're not there.
 175      */
 176     private void parseSpecs(URL url) throws MalformedURLException {
 177         String spec = url.getFile();
 178 
 179         int separator = spec.indexOf("!/");
 180         /*
 181          * REMIND: we don't handle nested JAR URLs
 182          */
 183         if (separator == -1) {
 184             throw new MalformedURLException("no !/ found in url spec:" + spec);
 185         }
 186 
 187         jarFileURL = new URL(spec.substring(0, separator++));
 188         entryName = null;
 189 
 190         /* if ! is the last letter of the innerURL, entryName is null */
 191         if (++separator != spec.length()) {
 192             entryName = spec.substring(separator, spec.length());
 193             entryName = ParseUtil.decode (entryName);
 194         }
 195     }
 196 
 197     /**
 198      * Returns the URL for the Jar file for this connection.
 199      *
 200      * @return the URL for the Jar file for this connection.
 201      */
 202     public URL getJarFileURL() {
 203         return jarFileURL;
 204     }
 205 
 206     /**
 207      * Return the entry name for this connection. This method
 208      * returns null if the JAR file URL corresponding to this
 209      * connection points to a JAR file and not a JAR file entry.
 210      *
 211      * @return the entry name for this connection, if any.
 212      */
 213     public String getEntryName() {
 214         return entryName;
 215     }
 216 
 217     /**
 218      * Return the JAR file for this connection.
 219      *
 220      * @return the JAR file for this connection. If the connection is
 221      * a connection to an entry of a JAR file, the JAR file object is
 222      * returned
 223      *
 224      * @exception IOException if an IOException occurs while trying to
 225      * connect to the JAR file for this connection.
 226      *
 227      * @see #connect
 228      */
 229     public abstract JarFile getJarFile() throws IOException;
 230 
 231     /**
 232      * Returns the Manifest for this connection, or null if none.
 233      *
 234      * @return the manifest object corresponding to the JAR file object
 235      * for this connection.
 236      *
 237      * @exception IOException if getting the JAR file for this
 238      * connection causes an IOException to be thrown.
 239      *
 240      * @see #getJarFile
 241      */
 242     public Manifest getManifest() throws IOException {
 243         return getJarFile().getManifest();
 244     }
 245 
 246     /**
 247      * Return the JAR entry object for this connection, if any. This
 248      * method returns null if the JAR file URL corresponding to this
 249      * connection points to a JAR file and not a JAR file entry.
 250      *
 251      * @return the JAR entry object for this connection, or null if
 252      * the JAR URL for this connection points to a JAR file.
 253      *
 254      * @exception IOException if getting the JAR file for this
 255      * connection causes an IOException to be thrown.
 256      *
 257      * @see #getJarFile
 258      * @see #getJarEntry
 259      */
 260     public JarEntry getJarEntry() throws IOException {
 261         return getJarFile().getJarEntry(entryName);
 262     }
 263 
 264     /**
 265      * Return the Attributes object for this connection if the URL
 266      * for it points to a JAR file entry, null otherwise.
 267      *
 268      * @return the Attributes object for this connection if the URL
 269      * for it points to a JAR file entry, null otherwise.
 270      *
 271      * @exception IOException if getting the JAR entry causes an
 272      * IOException to be thrown.
 273      *
 274      * @see #getJarEntry
 275      */
 276     public Attributes getAttributes() throws IOException {
 277         JarEntry e = getJarEntry();
 278         return e != null ? e.getAttributes() : null;
 279     }
 280 
 281     /**
 282      * Returns the main Attributes for the JAR file for this
 283      * connection.
 284      *
 285      * @return the main Attributes for the JAR file for this
 286      * connection.
 287      *
 288      * @exception IOException if getting the manifest causes an
 289      * IOException to be thrown.
 290      *
 291      * @see #getJarFile
 292      * @see #getManifest
 293      */
 294     public Attributes getMainAttributes() throws IOException {
 295         Manifest man = getManifest();
 296         return man != null ? man.getMainAttributes() : null;
 297     }
 298 
 299     /**
 300      * Return the Certificate object for this connection if the URL
 301      * for it points to a JAR file entry, null otherwise. This method
 302      * can only be called once
 303      * the connection has been completely verified by reading
 304      * from the input stream until the end of the stream has been
 305      * reached. Otherwise, this method will return {@code null}
 306      *
 307      * @return the Certificate object for this connection if the URL
 308      * for it points to a JAR file entry, null otherwise.
 309      *
 310      * @exception IOException if getting the JAR entry causes an
 311      * IOException to be thrown.
 312      *
 313      * @see #getJarEntry
 314      */
 315     public java.security.cert.Certificate[] getCertificates()
 316          throws IOException
 317     {
 318         JarEntry e = getJarEntry();
 319         return e != null ? e.getCertificates() : null;
 320     }
 321 }