PostProcessor.java

/*******************************************************************************
 * Copyright (c) 2011 The Board of Trustees of the Leland Stanford Junior University
 * as Operator of the SLAC National Accelerator Laboratory.
 * Copyright (c) 2011 Brookhaven National Laboratory.
 * EPICS archiver appliance is distributed subject to a Software License Agreement found
 * in file LICENSE that is included with this distribution.
 *******************************************************************************/
package org.epics.archiverappliance.retrieval.postprocessors;

import java.io.IOException;
import java.sql.Timestamp;
import java.util.concurrent.Callable;

import javax.servlet.http.HttpServletRequest;

import org.epics.archiverappliance.EventStream;
import org.epics.archiverappliance.config.PVTypeInfo;

/**
 * The interface for retrieval post processors.
 * At a very high level, post processors wrap event streams and generate new event streams.
 * To enable running in a thread pool, we make these take Callable<EventStream> and return Callable<EventStream>
 * A PostProcessor has to also help make a determination as to whether to execute sequentially or execute in parallel based on the memory consumption when running in parallel.
 * @author mshankar
 *
 */
public interface PostProcessor {
	/**
	 * The string used by clients to identify this post processor when making retrieval requests.
	 * For example to identify the FirstSamplePP postprocessor, users would add a pp=firstSample to the request for data.
	 * The situation is a little more complex; if a post processor has parameters then it needs to combine these into a string and offer that as an extension.
	 * The identity is just the starting part of this.
	 * <ol> 
	 * <li>For example, pp=firstSample_600 asks the server to sparsify with an interval of 600 seconds.</li> 
	 * <li>identity is firstSample.</li>
	 * <li>extension is firstSample_600.</li>
	 * <li>User specifies firstSample_600.</li>
	 * <li>ETL caches the data as firstSample_600 if asked to.</li>
	 * </ol>
	 * @return identify    
	 */
	public String getIdentity();
	
	
	/**
	 * This is the full form of the identity for the post processor and includes any parameters for the post processor.
	 * The exact format and interpretation of this is left to the post processor; however the convention is to use underscores to separate the params and have them in a specific order.
	 * @see getIdentity
	 * @return extension    
	 */
	public String getExtension(); 

	
	/**
	 * Initialize this post processor for the given PV and request parameters.
	 * @param userarg This is the full form (extension) of the identity for the post processor. 
	 * @param pvName The name of PV
	 * @throws IOException    
	 */
	public void initialize(String userarg, String pvName) throws IOException;
	
	/**
	 * Estimate the amount of memory required for the data generated by the post processors.
	 * @param pvName The name of PV
	 * @param typeInfo   PVTypeInfo 
	 * @param start Timestamp
	 * @param end Timestamp
	 * @param req HttpServletRequest 
	 * @return Estimated Memory comsumption
	 */
	public long estimateMemoryConsumption(String pvName, PVTypeInfo typeInfo, Timestamp start, Timestamp end, HttpServletRequest req);

	/**
	 * Primary data generation method. Using the event stream provided, do your magic and generate processed data
	 * @param callable    
	 * @return EventStream   
	 */
	public Callable<EventStream> wrap(Callable<EventStream> callable);
}