/** Copyright (C) SYSTAP, LLC DBA Blazegraph 2006-2016. All rights reserved. Contact: SYSTAP, LLC DBA Blazegraph 2501 Calvert ST NW #106 Washington, DC 20008 licenses@blazegraph.com This program is free software; you can redistribute it and/or modify it under the terms of the GNU General License as published by the Free Software Foundation; version 2 of the License. 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 License for more details. You should have received a copy of the GNU General License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ /* * Created on May 20, 2007 */ package com.bigdata.rdf.store; import org.openrdf.model.Resource; import org.openrdf.model.Statement; import org.openrdf.model.URI; import org.openrdf.model.Value; import com.bigdata.rdf.model.BigdataStatement; import com.bigdata.rdf.model.BigdataStatementImpl; import com.bigdata.rdf.model.BigdataValue; import com.bigdata.rdf.model.StatementEnum; import com.bigdata.rdf.rules.InferenceEngine; import com.bigdata.rdf.spo.ISPO; import com.bigdata.rdf.spo.SPO; import com.bigdata.rdf.store.DataLoader.Options; import com.bigdata.relation.accesspath.EmptyAccessPath; import com.bigdata.relation.accesspath.IAccessPath; import com.bigdata.striterator.IChunkedOrderedIterator; /** * Interface for a triple -or- quad store. * <p> * Note: This API does NOT implement a Truth Maintenance (TM) strategy and by * itself only supports "explicit" triples. If the knowledge base is NOT to * store any entailments then the application MAY directly use this API to read * and write explicit statements on the knowledge base. However, if the * knowledge base is to directly store any entailments, then the application * MUST NOT invoke operations on this API that add statements to, or remove * statements from, the knowledge base as the entailments will not be updated * properly. * <p> * When entailments are stored in the knowledge base, a TM strategy MUST be used * to made those entailments based on the explicit triples asserted or retracted * by the application. When an application requests that statements are added to * a knowledge base that maintains entailments, the TM strategy MAY need to add * additional entailments to the knowledge base. When an application requests * that statement(s) are removed from the knowledge base, the TM strategy needs * to consider the state of the knowledge base. In general, a statement should * be removed IFF it was {@link StatementEnum#Explicit} AND the statement is no * longer entailed by the model theory and the remaining statements in the * knowledge base. * * @see IRawTripleStore * @see AbstractTripleStore * * @author <a href="mailto:thompsonbry@users.sourceforge.net">Bryan Thompson</a> * @version $Id$ */ public interface ITripleStore { /** * The #of named graphs. * * @throws UnsupportedOperationException * unless this is a quad store. */ long getNamedGraphCount(); /** * The #of triples in the named graph, or in the database if <i>c</i> is not * specified. * * @param c * The context (optional). * * @return The #of triples in the named graph or in the database. * * @deprecated by {@link #getStatementCount(Resource, boolean)} */ long getStatementCount(Resource c); /** * The #of triples in the store. * * @return The #of statements in the database. When either transactions or * key-range partitioned indices are being used, then this will be * an upper bound. * * @see #getStatementCount(boolean) * * @deprecated by {@link #getStatementCount(Resource, boolean)} */ long getStatementCount(); /** * The #of triples in the store. * * @param exact * When <code>true</code> the result will be an exact count, * which may require a full key-range scan of one of the * statement indices. * * @return The #of statements in the database. When <i>exact</i> is * <code>false</code> and either transactions or key-range * partitioned indices are being used, then this will be an upper * bound. * * @deprecated by {@link #getStatementCount(Resource, boolean)} */ long getStatementCount(boolean exact); /** * The #of triples in the named graph or in the database if no context is * specified. * * @param c * The context (optional). * @param exact * When <code>true</code> the result will be an exact count, * which may require a full key-range scan of one of the * statement indices. * * @return The #of statements in the named graph or in the database if * <i>c</i> is <code>null</code>. When <i>exact</i> is * <code>false</code> and either transactions or key-range * partitioned indices are being used, then this will be an upper * bound. */ long getStatementCount(Resource c, boolean exact); /** * The #of RDF {@link Value}s in the lexicon (this is not specific to any * named graph). * <p> * This may be an estimate when using partitioned indices. * <p> * Many RDF {@link Value}s are inlined into the statement indices. Inlined * values are not be reported by this method. */ long getTermCount(); /** * The #of URIs in the lexicon (this is not specific to any named graph). * <p> * This may be an estimate when using partitioned indices. * <p> * Many RDF {@link Value}s are inlined into the statement indices. Inlined * values are not be reported by this method. */ long getURICount(); /** * The #of Literals in the lexicon (this is not specific to any named * graph). * <p> * This may be an estimate when using partitioned indices. * <p> * Many RDF {@link Value}s are inlined into the statement indices. Inlined * values are not be reported by this method. */ long getLiteralCount(); /** * The #of BNodes in the lexicon (this is not specific to any named graph). * <p> * This may be an estimate when using partitioned indices. * <p> * This will always return ZERO (0) if * {@link AbstractTripleStore.Options#STORE_BLANK_NODES} is * <code>false</code> since there will not be any blank nodes in the * lexicon. * <p> * Many RDF {@link Value}s are inlined into the statement indices. Inlined * values are not be reported by this method. */ long getBNodeCount(); /** * Add a single {@link StatementEnum#Explicit} statement by lookup and/or * insert into the various indices (non-batch api). * <p> * Note: The non-batch API is horridly inefficient and can not be used to * co-reference blank nodes. The batch load API for Sesame {@link Value} * objects is: * * <pre> * * StatementBuffer buffer = new StatementBuffer(store, ...); * * buffer.add( s, p, o ); * ... * * buffer.flush(); * * </pre> * * @param s * The subject (required). * @param p * The predicate (required). * @param o * The object (required). * @param c * The context (required IFF a quad store and otherwise ignored). */ void addStatement(Resource s, URI p, Value o, Resource c); /** * @deprecated by {@link #addStatement(Resource, URI, Value, Resource)} */ void addStatement(Resource s, URI p, Value o); /** * Return true if the triple pattern matches any statements in the store * (non-batch API). * <p> * Note: This does not verify whether or not the statement is explicit. * * @param s * The subject (optional). * @param p * The predicate (optional). * @param o * The object (optional). * @param c * The context (optional and ignored unless a quad store). */ boolean hasStatement(Resource s, URI p, Value o, Resource c); /** * @deprecated by {@link #hasStatement(Resource, URI, Value, Resource)} */ boolean hasStatement(Resource s, URI p, Value o); /** * Return the statement from the database matching the fully bound query. * <p> * Note: If the parameters are from an {@link AbstractTripleStore} using a * different lexicon then you MUST either * {@link BigdataValue#clearInternalValue()} or create a new {@link Value} * object which either is not aware of the term identifier or does not have * its term identifier set in order to avoid lookup using the term * identifier rather than indirecting through the lexicon. * * @param s * The subject (required). * @param p * The predicate (required). * @param o * The object (required). * @param c * The context (required iff a quad store and otherwise ignored). * * @return The statement -or- <code>null</code> iff the triple is not * defined in the database. * * @see #asValue(Value) */ BigdataStatement getStatement(Resource s, URI p, Value o, Resource c); /** * @deprecated by {@link #getStatement(Resource, URI, Value, Resource)} */ BigdataStatement getStatement(Resource s, URI p, Value o); /** * Return an iterator that will visit all {@link BigdataStatement}s in the * database matching the triple pattern. * * @param s * The subject (optional). * @param p * The predicate (optional). * @param o * The object (optional). * @param c * The context (optional and ignored unless a quad store). * * @return The iterator. */ BigdataStatementIterator getStatements(Resource s, URI p, Value o, Resource c); /** * @deprecated by {@link #getStatements(Resource, URI, Value, Resource)} */ BigdataStatementIterator getStatements(Resource s, URI p, Value o); /** * Converts a {@link BigdataValue} to a Sesame {@link Value} object. * * @param value * Either a {@link BigdataValue}, a Sesame {@link Value} * object, or <code>null</code>. * * @return A corresponding Sesame {@link Value} object -or- * <code>null</code> iff <i>value</i> is <code>null</code>. */ BigdataValue asValue(Value value); /** * Unconditionally removes statement(s) matching the triple pattern (NO * truth maintenance). * * @param s * The subject (optional). * @param p * The predicate (optional). * @param o * The object (optional). * @param c * The context (optional). * * @return The #of statements removed. */ long removeStatements(Resource s, URI p, Value o, Resource c); /** * @deprecated by {@link #removeStatements(Resource, URI, Value, Resource)} */ long removeStatements(Resource s, URI p, Value o); /** * Returns an {@link IAccessPath} matching the triple pattern. * * @param s * The subject (optional). * @param p * The predicate (optional). * @param o * The object (optional). * @param c * The context (optional). * * @return The object that may be used to read efficiently on the indices * for that triple pattern. In the special case where any of the * given {@link Value}s is <strong>not known</strong> to the * database this method will return an {@link EmptyAccessPath}. * * @see IAccessPath * @see #asStatementIterator(IChunkedOrderedIterator) */ IAccessPath<ISPO> getAccessPath(Resource s, URI p, Value o, Resource c); /** * @deprecated by {@link #getAccessPath(Resource, URI, Value, Resource)} */ IAccessPath<ISPO> getAccessPath(Resource s, URI p, Value o); /** * Wraps an {@link IChunkedOrderedIterator} as a * {@link BigdataStatementIterator}. * <p> * Note: The object visited will be {@link BigdataStatementImpl}s. * * @param src * An {@link IChunkedOrderedIterator} visiting {@link SPO}s * * @return The {@link BigdataStatementIterator}. * * @see IAccessPath * @see #getAccessPath(Resource, URI, Value) */ BigdataStatementIterator asStatementIterator( IChunkedOrderedIterator<ISPO> src); /** * Convert an internal {@link ISPO} into a Sesame {@link Statement}. * <p> * Note: The object returned will be a {@link BigdataStatement} * * @param spo * The {@link ISPO}. * * @return The Sesame {@link Statement} -or- <code>null</code>. */ BigdataStatement asStatement(ISPO spo); /** * Return a {@link DataLoader} singleton configured using the properties * that were used to configure the database. * * @see Options */ DataLoader getDataLoader(); /** * Return an {@link InferenceEngine} singleton configured using the * properties that were used to configure the database. * <p> * Note: The first time this object is requested it will attempt to write * the axioms on the database. * * @see Options */ InferenceEngine getInferenceEngine(); /** * Discard the write set. * <p> * Note: The semantics of this operation depend on whether the database is * embedded (discards the write set), temporary (ignored since the store is * not restart safe), or a federation (ignored since unisolated writes on * the federation are atomic and auto-committed). */ void abort(); /** * Commit changes on the database. * <p> * Note: The semantics of this operation depend on whether the database is * embedded (does a commit), temporary (ignored), or a federation (ignored * since unisolated writes on the federation are atomic and auto-committed). * * @return commit time if store supports commit timestamps */ long commit(); /** * Deletes all data for the {@link ITripleStore}. */ void destroy(); /** * Close the connection to the {@link ITripleStore}. */ void close(); /** * True iff the database view is read-only. */ boolean isReadOnly(); /** * Return <code>true</code> iff this is a quad store. */ boolean isQuads(); }