001    /* JarURLConnection.java -- Class for manipulating remote jar files
002       Copyright (C) 1998, 2002, 2003, 2005 Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    package java.net;
039    
040    import java.io.IOException;
041    import java.security.cert.Certificate;
042    import java.util.jar.Attributes;
043    import java.util.jar.JarEntry;
044    import java.util.jar.JarFile;
045    import java.util.jar.Manifest;
046    
047    
048    /**
049     * This abstract class represents a common superclass for implementations
050     * of jar URL's.  A jar URL is a special type of URL that allows JAR
051     * files on remote systems to be accessed.  It has the form:
052     * <p>
053     * jar:&lt;standard URL pointing to jar filei&gt;!/file/within/jarfile
054     * <p> for example:
055     * <p>
056     * jar:http://www.urbanophile.com/java/foo.jar!/com/urbanophile/bar.class
057     * <p>
058     * That example URL points to the file /com/urbanophile/bar.class in the
059     * remote JAR file http://www.urbanophile.com/java/foo.jar.  The HTTP
060     * protocol is used only as an example.  Any supported remote protocol
061     * can be used.
062     * <p>
063     * This class currently works by retrieving the entire jar file into a
064     * local cache file, then performing standard jar operations on it.
065     * (At least this is true for the default protocol implementation).
066     *
067     * @author Aaron M. Renn (arenn@urbanophile.com)
068     * @author Kresten Krab Thorup (krab@gnu.org)
069     * @date Aug 10, 1999.
070     *
071     * @since 1.2
072     */
073    public abstract class JarURLConnection extends URLConnection
074    {
075      /**
076       * This is the actual URL that points the remote jar file.  This is parsed
077       * out of the jar URL by the constructor.
078       */
079      private final URL jarFileURL;
080    
081      /**
082       * The connection to the jar file itself. A JarURLConnection
083       * can represent an entry in a jar file or an entire jar file.  In
084       * either case this describes just the jar file itself.
085       */
086      protected URLConnection jarFileURLConnection;
087    
088      /**
089       * This is the jar file "entry name" or portion after the "!/" in the
090       * URL which represents the pathname inside the actual jar file.
091       */
092      private final String entryName;
093    
094      /**
095       * Creates a JarURLConnection from an URL object
096       *
097       * @param url The URL object for this connection.
098       *
099       * @exception MalformedURLException If url is invalid
100       *
101       * @specnote This constructor is protected since JDK 1.4
102       */
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       */
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       */
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       */
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       */
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       */
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       */
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       */
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       */
223      public Manifest getManifest() throws IOException
224      {
225        JarFile file = getJarFile();
226    
227        return file != null ? file.getManifest() : null;
228      }
229    }