001    /**
002     * Copyright (c) 2008-2009 Apple Inc. All rights reserved.
003     * Copyright (C) 2012 FuseSource, Inc.
004     * http://fusesource.com
005     *
006     * Licensed under the Apache License, Version 2.0 (the "License");
007     * you may not use this file except in compliance with the License.
008     * 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, software
013     * distributed under the License is distributed on an "AS IS" BASIS,
014     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015     * See the License for the specific language governing permissions and
016     * limitations under the License.
017     */
018    
019    package org.fusesource.hawtdispatch;
020    
021    /**
022     * A dispatch source that is used to coalesce multiple application generated
023     * events for later processing by the dispatch source event handler.
024     *
025     * @param <Event>
026     * @param <MergedEvent>
027     */
028    public interface CustomDispatchSource<Event, MergedEvent> extends DispatchSource {
029    
030        /**
031         * <p>
032         * Returns pending data for the dispatch source.  Calling this method consumes
033         * the event and a subsequent call will return null.
034         * </p><p>
035         * This function is intended to be called from within the event handler runnable.
036         * The result of calling this function outside of the event handler runnable is
037         * undefined.
038         * </p>
039         *
040         * @author <a href="http://hiramchirino.com">Hiram Chirino</a>
041         */
042        public MergedEvent getData();
043    
044        /**
045         * <p>
046         * Merges data into a dispatch source and submits its event handler runnable to its
047         * target queue.
048         * </p>
049         *
050         * @param value
051         * The value to coalesce with the pending data using the {@link EventAggregator}
052         * that was specified when this dispach source was created.
053         */
054        public void merge(Event value);
055    }