Package org.eclipse.osgi.container

# Class ModuleDatabase

java.lang.Object
org.eclipse.osgi.container.ModuleDatabase

public class ModuleDatabase extends Object
A database for storing modules, their revisions and wiring states. The database is responsible for assigning ids and providing access to the capabilities provided by the revisions currently installed as well as the wiring states.

Concurrent Semantics
Implementations must be thread safe. The database allows for concurrent read operations and all read operations are protected by the `read` lock. All write operations are protected by the `write` lock. The read and write locks are reentrant and follow the semantics of the `ReentrantReadWriteLock`. Just like the `ReentrantReadWriteLock` the lock on a database can not be upgraded from a read to a write. Doing so will result in an `IllegalMonitorStateException` being thrown. This is behavior is different from the `ReentrantReadWriteLock` which results in a deadlock if an attempt is made to upgrade from a read to a write lock.

A database is associated with a `container`. The container associated with a database provides public API for manipulating the modules and their wiring states. For example, installing, updating, uninstalling, resolving and unresolving modules. Except for the `load(DataInputStream)`, all other methods that perform write operations are intended to be used by the associated container.

Since:
  3.10

## Constructor Summary

Constructors
Constructor
Description
`ModuleDatabase(ModuleContainerAdaptor adaptor)`
Constructs a new empty database.

## Method Summary

Modifier and Type
Method
Description
`final long`
`getAndIncrementNextId()`
Atomically increments by one the next module ID.
`final long`
`getNextId()`
returns the next module ID.
`final long`
`getRevisionsTimestamp()`
Returns the current timestamp for the revisions of this database.
`final long`
`getTimestamp()`
Returns the current timestamp for this database.
`final void`
`load(DataInputStream in)`
Loads information into this database from the input data stream.
`final void`
`readLock()`
Acquires the read lock for this database.
`final void`
`readUnlock()`
Attempts to release the read lock for this database.
`protected void`
`removeCapabilities(ModuleRevision revision)`
Removes the `capabilities` provided by the specified revision from this database.
`final void`
`store(DataOutputStream out, boolean persistWirings)`
Writes this database in a format suitable for using the `load(DataInputStream)` method.
`final void`
`writeLock()`
Acquires the write lock for this database.
`final void`
`writeUnlock()`
Attempts to release the write lock for this database.

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

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

## Constructor Details

### ModuleDatabase

public ModuleDatabase(ModuleContainerAdaptor adaptor)
Constructs a new empty database.

Parameters:
  `adaptor` - the module container adaptor

## Method Details

### getNextId

public final long getNextId()
returns the next module ID.

A read operation protected by the `read` lock.

Returns:
  the next module ID

### getAndIncrementNextId

public final long getAndIncrementNextId()
Atomically increments by one the next module ID.

A write operation protected by the `writeLock()` lock.

Returns:
  the previous module ID
Since:
  3.13

### getRevisionsTimestamp

public final long getRevisionsTimestamp()
Returns the current timestamp for the revisions of this database. The timestamp is incremented any time a modification is made to the revisions in this database. For example:

- installing a module
- updating a module
- uninstalling a module
- modifying the wirings

A read operation protected by the `read` lock.

Returns:
  the current timestamp of this database.

### getTimestamp

public final long getTimestamp()
Returns the current timestamp for this database. The timestamp is incremented any time a modification is made to this database. This includes the modifications described in `revisions timestamp` and the following modifications related to modules:

- modifying the initial module start level
- modifying a module start level
- modifying a module settings

A read operation protected by the `read` lock.

Returns:
  the current timestamp of this database.

### readLock

public final void readLock()
Acquires the read lock for this database.

See Also:
  - `ReentrantReadWriteLock.ReadLock.lock()`

### writeLock

public final void writeLock()
Acquires the write lock for this database. Same as `ReentrantReadWriteLock.WriteLock.lock()` except an illegal state exception is thrown if the current thread holds one or more read locks.

Throws:
  `IllegalMonitorStateException` - if the current thread holds one or more read locks.
See Also:
  - `ReentrantReadWriteLock.WriteLock.lock()`

### readUnlock

public final void readUnlock()
Attempts to release the read lock for this database.

See Also:
  - `ReentrantReadWriteLock.ReadLock.unlock()`

### writeUnlock

public final void writeUnlock()
Attempts to release the write lock for this database.

See Also:
  - `ReentrantReadWriteLock.WriteLock.unlock()`

### removeCapabilities

protected void removeCapabilities(ModuleRevision revision)
Removes the `capabilities` provided by the specified revision from this database. These capabilities must no longer be available for lookup with the `findCapabilities(Requirement)` method.

This method must be called while holding the `write` lock.

### store

public final void store(DataOutputStream out, boolean persistWirings) throws IOException
Writes this database in a format suitable for using the `load(DataInputStream)` method. All modules are stored which have a current `revision`. Only the current revision of each module is stored (no removal pending revisions are stored). Optionally the `wiring` of each current revision may be stored. Wiring can only be stored if there are no `removal pending` revisions.

This method acquires the `read` lock while writing this database.

After this database have been written, the output stream is flushed. The output stream remains open after this method returns.

Parameters:
  `out` - the data output steam.
  `persistWirings` - true if wirings should be persisted. This option will be ignored if there are `removal pending` revisions.
Throws:
  `IOException` - if writing this database to the specified output stream throws an IOException

### load

public final void load(DataInputStream in) throws IOException
Loads information into this database from the input data stream. This data base must be empty and never been modified (the `timestamp` is zero). All stored modules are loaded into this database. If the input stream contains wiring then it will also be loaded into this database.

Since this method modifies this database it is considered a write operation. This method acquires the `write` lock while loading the information into this database.

The specified stream remains open after this method returns.

Parameters:
  `in` - the data input stream.
Throws:
  `IOException` - if an error occurred when reading from the input stream.
  `IllegalStateException` - if this database is not empty.