org.apache.felix.framework.cache

## Class BundleArchive

- java.lang.Object
- - org.apache.felix.framework.cache.BundleArchive

    public class BundleArchive
    extends Object

This class is a logical abstraction for a bundle archive. This class, combined with `BundleCache` and concrete `BundleRevision` subclasses, implement the bundle cache for Felix. The bundle archive abstracts the actual bundle content into revisions and the revisions provide access to the actual bundle content. When a bundle is installed it has one revision associated with its content. Updating a bundle adds another revision for the updated content. Any number of revisions can be associated with a bundle archive. When the bundle (or framework) is refreshed, then all old revisions are purged and only the most recent revision is maintained.

The content associated with a revision can come in many forms, such as a standard JAR file or an exploded bundle directory. The bundle archive is responsible for creating all revision instances during invocations of the `revise()` method call. Internally, it determines the concrete type of revision type by examining the location string as an URL. Currently, it supports standard JAR files, referenced JAR files, and referenced directories. Examples of each type of URL are, respectively:

- `http://www.foo.com/bundle.jar`
- `reference:file:/foo/bundle.jar`
- `reference:file:/foo/bundle/`

The "`reference:`" notation signifies that the resource should be used "in place", meaning that they will not be copied. For referenced JAR files, some resources may still be copied, such as embedded JAR files or native libraries, but for referenced exploded bundle directories, nothing will be copied. Currently, reference URLs can only refer to "file:" targets.

See Also:
  `BundleCache`

### Field Summary

Fields
`static String` `FILE_PROTOCOL`
`static String` `INPUTSTREAM_PROTOCOL`
`static String` `REFERENCE_PROTOCOL`

### Constructor Summary

Constructors
Constructor and Description
`BundleArchive(Logger logger, Map configMap, WeakZipFileFactory zipFactory, File archiveRootDir)` This constructor is called when an archive for a bundle is being reconstructed when the framework is restarted.
`BundleArchive(Logger logger, Map configMap, WeakZipFileFactory zipFactory, File archiveRootDir, long id, int startLevel, String location, InputStream is)` This constructor is used for creating new archives when a bundle is installed into the framework.

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `close()`
`void` `closeAndDelete()` This method closes any revisions and deletes the bundle archive directory.
`BundleArchiveRevision` `getCurrentRevision()` Returns the current revision object for the archive.
`Long` `getCurrentRevisionNumber()` Returns the current revision object for the archive.
`File` `getDataFile(String fileName)` Returns a `File` object corresponding to the data file of the relative path of the specified string.
`long` `getId()` Returns the bundle identifier associated with this archive.
`long` `getLastModified()` Returns the last modification time of this archive.
`String` `getLocation()` Returns the location string associated with this archive.
`int` `getPersistentState()` Returns the persistent state of this archive.
`int` `getStartLevel()` Returns the start level of this archive.
`boolean` `isRemovalPending()`
`void` `purge()` This method removes all old revisions associated with the archive and keeps only the current revision.
`void` `revise(String location, InputStream is)` This method adds a revision to the archive using the associated location and input stream.
`boolean` `rollbackRevise()` This method undoes the previous revision to the archive; this method will remove the latest revision from the archive.
`void` `setLastModified(long lastModified)` Sets the the last modification time of this archive.
`void` `setPersistentState(int state)` Sets the persistent state of this archive.
`void` `setStartLevel(int level)` Sets the the start level of this archive this archive.

### Methods inherited from class java.lang.Object

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

### Field Detail

#### FILE_PROTOCOL

    public static final transient String FILE_PROTOCOL

See Also:
  Constant Field Values

#### REFERENCE_PROTOCOL

    public static final transient String REFERENCE_PROTOCOL

See Also:
  Constant Field Values

#### INPUTSTREAM_PROTOCOL

    public static final transient String INPUTSTREAM_PROTOCOL

See Also:
  Constant Field Values

### Constructor Detail

#### BundleArchive

    public BundleArchive(Logger logger,
                         Map configMap,
                         WeakZipFileFactory zipFactory,
                         File archiveRootDir,
                         long id,
                         int startLevel,
                         String location,
                         InputStream is)
                  throws Exception

This constructor is used for creating new archives when a bundle is installed into the framework. Each archive receives a logger, a root directory, its associated bundle identifier, the associated bundle location string, and an input stream from which to read the bundle content. The root directory is where any required state can be stored. The input stream may be null, in which case the location is used as an URL to the bundle content.

