KPIService.java

/*
 * Copyright 2020 Global Crop Diversity Trust
 *
 * 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 org.gringlobal.service;

import java.time.LocalDate;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.SortedMap;

import javax.validation.Valid;

import com.querydsl.core.Tuple;
import lombok.NoArgsConstructor;
import org.gringlobal.model.kpi.Dimension;
import org.gringlobal.model.kpi.DimensionKey;
import org.gringlobal.model.kpi.Execution;
import org.gringlobal.model.kpi.ExecutionRun;
import org.gringlobal.model.kpi.KPIParameter;
import org.gringlobal.model.kpi.Observation;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;

public interface KPIService {

	/**
	 * Details
	 */
	class ExecutionDetails {
		public Execution execution;
		public ExecutionRun lastRun;
		public Page<ExecutionRun> runs;

		public static ExecutionDetails from(Execution execution, ExecutionRun lastRun, Page<ExecutionRun> runs) {
			ExecutionDetails ed = new ExecutionDetails();
			ed.execution=execution;
			ed.lastRun = lastRun;
			ed.runs = runs;
			return ed;
		}
	}

	@NoArgsConstructor
	class GroupedRunObservations {
		public String dimensionValue;
		public Map<LocalDate, Double> runCountResult;

		public GroupedRunObservations(String dimensionValue, Map<LocalDate, Double> runCountResult) {
			this.dimensionValue = dimensionValue;
			this.runCountResult = runCountResult;
		}
	}

	public static class ExecutionRunsRequest {
		public List<LocalDate> dates;
		public Map<String, Set<String>> keys;
	}

	KPIParameter save(@Valid KPIParameter parameter);

	KPIParameter getParameter(String name);

	KPIParameter getParameter(long id);

	KPIParameter delete(KPIParameter parameter);

	<T extends Dimension<?>> T save(@Valid T dimension);

	Dimension<?> getDimension(long id);

	Dimension<?> getDimension(String name);

	<T extends Dimension<?>> T delete(T dimension);

	<T> Set<T> getValues(Dimension<T> loadedJpa);

	Execution save(@Valid Execution execution);

	Execution loadExecution(String executionName);

	Execution getExecution(long id);
	Execution getExecution(String executionName);

	Execution delete(Execution execution);

	List<Observation> execute(Execution execution);
	ExecutionRun executeAndSave(Execution execution);

	Page<KPIParameter> listParameters(Pageable page);

	Page<Dimension<?>> listDimensions(Pageable page);

	Page<Execution> listExecutions(Pageable page);
	List<Execution> listExecutions();

	Page<Observation> listObservations(ExecutionRun executionRun, Map<String, String> dimensionFilters, Pageable page);
	Page<Observation> listObservations(Execution execution, long dimensionKeyId, Pageable pageable);

	ExecutionRun findLastExecutionRun(Execution execution);

	ExecutionRun findExecutionRunByDate(Execution execution, LocalDate date);

	void deleteObservations(ExecutionRun executionRun);

	Page<ExecutionRun> listExecutionRuns(Execution execution, Pageable pageable);

	ExecutionRun getExecutionRun(long runId);

	/**
	 * List selected observations of an execution with the executionRun#timestamp.
	 *
	 * @param execution the execution
	 * @param from the from
	 * @param to the to
	 * @param keys the keys
	 * @param page the page
	 * @return the page
	 */
	Page<Tuple> listObservations(Execution execution, LocalDate from, LocalDate to, Map<String, Set<String>> keys, Pageable page);

	List<Observation> filterObservations(Execution execution, LocalDate date, Map<String, Set<String>> keys);

	/**
	 * Calculate differences in observations starting at 'to' date, comparing observations
	 * with the earlier runs until since 'from' date.
	 *
	 * @param execution the execution
	 * @param from the date of the earliest run
	 * @param to the date of the latest run
	 * @return the sorted map keyed by run date, containing run differences
	 */
	SortedMap<LocalDate, List<Observation>> calculateRunDiff(Execution execution, LocalDate from, LocalDate to, Map<String, Set<String>> keys);

	/**
	 * Remove runs that have the same observations and don't add much value.
	 *
	 * @param execution the execution
	 * @return
	 */
	long purgeExecutionRuns(Execution execution);

	/**
	 * Find observations by dates and filter.
	 *
	 * @param execution the execution
	 * @param runsRequest the execution runs request
	 * @return the map of observations for dates
	 */
	SortedMap<LocalDate, List<Observation>> findExecutionRuns(Execution execution, ExecutionRunsRequest runsRequest);

	/**
	 * Get observations grouped by dimension.
	 *
	 * @param execution the execution
	 * @param dimensionName the dimension for grouping
	 * @param toDate the date for searching
	 * @param maxRuns the max execution runs number
	 * @return the list of GroupedRunObservations
	 */
	List<GroupedRunObservations> getObservationsGroupedByDimension(Execution execution, String dimensionName, LocalDate toDate, Integer maxRuns);

	/**
	 * Get the dimension keys generated by {@code execution} in its runs.
	 * 
	 * @param execution the execution
	 * @param dimensionNames names of dimensions
	 * @return List of dimension keys
	 */
	List<DimensionKey> getDimensionKeys(Execution execution, Set<String> dimensionNames);

	/**
	 * Delete KPI run
	 * @param run run to delete
	 * @return the deleted run
	 */
	ExecutionRun delete(ExecutionRun run);

}