001/**
002 *
003 * Copyright 2015 Florian Schmaus
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.jivesoftware.smack.util;
018
019import java.util.Map;
020import java.util.concurrent.ConcurrentHashMap;
021
022/**
023 * The event manager class is used to perform actions and wait for an event, which is usually caused by the action (or maybe never occurs).
024 * <p>
025 * Events are distinguished by an unique event key. They can produce an event result, which can simply be null.
026 * </p>
027 * <p>
028 * The action is able to throw an exception.
029 * </p>
030 *
031 * @param <K> the event key.
032 * @param <R> the event result.
033 * @param <E> the exception which could be thrown by the action.
034 */
035public class EventManger<K, R, E extends Exception> {
036
037    private final Map<K, Reference<R>> events = new ConcurrentHashMap<>();
038
039    /**
040     * Perform an action and wait for an event.
041     * <p>
042     * The event is signaled with {@link #signalEvent(Object, Object)}.
043     * </p>
044     *
045     * @param eventKey the event key, must not be null.
046     * @param timeout the timeout to wait for the event in milliseconds.
047     * @param action the action to perform prior waiting for the event, must not be null.
048     * @return the event value, may be null.
049     * @throws InterruptedException if interrupted while waiting for the event.
050     * @throws E depending on the concrete use case.
051     */
052    public R performActionAndWaitForEvent(K eventKey, long timeout, Callback<E> action) throws InterruptedException, E {
053        final Reference<R> reference = new Reference<>();
054        events.put(eventKey, reference);
055        try {
056            synchronized (reference) {
057                action.action();
058                reference.wait(timeout);
059            }
060            return reference.eventResult;
061        }
062        finally {
063            events.remove(eventKey);
064        }
065    }
066
067    /**
068     * Signal an event and the event result.
069     * <p>
070     * This method will return <code>false</code> if the event was not created with
071     * {@link #performActionAndWaitForEvent(Object, long, Callback)}.
072     * </p>
073     *
074     * @param eventKey the event key, must not be null.
075     * @param eventResult the event result, may be null.
076     * @return true if the event was found and signaled, false otherwise.
077     */
078    public boolean signalEvent(K eventKey, R eventResult) {
079        final Reference<R> reference = events.get(eventKey);
080        if (reference == null) {
081            return false;
082        }
083        reference.eventResult = eventResult;
084        synchronized (reference) {
085            reference.notifyAll();
086        }
087        return true;
088    }
089
090    private static class Reference<V> {
091        volatile V eventResult;
092    }
093
094    public interface Callback<E extends Exception> {
095        void action() throws E;
096    }
097}