IConcurrentNotificationHandler.java

/**
 * Copyright (C) 2008 - 2014 52°North Initiative for Geospatial Open Source
 * Software GmbH
 *
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 as published
 * by the Free Software Foundation.
 *
 * If the program is linked with libraries which are licensed under one of
 * the following licenses, the combination of the program with the linked
 * library is not considered a "derivative work" of the program:
 *
 *     - Apache License, version 2.0
 *     - Apache Software License, version 1.0
 *     - GNU Lesser General Public License, version 3
 *     - Mozilla Public License, versions 1.0, 1.1 and 2.0
 *     - Common Development and Distribution License (CDDL), version 1.0
 *
 * Therefore the distribution of the program linked with libraries licensed
 * under the aforementioned licenses, is permitted by the copyright holders
 * if the distribution is compliant with both the GNU General Public
 * icense version 2 and the aforementioned licenses.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
 * Public License for more details.
 */
package org.n52.ses.util.concurrent;

import org.n52.ses.api.event.MapEvent;

/**
 * Interface for a concurrent Notification processor.
 * An implementation should inform at least one implementation
 * of {@link IPollListener} about availability of inserted
 * {@link QueuedMapEventCollection}. These get claimed before
 * the actual processing using the {@link #insertPendingEventCollection(QueuedMapEventCollection)}
 * method.
 * 
 * @author matthes rieke <m.rieke@52north.org>
 *
 */
public interface IConcurrentNotificationHandler {
	
	/**
	 * notify the worker that new data is available
	 * @param coll the collection which has been processed
	 */
	public void notifyOnDataAvailability(QueuedMapEventCollection coll);

	/**
	 * start the concurrent processing
	 */
	public void startWorking();

	/**
	 * stop the concurrent processing
	 */
	public void stopWorking();
	
	/**
	 * @param coll the collection of MapEvents to be filled
	 * @return an empty collection of {@link MapEvent}s. This will get filled after
	 * processing has finished. 
	 */
	public QueuedMapEventCollection insertPendingEventCollection(QueuedMapEventCollection coll);

	/**
	 * @return number of errors due to unprocessed elements
	 */
	public int getNotProcessedFailureCount();

	/**
	 * reset the failure counters
	 */
	public void resetFailures();

	/**
	 * Join the working thread until all elements got processed and forwarded
	 * to the {@link IPollListener} implementation.
	 */
	public void joinUntilEmpty();

	/**
	 * @param l the timeout the handler should wait for messages to be processed
	 */
	public void setTimeout(long l);
	
	/**
	 * @param pl the impl of {@link IPollListener}, getting called for each event item
	 */
	public void setPollListener(IPollListener pl);
	
	
	/**
	 * set this flag to enable training an benchmarking of timeout deltas
	 * by taking actual processing periods into account.
	 * @param b true?
	 */
	public void setUseIntelligentTimeout(boolean b);
	
	
	/**
	 * A listener interface which gets called when
	 * a MapEvent is processed.
	 * 
	 * @author matthes rieke <m.rieke@52north.org>
	 *
	 */
	public static interface IPollListener {
		
		/**
		 * @param alert the next available MapEvent 
		 */
		public void onElementPolled(MapEvent alert);
		
	}


}