com.graphaware.reco.generic.context.Context Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of recommendation-engine Show documentation
Skeleton for a Recommendation Engine
The newest version!
/*
 * Copyright (c) 2013-2016 GraphAware
 *
 * This file is part of the GraphAware Framework.
 *
 * GraphAware Framework is free software: you can redistribute it and/or modify it under the terms of
 * the GNU General Public License as published by the Free Software Foundation, either
 * version 3 of the License, or (at your option) any later version.
 *
 * 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. You should have received a copy of
 * the GNU General Public License along with this program.  If not, see
 * .
 */

package com.graphaware.reco.generic.context;

import com.graphaware.reco.generic.config.Config;
import com.graphaware.reco.generic.stats.Statistics;

/**
 * Context holding information about the recommendation-computing process. All methods of implementing classes can be
 * called by multiple threads simultaneously, thus must be thread-safe.
 */
public interface Context {

    /**
     * Get config.
     *
     * @return configuration for the recommendation-computing process. Never null.
     */
    Config config();

    /**
     * @return for which recommendations are being computed. Must not be null.
     */
    IN input();

    /**
     * Get config in a type-safe manner.
     *
     * @param clazz of the config.
     * @return configuration for the recommendation-computing process. Never null.
     * @throws IllegalArgumentException if the config isn't of the specified type.
     */
     C config(Class clazz);

    /**
     * @return true iff there's still time left for the computation, i.e. iff less time has elapsed so far
     * than returned by {@link Config#maxTime()}.
     */
    boolean timeLeft();

    /**
     * Check whether a produced recommendation is allowed for the given input in the current context.
     *
     * @param recommendation produced. Must not be null.
     * @param task           name of the task that is asking the "allow?" question. Must not be null.
     *                       Used for statistics and logging.
     * @return true iff the recommendation is allowed for the given input.
     */
    boolean allow(OUT recommendation, String task);

    /**
     * Disallow the given recommendation. Intended for {@link com.graphaware.reco.generic.engine.RecommendationEngine}s
     * to prevent other engines that follow from discovering the same recommendation.
     *
     * @param recommendation to disallow.
     */
    void disallow(OUT recommendation);

    /**
     * Get the statistics of the computation process that this context is for.
     *
     * @return stats.
     */
    Statistics statistics();
}