1 /* JarURLConnection.java -- Class for manipulating remote jar files
2    Copyright (C) 1998, 2002, 2003, 2005 Free Software Foundation, Inc.
3 
4 This file is part of GNU Classpath.
5 
6 GNU Classpath is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2, or (at your option)
9 any later version.
10 
11 GNU Classpath is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14 General Public License for more details.
15 
16 You should have received a copy of the GNU General Public License
17 along with GNU Classpath; see the file COPYING.  If not, write to the
18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
19 02110-1301 USA.
20 
21 Linking this library statically or dynamically with other modules is
22 making a combined work based on this library.  Thus, the terms and
23 conditions of the GNU General Public License cover the whole
24 combination.
25 
26 As a special exception, the copyright holders of this library give you
27 permission to link this library with independent modules to produce an
28 executable, regardless of the license terms of these independent
29 modules, and to copy and distribute the resulting executable under
30 terms of your choice, provided that you also meet, for each linked
31 independent module, the terms and conditions of the license of that
32 module.  An independent module is a module which is not derived from
33 or based on this library.  If you modify this library, you may extend
34 this exception to your version of the library, but you are not
35 obligated to do so.  If you do not wish to do so, delete this
36 exception statement from your version. */
37 
38 package java.net;
39 
40 import java.io.IOException;
41 import java.security.cert.Certificate;
42 import java.util.jar.Attributes;
43 import java.util.jar.JarEntry;
44 import java.util.jar.JarFile;
45 import java.util.jar.Manifest;
46 
47 
48 /**
49  * This abstract class represents a common superclass for implementations
50  * of jar URL's.  A jar URL is a special type of URL that allows JAR
51  * files on remote systems to be accessed.  It has the form:
52  * <p>
53  * jar:&lt;standard URL pointing to jar filei&gt;!/file/within/jarfile
54  * <p> for example:
55  * <p>
56  * jar:http://www.urbanophile.com/java/foo.jar!/com/urbanophile/bar.class
57  * <p>
58  * That example URL points to the file /com/urbanophile/bar.class in the
59  * remote JAR file http://www.urbanophile.com/java/foo.jar.  The HTTP
60  * protocol is used only as an example.  Any supported remote protocol
61  * can be used.
62  * <p>
63  * This class currently works by retrieving the entire jar file into a
64  * local cache file, then performing standard jar operations on it.
65  * (At least this is true for the default protocol implementation).
66  *
67  * @author Aaron M. Renn (arenn@urbanophile.com)
68  * @author Kresten Krab Thorup (krab@gnu.org)
69  * @date Aug 10, 1999.
70  *
71  * @since 1.2
72  */
73 public abstract class JarURLConnection extends URLConnection
74 {
75   /**
76    * This is the actual URL that points the remote jar file.  This is parsed
77    * out of the jar URL by the constructor.
78    */
79   private final URL jarFileURL;
80 
81   /**
82    * The connection to the jar file itself. A JarURLConnection
83    * can represent an entry in a jar file or an entire jar file.  In
84    * either case this describes just the jar file itself.
85    */
86   protected URLConnection jarFileURLConnection;
87 
88   /**
89    * This is the jar file "entry name" or portion after the "!/" in the
90    * URL which represents the pathname inside the actual jar file.
91    */
92   private final String entryName;
93 
94   /**
95    * Creates a JarURLConnection from an URL object
96    *
97    * @param url The URL object for this connection.
98    *
99    * @exception MalformedURLException If url is invalid
100    *
101    * @specnote This constructor is protected since JDK 1.4
102    */
JarURLConnection(URL url)103   protected JarURLConnection(URL url) throws MalformedURLException
104   {
105     super(url);
106 
107     if (! url.getProtocol().equals("jar"))
108       throw new MalformedURLException(url + ": Not jar protocol.");
109 
110     String spec = url.getFile();
111     int bang = spec.indexOf("!/");
112     if (bang == -1)
113       throw new MalformedURLException(url + ": No `!/' in spec.");
114 
115     // Extract the url for the jar itself.
116     jarFileURL = new URL(spec.substring(0, bang));
117 
118     // Get the name of the entry, if any.
119     entryName = spec.length() == (bang + 2) ? null : spec.substring(bang + 2);
120   }
121 
122   /**
123    * This method returns the "real" URL where the JarFile is located.
124    * //****Is this right?*****
125    *
126    * @return The remote URL
127    */
getJarFileURL()128   public URL getJarFileURL()
129   {
130     return jarFileURL;
131   }
132 
133   /**
134    * Returns the "entry name" portion of the jar URL.  This is the portion
135    * after the "!/" in the jar URL that represents the pathname inside the
136    * actual jar file.
137    *
138    * @return The entry name.
139    */
getEntryName()140   public String getEntryName()
141   {
142     return entryName;
143   }
144 
145   /**
146    * Returns the entry in this jar file specified by the URL.
147    *
148    * @return The jar entry
149    *
150    * @exception IOException If an error occurs
151    */
getJarEntry()152   public JarEntry getJarEntry() throws IOException
153   {
154     if (entryName == null)
155       return null;
156     JarFile jarFile = getJarFile();
157     return jarFile != null ? jarFile.getJarEntry(entryName) : null;
158   }
159 
160   /**
161    * Returns a read-only JarFile object for the remote jar file
162    *
163    * @return The JarFile object
164    *
165    * @exception IOException If an error occurs
166    */
getJarFile()167   public abstract JarFile getJarFile() throws IOException;
168 
169   /**
170    * Returns an array of Certificate objects for the jar file entry specified
171    * by this URL or null if there are none
172    *
173    * @return A Certificate array
174    *
175    * @exception IOException If an error occurs
176    */
getCertificates()177   public Certificate[] getCertificates() throws IOException
178   {
179     JarEntry entry = getJarEntry();
180 
181     return entry != null ? entry.getCertificates() : null;
182   }
183 
184   /**
185    * Returns the main Attributes for the jar file specified in the URL or
186    * null if there are none
187    *
188    * @return The main Attributes for the JAR file for this connection
189    *
190    * @exception IOException If an error occurs
191    */
getMainAttributes()192   public Attributes getMainAttributes() throws IOException
193   {
194     Manifest manifest = getManifest();
195 
196     return manifest != null ? manifest.getMainAttributes() : null;
197   }
198 
199   /**
200    * Returns the Attributes for the Jar entry specified by the URL or null
201    * if none
202    *
203    * @return The Attributes object for this connection if the URL for it points
204    * to a JAR file entry, null otherwise
205    *
206    * @exception IOException If an error occurs
207    */
getAttributes()208   public Attributes getAttributes() throws IOException
209   {
210     JarEntry entry = getJarEntry();
211 
212     return entry != null ? entry.getAttributes() : null;
213   }
214 
215   /**
216    * Returns a Manifest object for this jar file, or null if there is no
217    * manifest.
218    *
219    * @return The Manifest for this connection, or null if none
220    *
221    * @exception IOException If an error occurs
222    */
getManifest()223   public Manifest getManifest() throws IOException
224   {
225     JarFile file = getJarFile();
226 
227     return file != null ? file.getManifest() : null;
228   }
229 }
230