001/*
002    Licensed to the Apache Software Foundation (ASF) under one
003    or more contributor license agreements.  See the NOTICE file
004    distributed with this work for additional information
005    regarding copyright ownership.  The ASF licenses this file
006    to you under the Apache License, Version 2.0 (the
007    "License"); you may not use this file except in compliance
008    with the License.  You may obtain a copy of the License at
009
010       http://www.apache.org/licenses/LICENSE-2.0
011
012    Unless required by applicable law or agreed to in writing,
013    software distributed under the License is distributed on an
014    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015    KIND, either express or implied.  See the License for the
016    specific language governing permissions and limitations
017    under the License.
018 */
019package org.apache.wiki.util;
020
021import java.util.concurrent.locks.ReentrantLock;
022import java.util.function.Supplier;
023
024/**
025 * <h1>Synchronizer Utility Class</h1>
026 *
027 * <p>This utility class is designed to provide a simplified interface for
028 * executing code blocks in a synchronized manner using {@link ReentrantLock}.
029 * It aims to improve code readability and maintainability by abstracting
030 * common locking idioms.</p>
031 *
032 * <h2>Usage Example:</h2>
033 * <pre>
034 * {@code
035 * ReentrantLock lock = new ReentrantLock();
036 * String result = Synchronizer.synchronize(lock, () -> {
037 *     // Your synchronized code here
038 *     return "some result";
039 * });
040 * }
041 * </pre>
042 *
043 * @since 3.0.1
044 */
045public class Synchronizer {
046
047    /**
048     * Executes a given {@link Supplier} within a synchronized block managed by
049     * a {@link ReentrantLock}.
050     *
051     * <p>This method acquires the lock, executes the supplier's code, and then
052     * releases the lock. It is designed to replace the traditional lock idiom:</p>
053     *
054     * <pre>{@code
055     * lock.lock();
056     * try {
057     *     doSomething();
058     * } finally {
059     *     lock.unlock();
060     * }
061     * }</pre>
062     *
063     * <p><strong>Parameters:</strong></p>
064     * <ul>
065     *     <li>{@code lock} - The ReentrantLock to be used for synchronization.</li>
066     *     <li>{@code supplier} - The supplier whose code needs to be executed within
067     *     the synchronized block.</li>
068     * </ul>
069     *
070     * <p><strong>Returns:</strong></p>
071     * <p>The result produced by the supplier.</p>
072     *
073     * <p><strong>Throws:</strong></p>
074     * <p>This method propagates any exceptions thrown by the supplier's code.</p>
075     *
076     * @param <T>      The type of result produced by the supplier.
077     * @param lock     The ReentrantLock to be used for synchronization.
078     * @param supplier The supplier to be executed within the synchronized block.
079     * @return The result produced by the supplier.
080     */
081    public static <T> T synchronize(final ReentrantLock lock, final Supplier<T> supplier) {
082        lock.lock();
083        try {
084            return supplier.get();
085        } finally {
086            lock.unlock();
087        }
088    }
089
090    /**
091     * <p>Functional interface for runnable tasks that can throw exceptions.</p>
092     *
093     * @param <E> the type of exception that may be thrown
094     */
095    @FunctionalInterface
096    public interface ThrowingRunnable<E extends Exception> {
097        /**
098         * Executes the operation.
099         *
100         * @throws E if an exception occurs during the operation
101         */
102        void run() throws E;
103    }
104
105    /**
106     * <p>Throws the given exception as an unchecked exception.</p>
107     *
108     * @param <E>       the type of exception to throw
109     * @param exception the exception to throw
110     * @throws E the thrown exception
111     */
112    @SuppressWarnings("unchecked")
113    private static < E extends Throwable > void throwAsUnchecked( final Exception exception ) throws E {
114        throw (E) exception;
115    }
116
117    /**
118     * <p>Executes a given {@link ThrowingRunnable} within a synchronized block managed by
119     * a {@link ReentrantLock}.</p>
120     *
121     * <p><strong>Parameters:</strong></p>
122     * <ul>
123     *     <li>{@code lock} - The ReentrantLock to be used for synchronization.</li>
124     *     <li>{@code throwingRunnable} - The ThrowingRunnable whose code needs to be executed within
125     *     the synchronized block.</li>
126     * </ul>
127     *
128     * <p><strong>Throws:</strong></p>
129     * <p>This method propagates any exceptions thrown by the ThrowingRunnable's code.</p>
130     *
131     * @param <E>              the type of exception that may be thrown
132     * @param lock             the ReentrantLock to use for synchronization
133     * @param throwingRunnable the ThrowingRunnable to execute
134     */
135    public static < E extends Exception > void synchronize( final ReentrantLock lock, final ThrowingRunnable<E> throwingRunnable ) {
136        lock.lock();
137        try {
138            throwingRunnable.run();
139        } catch( final Exception e ) {
140            throwAsUnchecked( e );
141        } finally {
142            lock.unlock();
143        }
144    }
145
146}
147