Java tutorial
/** * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information * regarding copyright ownership. The ASF licenses this file * to you under the Apache License, Version 2.0 (the * "License"); you may not use this file except in compliance * with the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package com.twitter.distributedlog.util; import com.twitter.distributedlog.exceptions.BKTransmitException; import com.twitter.distributedlog.DistributedLogConstants; import com.twitter.distributedlog.exceptions.LockingException; import com.twitter.distributedlog.ZooKeeperClient; import com.twitter.distributedlog.exceptions.DLInterruptedException; import com.twitter.distributedlog.exceptions.UnexpectedException; import com.twitter.distributedlog.exceptions.ZKException; import com.twitter.util.Await; import com.twitter.util.Duration; import com.twitter.util.Function; import com.twitter.util.Future; import com.twitter.util.FutureCancelledException; import com.twitter.util.FutureEventListener; import com.twitter.util.Promise; import com.twitter.util.Return; import com.twitter.util.Throw; import org.apache.bookkeeper.client.BKException; import org.apache.zookeeper.KeeperException; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import scala.runtime.BoxedUnit; import javax.annotation.Nullable; import java.io.IOException; import java.util.ArrayList; import java.util.Iterator; import java.util.List; import java.util.concurrent.ExecutorService; import java.util.concurrent.TimeUnit; /** * Utilities to process future */ public class FutureUtils { private static final Logger logger = LoggerFactory.getLogger(FutureUtils.class); public static class OrderedFutureEventListener<R> implements FutureEventListener<R> { public static <R> OrderedFutureEventListener<R> of(FutureEventListener<R> listener, OrderedScheduler scheduler, Object key) { return new OrderedFutureEventListener<R>(scheduler, key, listener); } private final OrderedScheduler scheduler; private final Object key; private final FutureEventListener<R> listener; private OrderedFutureEventListener(OrderedScheduler scheduler, Object key, FutureEventListener<R> listener) { this.scheduler = scheduler; this.key = key; this.listener = listener; } @Override public void onSuccess(final R value) { scheduler.submit(key, new Runnable() { @Override public void run() { listener.onSuccess(value); } }); } @Override public void onFailure(final Throwable cause) { scheduler.submit(key, new Runnable() { @Override public void run() { listener.onFailure(cause); } }); } } public static class FutureEventListenerRunnable<R> implements FutureEventListener<R> { public static <R> FutureEventListenerRunnable<R> of(FutureEventListener<R> listener, ExecutorService executorService) { return new FutureEventListenerRunnable<R>(executorService, listener); } private final ExecutorService executorService; private final FutureEventListener<R> listener; private FutureEventListenerRunnable(ExecutorService executorService, FutureEventListener<R> listener) { this.executorService = executorService; this.listener = listener; } @Override public void onSuccess(final R value) { executorService.submit(new Runnable() { @Override public void run() { listener.onSuccess(value); } }); } @Override public void onFailure(final Throwable cause) { executorService.submit(new Runnable() { @Override public void run() { listener.onFailure(cause); } }); } } private static class ListFutureProcessor<T, R> extends Function<Throwable, BoxedUnit> implements FutureEventListener<R>, Runnable { private volatile boolean interrupted = false; private final Iterator<T> itemsIter; private final Function<T, Future<R>> processFunc; private final Promise<List<R>> promise; private final List<R> results; private final ExecutorService callbackExecutor; ListFutureProcessor(List<T> items, Function<T, Future<R>> processFunc, ExecutorService callbackExecutor) { this.itemsIter = items.iterator(); this.processFunc = processFunc; this.promise = new Promise<List<R>>(); this.promise.setInterruptHandler(this); this.results = new ArrayList<R>(); this.callbackExecutor = callbackExecutor; } @Override public BoxedUnit apply(Throwable cause) { interrupted = true; return BoxedUnit.UNIT; } @Override public void onSuccess(R value) { results.add(value); if (null == callbackExecutor) { run(); } else { callbackExecutor.submit(this); } } @Override public void onFailure(final Throwable cause) { if (null == callbackExecutor) { promise.setException(cause); } else { callbackExecutor.submit(new Runnable() { @Override public void run() { promise.setException(cause); } }); } } @Override public void run() { if (interrupted) { logger.debug("ListFutureProcessor is interrupted."); return; } if (!itemsIter.hasNext()) { promise.setValue(results); return; } processFunc.apply(itemsIter.next()).addEventListener(this); } } /** * Process the list of items one by one using the process function <i>processFunc</i>. * The process will be stopped immediately if it fails on processing any one. * * @param collection list of items * @param processFunc process function * @param callbackExecutor executor to process the item * @return future presents the list of processed results */ public static <T, R> Future<List<R>> processList(List<T> collection, Function<T, Future<R>> processFunc, @Nullable ExecutorService callbackExecutor) { ListFutureProcessor<T, R> processor = new ListFutureProcessor<T, R>(collection, processFunc, callbackExecutor); if (null != callbackExecutor) { callbackExecutor.submit(processor); } else { processor.run(); } return processor.promise; } /** * Await for the result of the future and thrown bk related exceptions. * * @param result future to wait for * @return the result of future * @throws BKException when exceptions are thrown by the future. If there is unkown exceptions * thrown from the future, the exceptions will be wrapped into * {@link org.apache.bookkeeper.client.BKException.BKUnexpectedConditionException}. */ public static <T> T bkResult(Future<T> result) throws BKException { try { return Await.result(result); } catch (BKException bke) { throw bke; } catch (InterruptedException ie) { throw BKException.create(BKException.Code.InterruptedException); } catch (Exception e) { logger.warn("Encountered unexpected exception on waiting bookkeeper results : ", e); throw BKException.create(BKException.Code.UnexpectedConditionException); } } /** * Return the bk exception return code for a <i>throwable</i>. * * @param throwable the cause of the exception * @return the bk exception return code. if the exception isn't bk exceptions, * it would return bk exception code. */ public static int bkResultCode(Throwable throwable) { if (throwable instanceof BKException) { return ((BKException) throwable).getCode(); } return BKException.Code.UnexpectedConditionException; } /** * Wait for the result until it completes. * * @param result result to wait * @return the result * @throws IOException when encountered exceptions on the result */ public static <T> T result(Future<T> result) throws IOException { return result(result, Duration.Top()); } /** * Wait for the result for a given <i>duration</i>. * <p>If the result is not ready within `duration`, an IOException will thrown wrapping with * corresponding {@link com.twitter.util.TimeoutException}. * * @param result result to wait * @param duration duration to wait * @return the result * @throws IOException when encountered exceptions on the result or waiting for the result. */ public static <T> T result(Future<T> result, Duration duration) throws IOException { try { return Await.result(result, duration); } catch (KeeperException ke) { throw new ZKException("Encountered zookeeper exception on waiting result", ke); } catch (BKException bke) { throw new BKTransmitException("Encountered bookkeeper exception on waiting result", bke.getCode()); } catch (IOException ioe) { throw ioe; } catch (InterruptedException ie) { throw new DLInterruptedException("Interrupted on waiting result", ie); } catch (Exception e) { throw new IOException("Encountered exception on waiting result", e); } } /** * Wait for the result of a lock operation. * * @param result result to wait * @param lockPath path of the lock * @return the result * @throws LockingException when encountered exceptions on the result of lock operation */ public static <T> T lockResult(Future<T> result, String lockPath) throws LockingException { try { return Await.result(result); } catch (LockingException le) { throw le; } catch (Exception e) { throw new LockingException(lockPath, "Encountered exception on locking ", e); } } /** * Convert the <i>throwable</i> to zookeeper related exceptions. * * @param throwable cause * @param path zookeeper path * @return zookeeper related exceptions */ public static Throwable zkException(Throwable throwable, String path) { if (throwable instanceof KeeperException) { return throwable; } else if (throwable instanceof ZooKeeperClient.ZooKeeperConnectionException) { return KeeperException.create(KeeperException.Code.CONNECTIONLOSS, path); } else if (throwable instanceof InterruptedException) { return new DLInterruptedException("Interrupted on operating " + path, throwable); } else { return new UnexpectedException("Encountered unexpected exception on operatiing " + path, throwable); } } /** * Cancel the future. It would interrupt the future. * * @param future future to cancel */ public static <T> void cancel(Future<T> future) { future.raise(new FutureCancelledException()); } /** * Raise an exception to the <i>promise</i> within a given <i>timeout</i> period. * If the promise has been satisfied before raising, it won't change the state of the promise. * * @param promise promise to raise exception * @param timeout timeout period * @param unit timeout period unit * @param cause cause to raise * @param scheduler scheduler to execute raising exception * @param key the submit key used by the scheduler * @return the promise applied with the raise logic */ public static <T> Promise<T> within(final Promise<T> promise, final long timeout, final TimeUnit unit, final Throwable cause, final OrderedScheduler scheduler, final Object key) { if (timeout < DistributedLogConstants.FUTURE_TIMEOUT_IMMEDIATE || promise.isDefined()) { return promise; } scheduler.schedule(key, new Runnable() { @Override public void run() { logger.info("Raise exception", cause); // satisfy the promise FutureUtils.setException(promise, cause); } }, timeout, unit); return promise; } /** * Satisfy the <i>promise</i> with provide value in an ordered scheduler. * <p>If the promise was already satisfied, nothing will be changed. * * @param promise promise to satisfy * @param value value to satisfy * @param scheduler scheduler to satisfy the promise with provided value * @param key the submit key of the ordered scheduler */ public static <T> void setValue(final Promise<T> promise, final T value, OrderedScheduler scheduler, Object key) { scheduler.submit(key, new Runnable() { @Override public void run() { setValue(promise, value); } }); } /** * Satisfy the <i>promise</i> with provide value. * <p>If the promise was already satisfied, nothing will be changed. * * @param promise promise to satisfy * @param value value to satisfy * @return true if successfully satisfy the future. false if the promise has been satisfied. */ public static <T> boolean setValue(Promise<T> promise, T value) { boolean success = promise.updateIfEmpty(new Return<T>(value)); if (!success) { logger.info("Result set multiple times. Value = '{}', New = 'Return({})'", promise.poll(), value); } return success; } /** * Satisfy the <i>promise</i> with provided <i>cause</i> in an ordered scheduler. * * @param promise promise to satisfy * @param throwable cause to satisfy * @param scheduler the scheduler to satisfy the promise * @param key submit key of the ordered scheduler */ public static <T> void setException(final Promise<T> promise, final Throwable throwable, OrderedScheduler scheduler, Object key) { scheduler.submit(key, new Runnable() { @Override public void run() { setException(promise, throwable); } }); } /** * Satisfy the <i>promise</i> with provided <i>cause</i>. * * @param promise promise to satisfy * @param cause cause to satisfy * @return true if successfully satisfy the future. false if the promise has been satisfied. */ public static <T> boolean setException(Promise<T> promise, Throwable cause) { boolean success = promise.updateIfEmpty(new Throw<T>(cause)); if (!success) { logger.info("Result set multiple times. Value = '{}', New = 'Throw({})'", promise.poll(), cause); } return success; } /** * Ignore exception from the <i>future</i>. * * @param future the original future * @return a transformed future ignores exceptions */ public static <T> Promise<Void> ignore(Future<T> future) { return ignore(future, null); } /** * Ignore exception from the <i>future</i> and log <i>errorMsg</i> on exceptions * * @param future the original future * @param errorMsg the error message to log on exceptions * @return a transformed future ignores exceptions */ public static <T> Promise<Void> ignore(Future<T> future, final String errorMsg) { final Promise<Void> promise = new Promise<Void>(); future.addEventListener(new FutureEventListener<T>() { @Override public void onSuccess(T value) { setValue(promise, null); } @Override public void onFailure(Throwable cause) { if (null != errorMsg) { logger.error(errorMsg, cause); } setValue(promise, null); } }); return promise; } /** * Create transmit exception from transmit result. * * @param transmitResult * transmit result (basically bk exception code) * @return transmit exception */ public static BKTransmitException transmitException(int transmitResult) { return new BKTransmitException("Failed to write to bookkeeper; Error is (" + transmitResult + ") " + BKException.getMessage(transmitResult), transmitResult); } }