Package org.apache.commons.configuration2.sync

# Interface SynchronizerSupport

All Known Subinterfaces:
  `Configuration`, `FileBasedConfiguration`, `HierarchicalConfiguration<T>`

All Known Implementing Classes:
  `AbstractConfiguration`, `AbstractHierarchicalConfiguration`, `AbstractYAMLBasedConfiguration`, `AppletConfiguration`, `BaseConfiguration`, `BaseHierarchicalConfiguration`, `CombinedConfiguration`, `CompositeConfiguration`, `DatabaseConfiguration`, `DataConfiguration`, `DynamicCombinedConfiguration`, `EnvironmentConfiguration`, `INIConfiguration`, `JNDIConfiguration`, `JSONConfiguration`, `MapConfiguration`, `PatternSubtreeConfigurationWrapper`, `PropertiesConfiguration`, `PropertyListConfiguration`, `ServletConfiguration`, `ServletContextConfiguration`, `ServletFilterConfiguration`, `ServletRequestConfiguration`, `SubnodeConfiguration`, `SubsetConfiguration`, `SystemConfiguration`, `XMLConfiguration`, `XMLPropertiesConfiguration`, `XMLPropertyListConfiguration`, `YAMLConfiguration`

public interface SynchronizerSupport

Definition of an interface for objects that can be associated with a `Synchronizer`.

This interface defines methods for querying and setting the `Synchronizer`. In addition, it is possible to lock the object for a certain operation. This is useful if some complex operations are to be performed on the `SynchronizerSupport` object in an atomic way.

Note that the actual effect of these methods depends on the concrete `Synchronizer` implementation in use! If only a dummy `Synchronizer` is involved (which is appropriate if objects are only accessed by a single thread), locking an object does not really prohibit concurrent access.

Since:
  2.0

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Synchronizer`
  `getSynchronizer()`
  Gets the `Synchronizer` used by this object.
  `void`
  `lock(LockMode mode)`
  Locks this object for the specified mode.
  `void`
  `setSynchronizer(Synchronizer sync)`
  Sets the `Synchronizer` to be used by this object.
  `void`
  `unlock(LockMode mode)`
  Releases a lock of this object that was obtained using the `lock(LockMode)` method.

- ## Method Details

  - ### getSynchronizer

    Synchronizer getSynchronizer()
    Gets the `Synchronizer` used by this object. An implementation must not return null. If no `Synchronizer` has been set so far, a meaningful default `Synchronizer` has to be returned.
    Returns:
      the `Synchronizer` used by this object

  - ### lock

    void lock(LockMode mode)
    Locks this object for the specified mode. This call may block until this object is released from other lock operations. When it returns the caller can access the object in a way compatible to the specified `LockMode`. When done the `unlock()` must be called with the same `LockMode` argument. In practice, a try-finally construct should be used as in the following example:

         SynchronizerSupport syncSupport = ...;
         syncSupport.lock(LockMode.READ);
         try
         {
             // read access to syncSupport
         }
         finally
         {
             syncSupport.unlock(LockMode.READ);
         }

    Note: Always use this method for obtaining a lock rather than accessing the object's `Synchronizer` directly. An implementation may perform additional actions which are not executed when only interacting with the `Synchronizer`.
    Parameters:
      `mode` - the `LockMode`

  - ### setSynchronizer

    void setSynchronizer(Synchronizer sync)
    Sets the `Synchronizer` to be used by this object. Calling this method and setting an appropriate `Synchronizer` determines whether this object can be accessed in a thread-safe way or not. The argument may be null; in this case an implementation should switch to a default `Synchronizer`.
    Parameters:
      `sync` - the `Synchronizer` for this object

  - ### unlock

    void unlock(LockMode mode)
    Releases a lock of this object that was obtained using the `lock(LockMode)` method. This method must always be called pair-wise with `lock()`. The argument must match to the one passed to the corresponding `lock()` call; otherwise, the behavior of the `Synchronizer` is unspecified.
    Parameters:
      `mode` - the `LockMode`