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