org.eclipse.emf.common.archive
Class ArchiveURLConnection

java.lang.Object
  extended byjava.net.URLConnection
      extended byorg.eclipse.emf.common.archive.ArchiveURLConnection
Direct Known Subclasses:
URIConverterImpl.Archive

public class ArchiveURLConnection
extends URLConnection

A connection that can access an entry in an archive, and then recursively an entry in that archive, and so on. For example, it can be used just like jar: or zip:, only the archive paths can repeat, e.g.,

  archive:file:///c:/temp/example.zip!/org/example/nested.zip!/org/example/deeply-nested.html
The general recursive pattern is
  archive:$nestedURL${/!$archivePath$}+
So the nested URL for the example above is
  file:///c:/temp/example.zip

Since the nested URL may itself contain archive schemes, the subsequence of the archive paths that should be associated with the nested URL is determined by finding the nth archive separator, i.e., the nth !/, where n is the number of ":"s before the first "/" of the nested URL, i.e., the number of nested schemes. For example, for a more complex case where the nested URL is itself an archive-based scheme, e.g.,

  archive:jar:file:///c:/temp/example.zip!/org/example/nested.zip!/org/example/deeply-nested.html
the nested URL is correctly parsed to skip to the second archive separator as
  jar:file:///c:/temp/example.zip!/org/example/nested.zip

The logic for accessing archives can be tailored and reused independant from its usage as a URL connection. This is normally done by using the constructor ArchiveURLConnection(String) and overriding createInputStream(String) and createOutputStream(String). The behavior can be tailored by overriding emulateArchiveScheme() and useZipFile().


Field Summary
protected  String urlString
          The cached string version of the URL.
 
Fields inherited from class java.net.URLConnection
allowUserInteraction, connected, doInput, doOutput, ifModifiedSince, url, useCaches
 
Constructor Summary
protected ArchiveURLConnection(String url)
          Constructs a new archive accessor.
  ArchiveURLConnection(URL url)
          Constructs a new connection for the URL.
 
Method Summary
 void connect()
          Record that this is connected.
protected  InputStream createInputStream(String nestedURL)
          Creates an input stream for the nested URL by calling URL#openStream()opening a stream on it.
protected  OutputStream createOutputStream(String nestedURL)
          Creates an input stream for the nested URL by calling URL#openStream()opening a stream on it.
protected  boolean emulateArchiveScheme()
           Returns whether the implementation will handle all the archive accessors directly.
 InputStream getInputStream()
          Creates the input stream for the URL.
 OutputStream getOutputStream()
          Creates the output stream for the URL.
protected  boolean useZipFile()
          Returns whether to handle the special case of a nested URL with file: schema using a ZipFile.
 
Methods inherited from class java.net.URLConnection
addRequestProperty, getAllowUserInteraction, getContent, getContent, getContentEncoding, getContentLength, getContentType, getDate, getDefaultAllowUserInteraction, getDefaultRequestProperty, getDefaultUseCaches, getDoInput, getDoOutput, getExpiration, getFileNameMap, getHeaderField, getHeaderField, getHeaderFieldDate, getHeaderFieldInt, getHeaderFieldKey, getHeaderFields, getIfModifiedSince, getLastModified, getPermission, getRequestProperties, getRequestProperty, getURL, getUseCaches, guessContentTypeFromName, guessContentTypeFromStream, setAllowUserInteraction, setContentHandlerFactory, setDefaultAllowUserInteraction, setDefaultRequestProperty, setDefaultUseCaches, setDoInput, setDoOutput, setFileNameMap, setIfModifiedSince, setRequestProperty, setUseCaches, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

urlString

protected String urlString
The cached string version of the URL.

Constructor Detail

ArchiveURLConnection

public ArchiveURLConnection(URL url)
Constructs a new connection for the URL.

Parameters:
url - the URL of this connection.

ArchiveURLConnection

protected ArchiveURLConnection(String url)
Constructs a new archive accessor. This constructor forwards a null URL to be super constructor, so an instance built with this constructor cannot be used as a URLConnection. The logic for accessing archives and for delegating to the nested URL can be reused in other applications, without creating an URLs.

Parameters:
url - the URL of the archive.
Method Detail

emulateArchiveScheme

protected boolean emulateArchiveScheme()

Returns whether the implementation will handle all the archive accessors directly. For example, whether
  archive:jar:file:///c:/temp/example.zip!/org/example/nested.zip!/org/example/deeply-nested.html
will be handled as if it were specified as
  archive:file:///c:/temp/example.zip!/org/example/nested.zip!/org/example/deeply-nested.html
Override this only if you are reusing the logic of retrieving an input stream into an archive and hence are likely to be overriding createInputStream, which is the point of delegation to the nested URL for recursive stream creation.

Returns:
whether the implementation will handle all the archive accessors directly.

useZipFile

protected boolean useZipFile()
Returns whether to handle the special case of a nested URL with file: schema using a ZipFile. This gives more efficient direct access to the root entry, e.g.,
  archive:file:///c:/temp/example.zip!/org/example/nested.html

Returns:
whether to handle the special case of a nested URL with file: schema using a ZipFile.

connect

public void connect()
             throws IOException
Record that this is connected.

Throws:
IOException

getInputStream

public InputStream getInputStream()
                           throws IOException
Creates the input stream for the URL.

Returns:
the input stream for the URL.
Throws:
IOException

createInputStream

protected InputStream createInputStream(String nestedURL)
                                 throws IOException
Creates an input stream for the nested URL by calling URL#openStream()opening a stream on it.

Parameters:
nestedURL - the nested URL for which a stream is required.
Returns:
the open stream of the nested URL.
Throws:
IOException

getOutputStream

public OutputStream getOutputStream()
                             throws IOException
Creates the output stream for the URL.

Returns:
the output stream for the URL.
Throws:
IOException

createOutputStream

protected OutputStream createOutputStream(String nestedURL)
                                   throws IOException
Creates an input stream for the nested URL by calling URL#openStream()opening a stream on it.

Parameters:
nestedURL - the nested URL for which a stream is required.
Returns:
the open stream of the nested URL.
Throws:
IOException

Copyright 2001-2006 IBM Corporation and others.
All Rights Reserved.