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 * https://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 (for example 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 /**
49 * Notifies this {@code Synchronizer} that the current thread is going to start a read operation on the managed
50 * configuration. This call can block if a concrete implementation decides that the thread has to wait until a specific
51 * condition is fulfilled.
52 */
53 void beginRead();
54
55 /**
56 * Notifies this {@code Synchronizer} that the current thread is going to start a write operation on the managed
57 * configuration. This call may block. For instance, a concrete implementation may suspend the thread until all read
58 * operations currently active are finished,
59 */
60 void beginWrite();
61
62 /**
63 * Notifies this {@code Synchronizer} that the current thread has finished its read operation. This may cause other
64 * waiting threads to be granted access to the managed configuration.
65 */
66 void endRead();
67
68 /**
69 * Notifies this {@code Synchronizer} that the current thread has finished its write operation. This may cause other
70 * waiting threads to be granted access to the managed configuration.
71 */
72 void endWrite();
73 }