KPIService.java

/*
 * Copyright 2019 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.genesys.server.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 org.genesys.server.model.kpi.Dimension;
import org.genesys.server.model.kpi.DimensionKey;
import org.genesys.server.model.kpi.Execution;
import org.genesys.server.model.kpi.ExecutionRun;
import org.genesys.server.model.kpi.KPIParameter;
import org.genesys.server.model.kpi.Observation;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;

import com.querydsl.core.Tuple;

public interface KPIService {

    /**
     * Details
     */
    static 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;
        }
    }

    static class GroupedRunObservations {
        public String dimensionValue;
        public Map<LocalDate, Double> runCountResult;
    
        public GroupedRunObservations() {
        }
    
        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);

    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);

}