## org.eclipse.emf.common.archive
Class ArchiveURLConnection

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

Direct Known Subclasses:
  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.
`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.
`java.io.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, 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`

### 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`

### 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`

### 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`

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