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 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:

    • 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:

    • readUnlock

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

    • writeUnlock

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

    • 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.