/*******************************************************************************
* Copyright (c) 2004, 2007 IBM Corporation and Cambridge Semantics Incorporated.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* File: $Source: /cvsroot/slrp/glitter/com.ibm.adtech.glitter/src/com/ibm/adtech/glitter/query/SolutionGenerator.java,v $
* Created by: Lee Feigenbaum (<a href="mailto:feigenbl@us.ibm.com">feigenbl@us.ibm.com</a>)
* Created on: 10/23/06
* Revision: $Id: SolutionGenerator.java 164 2007-07-31 14:11:09Z mroy $
*
* Contributors: IBM Corporation - initial API and implementation
* Cambridge Semantics Incorporated - Fork to Anzo
*******************************************************************************/
package org.openanzo.glitter.query;
import java.util.Set;
import org.apache.commons.collections15.MultiMap;
import org.openanzo.glitter.dataset.QueryDataset;
import org.openanzo.glitter.exception.GlitterException;
import org.openanzo.glitter.syntax.abstrakt.Expression;
import org.openanzo.glitter.syntax.abstrakt.TreeNode;
import org.openanzo.rdf.Variable;
/**
* A {@link SolutionGenerator} is a backend to the Glitter engine that knows how to generate a specific type of bindings.
*
* @author lee <lee@cambridgesemantics.com>
*
*/
public interface SolutionGenerator {
/**
*
* @return The unique ID of this instance of a query
*/
public String getQueryId();
/**
*
* @param dataset
* The {@link RDFDataset} against which the query is being executed.
*/
public abstract void setQueryDataset(QueryDataset dataset);
/**
*
* @param queryInformation
* Information on the parsed and prepared query.
*/
public abstract void setQueryInformation(QueryInformation queryInformation);
/**
*
* @param plan
* The execution plan in use.
*/
public abstract void setQueryExecutionPlan(QueryExecutionPlan plan);
/**
*
* @return Accessor to the dataset
*/
public abstract QueryDataset getQueryDataset();
/**
*
* @return Accessor to the parsed query
*/
public abstract QueryInformation getQueryInformation();
/**
*
* @return Accessor to the execution plan
*/
public abstract QueryExecutionPlan getQueryExecutionPlan();
/**
* @deprecated
* @return QueryExecutionServices for this SolutionGenerator
*/
@Deprecated
public abstract QueryExecutionServices getQueryExecutionServices();
/**
*
* @param node
* The node in the tree for which bindings are desired.
* @param namedGraph
* If not null, the solutions should be generated by matching against this graph from the named graph part of the RDF dataSet. Otherwise, the
* solutions should be generated from the default graph. (i.e., if not null, treat this graph as the default graph)
* @param namedGraphVariable
* If not null and this SolutionGenerator returns true for canBindGraphVariables(), then this is the variable that should be bound to the named
* graph IRI from which solutions are found.
* @param requiredBindings
* Known bindings at this point in the AST. Every returned solution should be a superset of one solution from the required bindings. (That is,
* unbound variables can be bound, but all bound variables must remain bound to the same value.) Note that Glitter enforces this constraint when
* combining pattern solutions.
*
* In general, if generateSolutions returns a value (null or otherwise), then the SolutionGenerator will not be called again for any descendants
* of node. If an exception is thrown, then generateSolution may be called for descendant (simpler) nodes.
* @param controller
* TODO
* @return A list of bindings (for variables and blank nodes) that satisfy the given tree node, or null if this pattern doesn't match.
* @throws GlitterException
*/
public abstract SolutionSet generateSolutions(TreeNode node, org.openanzo.rdf.URI namedGraph, Variable namedGraphVariable, SolutionSet requiredBindings, QueryController controller) throws GlitterException;
/**
* Called before any calls to generateSolutions but after all calls to set*.
*
* @throws GlitterException
*/
public abstract void initialize() throws GlitterException;
/**
* Called after all calls to generateSolutions.
*
* @throws GlitterException
*/
public abstract void cleanup() throws GlitterException;
/*
* The following methods provide information for the engine and query executor to use
* in determining how to traverse the query AST.
*/
/**
* Informative method.
*
* @return Whether or not this backend makes use of known constraints passed in when generating solutions.
*/
public abstract boolean usesRequiredBindings();
/**
* Informative method.
*
* @return Whether or not this backend can handle multiple requests in parallel.
*/
public abstract boolean canHandleSimultaneousRequests();
/**
* Informative method.
*
* @return Whether or not this backend can range over a graph variable and bind the variable to the appropriate graphs from the named graph part of the
* {@link RDFDataset}
*/
public abstract boolean canBindGraphVariables();
/**
* Many backends do not implement filters, in which case Glitter will filter results even if the solution generator handles a node which subsumes filters.
* (Other than an OPTIONAL -- a solution generator should only handle an OPTIONAL that includes a filter if it can handle the filter.)
*
* @param filters
* @return true if the solution generator will take care of these filters on any nodes that it sees, false if Glitter should handle the filters.
*/
public abstract boolean willHandleFilters(Set<Expression> filters);
/**
* Many backends do not special-case assignments, in which case Glitter will bind & join the variables in the assignments even if the solution generator
* handles a node which subsumes the assignments.
*
* @param assignments
* @return true if the solution generator will take care of these assignments on any nodes that it sees, false if Glitter should handle the assignments.
*/
public abstract boolean willHandleAssignments(MultiMap<Variable, Expression> assignments);
/**
*
* @return whether or not the generator sorts returned solutions as per any ORDER BY information
*/
public abstract boolean sortedSolutions();
}