package tech.kivu.k2.api;
import tech.kivu.core.qc.classification.InterfaceAudience;
import tech.kivu.core.qc.classification.InterfaceStability;
import tech.kivu.k2.api.algos.IndicatorAlgorithm;
import tech.kivu.k2.api.data.GraphData;
import java.io.IOException;
import java.util.Set;
import java.util.concurrent.CompletableFuture;
/**
* This is, together with GraphContext and Algorithm, the main interface of Kivu's graph API, and
* one of the main avenues of communication between any user of the Kivu Core API and Tarim, the
* Kivu graph computing platform.
*/
@InterfaceAudience.Public
@InterfaceStability.Evolving
public interface Graph extends GraphData, EdgeArea, Registered, Output {
/**
* Writes graph (including modifications) to kgf file
*/
@Override
void save() throws IOException;
/**
* Loads graph (including modifications) from kgf file
*/
@Override
int load() throws IOException;
/**
* Retrieves a graph's context,as an instance of GraphContext
* @see GraphContext
* @return an instance of GraphContext, unique for this graph instance.
*
PLEASE NOTE: one and the same graph may be loaded, e.g. by different users,
* more than once from the same resource (e.g., a file in Kivu Graph Format). Each
* of these instances will then have a unique GraphContext associated with it.
* In other words: although the various graphs will be logically equal, they
* will still have physically unequal GraphContext instances.
*/
GraphContext getContext();
/**
* Is this a "null graph", i.e. a graph having zero vertices and zero edges ?
* @return true if this is a "null graph", false otherwise
*/
boolean isEmpty();
/**
* Interrogate this Graph on its persistence status. A persistent Graph will write all the updates made to it into
* its commit log, a non-persistent one will not. Commit log entries (aka GraphFacts) may be applied to both persistent
* and non-persistent graphs.
*
* @return isPersistent :: boolean
*/
boolean isPersistent();
/**
* Re-Run all available {@link IndicatorAlgorithm Indicator Algorithms} after previous algorithms have finished
*/
void runAlgorithmsAsync();
/**
* Run all available {@link IndicatorAlgorithm Indicator Algorithms} now
* @return a completable future containing nothing, usable as a call-back.
*/
CompletableFuture runAlgorithms();
/**
* Makes a partial, deep clone of this Graph constrained by the given set of (long) vertex IDs.
* The copy will have its own GraphContext.
* Only edges of which both the tail and the head are elements of the given vertex set will be in the copy.
*
* @param vertices set of vertices as integer
* @return (an implementation of) Graph
*/
Graph duplicate(final Set< Integer > vertices );
/**
* Makes a deep clone of this Graph.
* The copy will have its own GraphContext.
*
* @return (an implementation of) Graph
*/
@Override
Graph duplicate();
}
/*
* Richard Feynman on the deeper mechanisms at work behind quantum mechanics:
*
* One might still like to ask: "How does it work ? What is the machinery behind the law ?"
* No one has found any machinery behind the law. No on can "explain" any more than we have just "explained".
* No one will give you any deeper representation of the situation. We have no ideas about a more basic mechanism
* from which these results can be deduced.
*
* R. Feynman, "The Feynman Lectures on Physics", California Institute of Technology, 1965; from vol III, p. 1-10
*/