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
019package 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 */
028public 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}