ar.com.zauber.commons.async.Joiner Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of commons-base Show documentation
There is a newer version: 3.55
/**
 * Copyright (c) 2005-2011 Zauber S.A. 
 *
 * 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 ar.com.zauber.commons.async;

import java.util.Collection;

/**
 * Defines the behavior of a joiner.
 * 
 * 
 * A joiner could be used when several asynchronous flows of tasks or objects need to be collected into
 * one point.
 * 
 * 
 * NOTE: Implementations of this interface should be thread safe
 * 
 * @param  The type of object to be joined.
 * @param  The type of failed flows.
 * @author Guido Marucci Blas
 * @since Apr 19, 2011
 */
public interface Joiner {

    /**
     * Notifies the {@link Joiner} that object
     * needs to be joined.
     * 
     * 
     * This method will increase the amount of successful notifications and will decrease the amount
     * of remaining notifications
     * 
     * 
     * @param object The object to be joined. Must not be null.
     * @throws IllegalStateException if the amount of remaining notifications is zero.
     * @throws IllegalArgumentException if object is null.
     */
    void notifySuccess(T object);
    
    /**
     * Notifies the {@link Joiner} that one of the expected object could not be joined.
     * 
     * 
     * This method will increase the amount of failure notifications and will decrease the amount
     * of remaining notifications
     * 
     * 
     * @throws IllegalStateException if the amount of remaining notifications is zero.
     */
    void notifyFailure();
    
    /**
     * Notifies the {@link Joiner} that one of the expected object could not be joined.
     * 
     * 
     * This method will increase the amount of failure notifications and will decrease the amount
     * of remaining notifications
     * 
     * 
     * @param t The reason why one of the objects could not joined. Must not be null.
     * @throws IllegalStateException if the amount of remaining notifications is zero.
     * @throws IllegalArgumentException if t is null.
     */
    void notifyFailure(Throwable t);
    
    /**
     * Notifies the {@link Joiner} that one of the expected object could not be joined.
     * 
     * 
     * This method will increase the amount of failure notifications and will decrease the amount
     * of remaining notifications
     * 
     * 
     * @param failedTask The task or flow that failed to create the object to be joined. Must not be null.
     * @param t The reason why one of the objects could not joined. Must not be null.
     * @throws IllegalStateException if the amount of remaining notifications is zero.
     * @throws IllegalArgumentException if t or failedTask are null.
     */
    void notifyFailure(F failedTask, Throwable t);
    
    /**
     * Obtains the amount of successful notifications.
     * 
     * @return The amount of successful notifications.
     */
    int getSuccessfulNotificationsCount();
    
    /**
     * Obtains the amount of failure notifications.
     * 
     * @return The amount of failure notifications.
     */
    int getFailureNotificationsCount();
    
    /**
     * Obtains the amount of expected notifications.
     * 
     * @return The amount of expected notifications.
     */
    int getExpectedNotificationsCount();
    
    /**
     * Obtains the amount of remaining notifications.
     * 
     * @return The amount of remaining notifications.
     */
    int getRemainingNotificationsCount();
    
    /**
     * @return True if the joiner has received failure notifications. False otherwise.
     */
    boolean hasFailureNotifications();
    
    /**
     * @return True if the joiner is still waiting for notifications, in which case 
     * {@link Joiner#getRemainingNotificationsCount()} will return a non-zero value. False otherwise.
     */
    boolean isWaitingForNotifications();
    
    /**
     * Obtains a {@link Collection} of joined objects.
     * 
     * 
     * The returned joined objects are the objects that were joined at the moment of the method call. 
     * The order of the collection is given by the order in which the {@link Joiner} was notified.
     * A new collection is created each time this method is called.
     * 
     * 
     * @return A {@link Collection} of joined objects.
     */
    Collection joinedObjects();
    
    /**
     * Obtains a {@link Collection} of failed tasks.
     * 
     * 
     * The returned failed tasks are the ones that were notified at the moment of the method call. 
     * The order of the collection is given by the order in which the {@link Joiner} was notified.
     * A new collection is created each time this method is called.
     * 
     * 
     * @return A {@link Collection} of joined objects.
     */
    Collection> failedTasks();
    
    /**
     * A wrapper type for grouping failed tasks with it's cause.
     * 
     * @param  The type of failed flows.
     * @author Guido Marucci Blas
     * @since Apr 20, 2011
     */
    interface FailedTask {
        
        /**
         * @return The failed task. May be null.
         */
        F getFailedTask();
        
        /**
         * @return The cause of failure.
         */
        Throwable getCause();
        
        /**
         * @return True if the failed task can be obtained. False otherwise.
         */
        boolean hasFailedTasks();
    }
}