View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.configuration2.sync;
18  
19  /**
20   * <p>
21   * An interface controlling synchronization of configuration instances.
22   * </p>
23   * <p>
24   * Each {@code Configuration} object derived from {@link org.apache.commons.configuration2.AbstractConfiguration
25   * AbstractConfiguration} has an associated {@code Synchronizer} object. Before an operation on the configuration is
26   * performed (e.g. a property read or an update), the {@code Synchronizer} is invoked. Depending on the concrete
27   * implementation of the {@code Synchronizer} used, the configuration can be made thread-safe.
28   * </p>
29   * <p>
30   * Whether a configuration has to be thread-safe or not is a matter of a concrete use case. For instance, an application
31   * that just reads some configuration settings on startup does need a thread-safe configuration implementation. A
32   * configuration in contrast which is shared between multiple components and updated concurrently should better be
33   * thread-safe. In order to satisfy both kinds of use cases, the support for thread-safety has been extracted out of the
34   * configuration implementation and refactored into this {@code Synchronizer} interface. By assigning different
35   * {@code Synchronizer} implementations to a configuration instance, the instance's support for concurrent access can be
36   * adapted to the concrete use case.
37   * </p>
38   * <p>
39   * The methods defined by this interface are similar to a <em>read-write lock</em>. The {@code Synchronizer} is notified
40   * when read or write operations start and end. A concrete implementation can then apply a specific policy to decide
41   * when threads need to block or when access to the configuration for the desired operation is granted.
42   * </p>
43   *
44   * @since 2.0
45   */
46  public interface Synchronizer {
47      /**
48       * Notifies this {@code Synchronizer} that the current thread is going to start a read operation on the managed
49       * configuration. This call can block if a concrete implementation decides that the thread has to wait until a specific
50       * condition is fulfilled.
51       */
52      void beginRead();
53  
54      /**
55       * Notifies this {@code Synchronizer} that the current thread is going to start a write operation on the managed
56       * configuration. This call may block. For instance, a concrete implementation may suspend the thread until all read
57       * operations currently active are finished,
58       */
59      void beginWrite();
60  
61      /**
62       * Notifies this {@code Synchronizer} that the current thread has finished its read operation. This may cause other
63       * waiting threads to be granted access to the managed configuration.
64       */
65      void endRead();
66  
67      /**
68       * Notifies this {@code Synchronizer} that the current thread has finished its write operation. This may cause other
69       * waiting threads to be granted access to the managed configuration.
70       */
71      void endWrite();
72  }