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