com.bigdata.rdf.internal
Interface IVCache<V extends BigdataValue,T>

All Known Subinterfaces:

IV<V,T>

All Known Implementing Classes:

AbstractBNodeIV, AbstractInlineExtensionIV, AbstractInlineIV, AbstractIV, AbstractLiteralIV, AbstractNonInlineExtensionIV, AbstractNonInlineExtensionIVWithDelegateIV, AbstractNonInlineIV, BlobIV, FullyInlineTypedLiteralIV, FullyInlineUnicodeBNodeIV, FullyInlineURIIV, LiteralExtensionIV, NumericBNodeIV, NumericIV, PartlyInlineTypedLiteralIV, PartlyInlineURIIV, SidIV, TermId, URIExtensionIV, UUIDBNodeIV, UUIDLiteralIV, VocabURIByteIV, VocabURIShortIV, XSDBooleanIV, XSDDecimalIV, XSDIntegerIV, XSDNumericIV, XSDUnsignedByteIV, XSDUnsignedIntIV, XSDUnsignedLongIV, XSDUnsignedShortIV

public interface IVCache<V extends BigdataValue,T>

Interface for managing the BigdataValue cached on an IV.

This interface is designed to support the query plan generator. The BigdataValue is cached when a query plan decides that the materialized value is required for a downstream operator.

Both IV and BigdataValue can cache one another. The pattern for caching is that you always cache the IV on the BigdataValue using BigdataValue.setIV(IV). However, the BigdataValue is normally NOT cached on the IV. The exception is when the BigdataValue has been materialized from the IV by joining against the lexicon.

Version:

$Id: IVCache.java 5829 2012-01-02 21:26:28Z thompsonbry $

Author:

Bryan Thompson

Method Summary

V	asValue(LexiconRelation lex) If the value is not already cached, then inflate an inline RDF value to a BigdataValue and cache it on a private field.
IV<V,T>	clone(boolean clearCache) Return a copy of this IV.
V	getValue() Return a pre-materialized RDF BigdataValue which has been cached on this IV by a previous invocation of asValue(LexiconRelation).
boolean	hasValue() Returns true if the RDF BigdataValue has been pre-materialized and cached on this IV.
V	setValue(V val) Cache the materialized Value.

Method Detail

asValue

V asValue(LexiconRelation lex)
                               throws UnsupportedOperationException

If the value is not already cached, then inflate an inline RDF value to a BigdataValue and cache it on a private field.

Note: Query plans are responsible for ensuring that IVs have been materialized before operators are evaluated which invoke this method. This pattern ensures that efficient batch operators are used to materialize Values, and thereby avoids heavy RMI overhead in scale-out, and provides operators which use getValue() with a simple method signature which does not require access to the lexicon. Query plans are also responsible for dropping variables once they are no longer needed or, in the case of large values and BLOBs, dropping the cached BigdataValue when possible in order to avoid excess network and heap overhead.

Parameters:

lex - The lexicon relation (this is required in order to access the BigdataValueFactory for the namespace associated with lexicon when we materialize an inline IV).

Returns:

The corresponding BigdataValue.

Throws:

UnsupportedOperationException - if the IV does not represent something which can be materialized. For example, a dummy value or a "null".

setValue

V setValue(V val)

Cache the materialized Value.

Note: This is normally invoked by asValue(LexiconRelation) during a lexicon join cache a newly materialized Value on the IV.

Parameters:

val - The BigdataValue.

getValue

V getValue()
                                throws NotMaterializedException

Return a pre-materialized RDF BigdataValue which has been cached on this IV by a previous invocation of asValue(LexiconRelation).

Returns:

The BigdataValue.

Throws:

NotMaterializedException - if the value is not cached.

clone

IV<V,T> clone(boolean clearCache)

Return a copy of this IV.

Note: This method exists to defeat the hard reference from the IV to the cached BigdataValue in order to avoid a memory leak when the IV is used as the key in a weak value cache whose value is the BigdataValue. Therefore, certain IV implementations MAY return this when they are used for limited collections. The vocabulary IVs are the primary example. For the same reason, we do not need to recursively break the link from the IV to the BigdataValue for IVs which embed other IVs.

Parameters:

clearCache - When true the cached reference (if any) will NOT be set on the copy.

Returns:

The copy.

See Also:

(Thread-local cache combined with unbounded thread pools causes effective memory leak)

hasValue

boolean hasValue()

Returns true if the RDF BigdataValue has been pre-materialized and cached on this IV.