Parameters:
  `logger` - the logger to be used by the archive.
  `archiveRootDir` - the archive root directory for storing state.
  `id` - the bundle identifier associated with the archive.
  `location` - the bundle location string associated with the archive.
  `is` - input stream from which to read the bundle content.
Throws:
  `Exception` - if any error occurs.

#### BundleArchive

    public BundleArchive(Logger logger,
                         Map configMap,
                         WeakZipFileFactory zipFactory,
                         File archiveRootDir)
                  throws Exception

This constructor is called when an archive for a bundle is being reconstructed when the framework is restarted. Each archive receives a logger, a root directory, and its associated bundle identifier. The root directory is where any required state can be stored.

Parameters:
  `logger` - the logger to be used by the archive.
  `archiveRootDir` - the archive root directory for storing state.
  `configMap` - configMap for BundleArchive
Throws:
  `Exception` - if any error occurs.

### Method Detail

#### getId

    public long getId()
               throws Exception

Returns the bundle identifier associated with this archive.

Returns:
  the bundle identifier associated with this archive.
Throws:
  `Exception` - if any error occurs.

#### getLocation

    public String getLocation()
                       throws Exception

Returns the location string associated with this archive.

Returns:
  the location string associated with this archive.
Throws:
  `Exception` - if any error occurs.

#### getPersistentState

    public int getPersistentState()
                           throws Exception

Returns the persistent state of this archive. The value returned is one of the following: `Bundle.INSTALLED`, `Bundle.ACTIVE`, or `Bundle.UNINSTALLED`.

Returns:
  the persistent state of this archive.
Throws:
  `Exception` - if any error occurs.

#### setPersistentState

    public void setPersistentState(int state)
                            throws Exception

Sets the persistent state of this archive. The value is one of the following: `Bundle.INSTALLED`, `Bundle.ACTIVE`, or `Bundle.UNINSTALLED`.

Parameters:
  `state` - the persistent state value to set for this archive.
Throws:
  `Exception` - if any error occurs.

#### getStartLevel

    public int getStartLevel()
                      throws Exception

Returns the start level of this archive.

Returns:
  the start level of this archive.
Throws:
  `Exception` - if any error occurs.

#### setStartLevel

    public void setStartLevel(int level)
                       throws Exception

Sets the the start level of this archive this archive.

Parameters:
  `level` - the start level to set for this archive.
Throws:
  `Exception` - if any error occurs.

#### getLastModified

    public long getLastModified()
                         throws Exception

Returns the last modification time of this archive.

Returns:
  the last modification time of this archive.
Throws:
  `Exception` - if any error occurs.

#### setLastModified

    public void setLastModified(long lastModified)
                         throws Exception

Sets the the last modification time of this archive.

Parameters:
  `lastModified` - The time of the last modification to set for this archive. According to the OSGi specification this time is set each time a bundle is installed, updated or uninstalled.
Throws:
  `Exception` - if any error occurs.

#### getDataFile

    public File getDataFile(String fileName)
                     throws Exception

Returns a `File` object corresponding to the data file of the relative path of the specified string.

Returns:
  a `File` object corresponding to the specified file name.
Throws:
  `Exception` - if any error occurs.

#### getCurrentRevisionNumber

    public Long getCurrentRevisionNumber()

Returns the current revision object for the archive.

Returns:
  the current revision object for the archive.

#### getCurrentRevision

    public BundleArchiveRevision getCurrentRevision()

Returns the current revision object for the archive.

Returns:
  the current revision object for the archive.

#### isRemovalPending

    public boolean isRemovalPending()

#### revise

    public void revise(String location,
                       InputStream is)
                throws Exception

This method adds a revision to the archive using the associated location and input stream. If the input stream is null, then the location is used a URL to obtain an input stream.

Parameters:
  `location` - the location string associated with the revision.
  `is` - the input stream from which to read the revision.
Throws:
  `Exception` - if any error occurs.

#### rollbackRevise

    public boolean rollbackRevise()
                           throws Exception

This method undoes the previous revision to the archive; this method will remove the latest revision from the archive. This method is only called when there are problems during an update after the revision has been created, such as errors in the update bundle's manifest. This method can only be called if there is more than one revision, otherwise there is nothing to undo.

Returns:
  true if the undo was a success false if there is no previous revision
Throws:
  `Exception` - if any error occurs.

#### close

    public void close()

#### closeAndDelete

    public void closeAndDelete()

This method closes any revisions and deletes the bundle archive directory.

Throws:
  `Exception` - if any error occurs.

#### purge

    public void purge()
               throws Exception

This method removes all old revisions associated with the archive and keeps only the current revision.

Throws:
  `Exception` - if any error occurs.