JarURLConnection


1   /*
2    * @(#)JarURLConnection.java    1.35 06/05/16
3    *
4    * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.net;
9   
10  import java.io.IOException  ;
11  import java.util.jar.JarFile  ;
12  import java.util.jar.JarEntry  ;
13  import java.util.jar.Attributes  ;
14  import java.util.jar.Manifest  ;
15  import java.security.Permission  ;
16  import sun.net.www.ParseUtil;
17  
18  /** 
19   * A URL Connection to a Java ARchive (JAR) file or an entry in a JAR
20   * file.
21   *
22   * <p>The syntax of a JAR URL is:
23   *
24   * <pre>
25   * jar:&lt;url&gt;!/{entry}
26   * </pre>
27   *
28   * <p>for example:
29   *
30   * <p><code>
31   * jar:http://www.foo.com/bar/baz.jar!/COM/foo/Quux.class<br>
32   * </code>
33   *
34   * <p>Jar URLs should be used to refer to a JAR file or entries in 
35   * a JAR file. The example above is a JAR URL which refers to a JAR
36   * entry. If the entry name is omitted, the URL refers to the whole
37   * JAR file:
38   *
39   * <code>
40   * jar:http://www.foo.com/bar/baz.jar!/
41   * </code>
42   * 
43   * <p>Users should cast the generic URLConnection to a
44   * JarURLConnection when they know that the URL they created is a JAR
45   * URL, and they need JAR-specific functionality. For example:
46   *
47   * <pre>
48   * URL url = new URL("jar:file:/home/duke/duke.jar!/");
49   * JarURLConnection jarConnection = (JarURLConnection)url.openConnection();
50   * Manifest manifest = jarConnection.getManifest();
51   * </pre>
52   *
53   * <p>JarURLConnection instances can only be used to read from JAR files.
54   * It is not possible to get a {@link java.io.OutputStream} to modify or write 
55   * to the underlying JAR file using this class.
56   * <p>Examples:
57   * 
58   * <dl>
59   * 
60   * <dt>A Jar entry
61   * <dd><code>jar:http://www.foo.com/bar/baz.jar!/COM/foo/Quux.class</code>
62   *
63   * <dt>A Jar file
64   * <dd><code>jar:http://www.foo.com/bar/baz.jar!/</code>
65   *
66   * <dt>A Jar directory
67   * <dd><code>jar:http://www.foo.com/bar/baz.jar!/COM/foo/</code>
68   *
69   * </dl>
70   *
71   * <p><code>!/</code> is refered to as the <em>separator</em>.
72   *
73   * <p>When constructing a JAR url via <code>new URL(context, spec)</code>,
74   * the following rules apply:
75   *
76   * <ul>
77   *
78   * <li>if there is no context URL and the specification passed to the
79   * URL constructor doesn't contain a separator, the URL is considered
80   * to refer to a JarFile.
81   *
82   * <li>if there is a context URL, the context URL is assumed to refer
83   * to a JAR file or a Jar directory.
84   *
85   * <li>if the specification begins with a '/', the Jar directory is
86   * ignored, and the spec is considered to be at the root of the Jar
87   * file.
88   *
89   * <p>Examples:
90   *
91   * <dl>
92   *
93   * <dt>context: <b>jar:http://www.foo.com/bar/jar.jar!/</b>, 
94   * spec:<b>baz/entry.txt</b>
95   *
96   * <dd>url:<b>jar:http://www.foo.com/bar/jar.jar!/baz/entry.txt</b>
97   *
98   * <dt>context: <b>jar:http://www.foo.com/bar/jar.jar!/baz</b>, 
99   * spec:<b>entry.txt</b>
100  *
101  * <dd>url:<b>jar:http://www.foo.com/bar/jar.jar!/baz/entry.txt</b>
102  *
103  * <dt>context: <b>jar:http://www.foo.com/bar/jar.jar!/baz</b>, 
104  * spec:<b>/entry.txt</b>
105  *
106  * <dd>url:<b>jar:http://www.foo.com/bar/jar.jar!/entry.txt</b>
107  *
108  * </dl>
109  *
110  * </ul>
111  *
112  * @see java.net.URL
113  * @see java.net.URLConnection
114  *
115  * @see java.util.jar.JarFile
116  * @see java.util.jar.JarInputStream
117  * @see java.util.jar.Manifest
118  * @see java.util.zip.ZipEntry
119  *
120  * @author Benjamin Renaud
121  * @since 1.2 
122  */
123 public abstract class JarURLConnection extends URLConnection   {
124 
125     private URL   jarFileURL;
126     private String   entryName;
127 
128     /**
129      * The connection to the JAR file URL, if the connection has been
130      * initiated. This should be set by connect.
131      */
132     protected URLConnection   jarFileURLConnection;
133 
134     /**
135      * Creates the new JarURLConnection to the specified URL.
136      * @param url the URL 
137      * @throws MalformedURLException if no legal protocol 
138      * could be found in a specification string or the 
139      * string could not be parsed. 
140      */
141 
142     protected JarURLConnection(URL   url) throws MalformedURLException   {
143     super(url);
144     parseSpecs(url);
145     }   
146 
147     /* get the specs for a given url out of the cache, and compute and
148      * cache them if they're not there. 
149      */
150     private void parseSpecs(URL   url) throws MalformedURLException   {
151     String   spec = url.getFile();
152 
153     int separator = spec.indexOf("!/");
154     /*
155      * REMIND: we don't handle nested JAR URLs
156      */
157     if (separator == -1) {
158         throw new MalformedURLException  ("no !/ found in url spec:" + spec);
159     }
160 
161     jarFileURL = new URL  (spec.substring(0, separator++));
162     entryName = null;
163 
164     /* if ! is the last letter of the innerURL, entryName is null */
165     if (++separator != spec.length()) {
166         entryName = spec.substring(separator, spec.length());
167         entryName = ParseUtil.decode (entryName);
168     }
169     }
170 
171     /**
172      * Returns the URL for the Jar file for this connection.
173      *
174      * @return the URL for the Jar file for this connection.
175      */
176     public URL   getJarFileURL() {
177     return jarFileURL;
178     }
179 
180     /**   
181      * Return the entry name for this connection. This method
182      * returns null if the JAR file URL corresponding to this
183      * connection points to a JAR file and not a JAR file entry.
184      *
185      * @return the entry name for this connection, if any.  
186      */
187     public String   getEntryName() {
188     return entryName;
189     }
190 
191     /**   
192      * Return the JAR file for this connection. 
193      *
194      * @return the JAR file for this connection. If the connection is
195      * a connection to an entry of a JAR file, the JAR file object is
196      * returned
197      *
198      * @exception IOException if an IOException occurs while trying to
199      * connect to the JAR file for this connection.
200      *
201      * @see #connect
202      */
203     public abstract JarFile   getJarFile() throws IOException  ;
204 
205     /**
206      * Returns the Manifest for this connection, or null if none.
207      *
208      * @return the manifest object corresponding to the JAR file object
209      * for this connection.
210      *
211      * @exception IOException if getting the JAR file for this
212      * connection causes an IOException to be trown.
213      *
214      * @see #getJarFile
215      */
216     public Manifest   getManifest() throws IOException   {
217     return getJarFile().getManifest();
218     }
219         
220     /**  
221      * Return the JAR entry object for this connection, if any. This
222      * method returns null if the JAR file URL corresponding to this
223      * connection points to a JAR file and not a JAR file entry.
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      * Return the Certificate object for this connection if the URL
275      * for it points to a JAR file entry, null otherwise. This method 
276      * can only be called once
277      * the connection has been completely verified by reading
278      * from the input stream until the end of the stream has been
279      * reached. Otherwise, this method will return <code>null</code>
280      * 
281      * @return the Certificate object for this connection if the URL
282      * for it points to a JAR file entry, null otherwise.  
283      *
284      * @exception IOException if getting the JAR entry causes an
285      * IOException to be thrown.
286      *
287      * @see #getJarEntry
288      */
289     public java.security.cert.Certificate  [] getCertificates()
290      throws IOException  
291     {
292     JarEntry   e = getJarEntry();
293     return e != null ? e.getCertificates() : null;
294     }
295 }
296 
297 
298 
299 
300 
301 
302
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags