JarURLConnection

One of the simplest ways to get information from a JAR file is through the java.net.JarURLConnection class. This class represents an active connection to a JAR file, generally via either the HTTP or file protocols.

public abstract class JarURLConnection extends URLConnection

It provides methods to get the URL, name, manifest, JAR entries, attributes, and certificates associated with the JAR file and its entries. The only constructor in this class is protected. As with most URLConnection subclasses, you don't instantiate JarURLConnection directly. Instead, you create a URL object using the string form of a JAR URL and invoke its openConnection( ) method. For example:

URL u = new URL( "jar:http://www.oreilly.com/javaio.jar!/com/elharo/io/StreamCopier.class"); URLConnection juc = u.openConnection( ); // ...

Notice the strange URL. A JAR URL is like a normal HTTP or file URL pointing to a JAR file, with the prefix "jar:" added to the URL's scheme (i.e., jar:http: or jar:file:). After the hostname, you place the path to the JAR file on the server. After the JAR filename, you add an exclamation point and a path to the particular entry you want within the JAR archive. For example, to refer to the file StreamCopier.class in the com/elharo/io directory of the JAR file javaio.jar located at http://www.oreilly.com/, you would use the JAR URL jar:http://www.oreilly.com/javaio.jar!/com/elharo/io/StreamCopier.class. If the entry is omitted, the URL refers to the JAR archive as a whole (for example, jar:http://www.oreilly.com/javaio.jar!/).

If you only want to read data from the connection using getInputStream( ) from the URLConnection superclass, the previous code will suffice. If you want to use the methods of the JarURLConnection class directly, you should cast the object returned from openConnection( ) to JarURLConnection. For example:

URL u = new URL( "jar:http://www.oreilly.com/javaio.jar!/com/elharo/io/StreamCopier.class"); JarURLConnection juc = (JarURLConnection) u.openConnection( ); // ...

Once you've done this, you can use eight methods that provide easy access to various meta-information about the JAR file and its contents. This meta-information comes from the archive's manifest or certificate files. The getJarFileURL( ) method returns the URL of the JAR file for this connection:

public URL getJarFileURL( )

This is most useful if the URL refers to a particular entry in the file. In that instance, the URL returned by getJarFileURL( ) refers to the URL of the archive. For example:

URL u = new URL( "jar:http://www.oreilly.com/javaio.jar!/com/elharo/io/StreamCopier.class"); JarURLConnection juc = (JarURLConnection) u.openConnection( ); URL base = juc.getURL( );

The URL object base now refers to http://www.oreilly.com/javaio.jar.

The getEntryName( ) method returns the name of the JAR entry referred to by this JAR URL:

public String getEntryName( )

It returns null if the JAR URL points to a JAR file as a whole rather than to one of the entries in the file.

The getJarFile( ) method returns an immutable JarFile object for the JAR archive referred to by this URL:

public abstract JarFile getJarFile( ) throws IOException

You can read the state of this object, but you cannot change it. Attempts to do so throw a java.lang.UnsupportedOperationException. This is a runtime exception, so you do not have to catch it.

The getJarEntry( ) method returns an immutable JarEntry object for the JAR entry referred to by this URL:

public JarEntry getJarEntry( ) throws IOException

You can read the state of this object, but you cannot change it. Attempts to do so throw a java.lang.UnsupportedOperationException .

The getManifest( ) method returns an immutable Manifest object constructed from the manifest file in the JAR archive:

public Manifest getManifest( ) throws IOException

It returns null if the archive doesn't have a manifest. Again, you cannot modify this Manifest object, and any attempt to do so will throw an UnsupportedOperationException.

The getAttributes( ) method returns an Attributes object representing the attributes of the JAR entry referred to by this URL:

public Attributes getAttributes( ) throws IOException public Attributes getMainAttributes( ) throws IOException

It returns null if the URL refers to a JAR file rather than a particular entry. To get the attributes of the entire archive, use the getMainAttributes( ) method instead.

Finally, the getCertificates( ) method returns an array of java.security.cert.Certificate objects containing the certificates for the JAR entry referred to by this URL (if any):

public Certificate[] getCertificates( ) throws IOException

This method returns null if the URL refers to a JAR file rather than a JAR entry.