com.elusive_code.newsboy.EventService Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of NewsBoy Show documentation

Asynchronous publish-subscribe communication library. Features: 1. Listeners are stored using WeakReferences to prevent memory leaks when they are not unsubscribed. 2. Uses fork-join framework for concurrent event delivery. 3. Publish methods returns collection of Futures that represent event notifications. 4. Supports ordered publishing: guaranteed to notify of the events in order they were published. 5. Provides EventSource and EventService interfaces for better integration with IOC containers and alternative implementations.

The newest version!

/*
 * Copyright 2014. Vladislav Dolgikh
 *
 * Licensed 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.elusive_code.newsboy;

import java.util.List;

/**
 * Publish-subscribe style communication
 * This interface represents event exchange service or subscribe "topic".
 * Other objects may subscribe for events published in this event service as well as publish their own events here
 *
 * 
 *     To receive events object must have public method with zero or one argument
 *     marked with {@link com.elusive_code.newsboy.Subscribe} annotation.

 *     This object should be passed to {@link com.elusive_code.newsboy.EventService#subscribe(Object)}.

 * 
 * 
 *     If event handling method has one argument, listener will be notified of the events
 *     that fit the type of that argument.

 *     
If event handling method has no arguments, listener will notified of the events that fit {@link Subscribe#eventType()}
 * 
 * @see com.elusive_code.newsboy.Subscribe
 * @see AsyncEventService
 * @author Vladislav Dolgikh
 */
public interface EventService extends EventSource {

    /**
     * Publish event to this EventService.
     * No delivery order guaranteed.
     * @param event event to notify of
     * @return list of {@link com.elusive_code.newsboy.NotificationFuture} that represent scheduled notifications
     */
    List publish(Object event);

    /**
     *
     * Publish event to this EventService.
     * Guaranteed to deliver event in the same order it was published
     * relative to other ordered events
     * @param event event to notify of
     * @return list of {@link com.elusive_code.newsboy.NotificationFuture} that represent scheduled notifications
     */
    List publishOrdered(Object event);
    
}