org.eclipse.emf.common.archive
Class ArchiveURLConnection

java.lang.Object
  java.net.URLConnection
      org.eclipse.emf.common.archive.ArchiveURLConnection

Direct Known Subclasses:

ArchiveURIHandlerImpl.Archive, URIConverterImpl.Archive

public class ArchiveURLConnection
extends java.net.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 java.lang.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(java.lang.String url) Constructs a new archive accessor.
	ArchiveURLConnection(java.net.URL url) Constructs a new connection for the URL.

Method Summary

void	connect() Record that this is connected.
protected java.io.InputStream	createInputStream(java.lang.String nestedURL) Creates an input stream for the nested URL by calling opening a stream on it.
protected java.io.OutputStream	createOutputStream(java.lang.String nestedURL) Creates an output stream for the nested URL by calling opening a stream on it.
void	delete()
protected boolean	emulateArchiveScheme() Returns whether the implementation will handle all the archive accessors directly.
java.io.InputStream	getInputStream() Creates the input stream for the URL.
protected java.lang.String	getNestedURL()
java.io.OutputStream	getOutputStream() Creates the output stream for the URL.
void	setTimeStamp(long timeStamp)
protected boolean	useZipFile() Returns whether to handle the special case of a nested URL with file: schema using a ZipFile.
protected java.io.InputStream	yield(java.util.zip.ZipEntry zipEntry, java.io.InputStream inputStream)
protected java.io.OutputStream	yield(java.util.zip.ZipEntry zipEntry, java.io.OutputStream outputStream)

Methods inherited from class java.net.URLConnection

addRequestProperty, getAllowUserInteraction, getConnectTimeout, getContent, getContent, getContentEncoding, getContentLength, getContentType, getDate, getDefaultAllowUserInteraction, getDefaultRequestProperty, getDefaultUseCaches, getDoInput, getDoOutput, getExpiration, getFileNameMap, getHeaderField, getHeaderField, getHeaderFieldDate, getHeaderFieldInt, getHeaderFieldKey, getHeaderFields, getIfModifiedSince, getLastModified, getPermission, getReadTimeout, getRequestProperties, getRequestProperty, getURL, getUseCaches, guessContentTypeFromName, guessContentTypeFromStream, setAllowUserInteraction, setConnectTimeout, setContentHandlerFactory, setDefaultAllowUserInteraction, setDefaultRequestProperty, setDefaultUseCaches, setDoInput, setDoOutput, setFileNameMap, setIfModifiedSince, setReadTimeout, setRequestProperty, setUseCaches, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

urlString

protected java.lang.String urlString

The cached string version of the URL.

Constructor Detail

ArchiveURLConnection

public ArchiveURLConnection(java.net.URL url)

Constructs a new connection for the URL.

Parameters:

url - the URL of this connection.

ArchiveURLConnection

protected ArchiveURLConnection(java.lang.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 java.io.IOException

Record that this is connected.

Specified by:

connect in class java.net.URLConnection

Throws:

java.io.IOException

getNestedURL

protected java.lang.String getNestedURL()
                                 throws java.io.IOException

Throws:

java.io.IOException

getInputStream

public java.io.InputStream getInputStream()
                                   throws java.io.IOException

Creates the input stream for the URL.

Overrides:

getInputStream in class java.net.URLConnection

Returns:

the input stream for the URL.

Throws:

java.io.IOException

yield

protected java.io.InputStream yield(java.util.zip.ZipEntry zipEntry,
                                    java.io.InputStream inputStream)
                             throws java.io.IOException

Throws:

java.io.IOException

createInputStream

protected java.io.InputStream createInputStream(java.lang.String nestedURL)
                                         throws java.io.IOException

Creates an input stream for the nested URL by calling 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:

java.io.IOException

getOutputStream

public java.io.OutputStream getOutputStream()
                                     throws java.io.IOException

Creates the output stream for the URL.

Overrides:

getOutputStream in class java.net.URLConnection

Returns:

the output stream for the URL.

Throws:

java.io.IOException

delete

public void delete()
            throws java.io.IOException

Throws:

java.io.IOException

setTimeStamp

public void setTimeStamp(long timeStamp)
                  throws java.io.IOException

Throws:

java.io.IOException

yield

protected java.io.OutputStream yield(java.util.zip.ZipEntry zipEntry,
                                     java.io.OutputStream outputStream)
                              throws java.io.IOException

Throws:

java.io.IOException

createOutputStream

protected java.io.OutputStream createOutputStream(java.lang.String nestedURL)
                                           throws java.io.IOException

Creates an output stream for the nested URL by calling 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:

java.io.IOException