com.bigdata.rdf.spo
Interface ISPO

All Known Subinterfaces:

BigdataStatement

All Known Implementing Classes:

BigdataStatementImpl, SPO

public interface ISPO

A interface representing an RDF triple, an RDF triple with a statement identifier, or an RDF quad. The slots are 64-bit long term identifiers assigned by a lexicon. The 4th position is either unused (triples), the statement identifier (triples with the provenance mode enabled), or the context/named graph position of a quad. This interface treats all four positions as "data" and requires the caller to be aware of the database mode (triples, triples+SIDs, or quads). The (s,p,o) of the interface are immutable. The (c) position is mutable because its value is not knowable until after the other three values have been bound in the triples+SIDs database mode. When using this interface for a quads mode database, the context position SHOULD be set by the appropriate constructor and NOT modified thereafter.

Two additional data are carried by this interface for use with inference and truth maintenance. First, this interface may also carry an indication of whether the triple/quad is an explicit statement, an inferred statement or an axiom. Second, the isOverride() flag is used during truth maintenance when an explicit statement is retracted and we need to downgrade the statement in the database to an inference because it is still provable by other statements in the knowledge base.

Version:

$Id: ISPO.java 2265 2009-10-26 12:51:06Z thompsonbry $

Author:

Bryan Thompson

Field Summary

static long

NULL The constant that indicates an unassigned term identifier.

Method Summary

long	c() The term identifier for the SID/context position (slot 3) -or- NULL.
long	get(int index) Return the s,p,o, or c value corresponding to the given index.
long	getStatementIdentifier() The statement identifier (optional).
StatementEnum	getStatementType() Whether the statement is StatementEnum.Explicit, StatementEnum.Inferred or an StatementEnum.Axiom.
boolean	hasStatementIdentifier() true IFF AbstractTripleStore.isStatement(long) returns true for c().
boolean	hasStatementType() Return true iff the statement type is known.
boolean	isAxiom() Return true IFF the SPO is marked as StatementEnum.Axiom.
boolean	isExplicit() Return true IFF the SPO is marked as StatementEnum.Explicit.
boolean	isFullyBound() Return true iff all position (s,p,o) are non-NULL.
boolean	isInferred() Return true IFF the SPO is marked as StatementEnum.Inferred.
boolean	isOverride() When true the statement will be written onto the database with exactly its current getStatementType() (default false).
long	o() The term identifier for the object position (slot 2) -or- NULL.
long	p() The term identifier for the predicate position (slot 1) -or- NULL.
long	s() The term identifier for the subject position (slot 0) -or- NULL.
byte[]	serializeValue(ByteArrayBuffer buf) Return the byte[] that would be written into a statement index for this ISPO, including the optional StatementEnum.MASK_OVERRIDE bit.
void	setOverride(boolean override) Set the override flag.
void	setStatementIdentifier(long sid) Set the statement identifier.
void	setStatementType(StatementEnum type) Set the statement type for this statement.
String	toString(IRawTripleStore db) Method may be used to externalize the BigdataValues in the ISPO.

Field Detail

NULL

static final long NULL

The constant that indicates an unassigned term identifier.

See Also:

IRawTripleStore.NULL, Constant Field Values

Method Detail

s

long s()

The term identifier for the subject position (slot 0) -or- NULL.

p

long p()

The term identifier for the predicate position (slot 1) -or- NULL.

o

long o()

The term identifier for the object position (slot 2) -or- NULL.

c

long c()

The term identifier for the SID/context position (slot 3) -or- NULL. The semantics of the returned value depend on the database mode. For triples, it is unused. For triples+SIDs, it is the statement identifier as assigned by the lexicon. For quads, it is the context (aka named graph) and NULL iff the context was not bound.

See Also:

AbstractTripleStore.Options#STATEMENT_IDENTIFIERS, AbstractTripleStore.Options#QUADS

get

long get(int index)

Return the s,p,o, or c value corresponding to the given index.

Parameters:

index - The legal values are: s=0, p=1, o=2, c=3.

isFullyBound

boolean isFullyBound()

Return true iff all position (s,p,o) are non-NULL.

Note: SPOs are sometimes used to represent triple patterns, e.g., in the tail of a Justification. This method will return true if the "triple pattern" is fully bound and false if there are any unbound positions.

Note: BigdataStatements are not fully bound when they are instantiated during parsing until their term identifiers have been resolved against a database's lexicon. FIXME quads : this method might need to be aware of the database mode, e.g., pass in [boolean quads]. if its semantics are restricted to whether the triple pattern is fully bound, then clarify that here.

getStatementType

StatementEnum getStatementType()

Whether the statement is StatementEnum.Explicit, StatementEnum.Inferred or an StatementEnum.Axiom.

Returns:

The StatementEnum type -or- null if the statement type has not been specified.

setStatementType

void setStatementType(StatementEnum type)

Set the statement type for this statement.

Parameters:

type - The statement type.

Throws:

IllegalArgumentException - if type is null.

IllegalStateException - if the statement type is already set to a different non- null value.

hasStatementType

boolean hasStatementType()

Return true iff the statement type is known. true iff the statement type is known for this statement.

isExplicit

boolean isExplicit()

Return true IFF the SPO is marked as StatementEnum.Explicit.

isInferred

boolean isInferred()

Return true IFF the SPO is marked as StatementEnum.Inferred.

isAxiom

boolean isAxiom()

Return true IFF the SPO is marked as StatementEnum.Axiom.

setStatementIdentifier

void setStatementIdentifier(long sid)

Set the statement identifier. This sets the 4th position of the quad, but some constraints are imposed on its argument.

Parameters:

sid - The statement identifier.

Throws:

IllegalArgumentException - if sid is NULL.

IllegalStateException - if the statement identifier is already set.

getStatementIdentifier

long getStatementIdentifier()

The statement identifier (optional). This has nearly identical semantics to c(), but will throw an exception if the 4th position is not bound.

Statement identifiers are a unique per-triple identifier assigned when a statement is first asserted against the database and are are defined iff AbstractTripleStore.Options#STATEMENT_IDENTIFIERS was specified.

Throws:

IllegalStateException - unless a statement identifier is assigned to this ISPO.

hasStatementIdentifier

boolean hasStatementIdentifier()

true IFF AbstractTripleStore.isStatement(long) returns true for c().

setOverride

void setOverride(boolean override)

Set the override flag.

Parameters:

override - the new value.

isOverride

boolean isOverride()

When true the statement will be written onto the database with exactly its current getStatementType() (default false).

Note: This feature is used by TruthMaintenance when we need to downgrade an ISPO from "Explicit" to "Inferred". Normally, a statement is automatically upgraded from "Inferred" to "Explicit" so without setOverride(boolean) you could not downgrade the StatementEnum in the database without first deleting the statement (which would also delete its justifications).

serializeValue

byte[] serializeValue(ByteArrayBuffer buf)

Return the byte[] that would be written into a statement index for this ISPO, including the optional StatementEnum.MASK_OVERRIDE bit. If the hasStatementIdentifier() would return true, then the SID will be included in the returned byte[]. Note that hasStatementIdentifier() is defined in terms of the bit pattern of the SID identifiers and therefore will be true ONLY for a statement identifier and NOT for an RDF Value identifier.

Parameters:

buf - A buffer supplied by the caller. The buffer will be reset before the value is written on the buffer.

Returns:

The value that would be written into a statement index for this ISPO.

toString

String toString(IRawTripleStore db)

Method may be used to externalize the BigdataValues in the ISPO.

Parameters:

db - The database whose lexicon will be used.