com.bigdata.bop
Class BOpBase

java.lang.Object
  com.bigdata.bop.CoreBaseBOp
      com.bigdata.bop.BOpBase

All Implemented Interfaces:

BOp, IPropertySet, Serializable, Cloneable

Direct Known Subclasses:

AbstractAccessPathOp, AND, BOpFilterBase, Constraint, EQ, EQConstant, ImmutableBOp, INConstraint, InferenceBVE, IVValueExpression, NE, NEConstant, OR, PipelineOp, RejectAnythingSameAsItself, TryBeforeMaterializationConstraint

public class BOpBase
extends CoreBaseBOp

Abstract base class for copy-on-write BOps. The BOpBase class is used for query evaluation operators. The copy-on-write contract provides a safety margin during concurrent evaluation of query plans by ensuring that all references are fully published.

Instances of this class are effectively immutable (mutation APIs always return a deep copy of the operator to which the mutation has been applied), Serializable to facilitate distributed computing, and Cloneable to facilitate non-destructive tree rewrites.

Constructor patterns

BOps should define the following public constructors

public Class(BOp[] args, Map<String,Object> anns)

A shallow copy constructor. This is used when initializing a BOp from the caller's data or when generated a query plan from Prolog. There are some exceptions to this rule. For example, Constant does not define a shallow copy constructor because that would not provide a means to set the constant's value.

public Class(Class src)

A deep copy constructor. Mutation methods make a deep copy of the BOp, apply the mutation to the copy, and then return the copy. This is the "effectively immutable" contract. Again, there are some exceptions. For example, Var provides a canonicalized mapping such that reference tests may be used to determine if two Vars are the same. In order to support that contract it overrides Var.clone().

Version:

$Id: BOpBase.java 6286 2012-04-13 15:21:49Z mrpersonick $

Author:

Bryan Thompson

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface com.bigdata.bop.BOp

BOp.Annotations

Field Summary

Fields inherited from class com.bigdata.bop.CoreBaseBOp

DEFAULT_INITIAL_CAPACITY

Fields inherited from interface com.bigdata.bop.BOp

NOANNS, NOARGS

Constructor Summary

BOpBase(BOp[] args, Map<String,Object> annotations)
Shallow copy constructor (required).

BOpBase(BOpBase op)
Deep copy constructor (required).

Method Summary

protected void	_clearProperty(String name) Clear an annotation.
protected void	_set(int index, BOp op) Set the value of an operand.
protected Object	_setProperty(String name, Object value) Set an annotation.
Map<String,Object>	annotations() The operator's annotations.
protected Map<String,Object>	annotationsCopy() A copy of the annotations.
protected boolean	annotationsEqual(BOp o) Return true iff the annotations of this BOp and the other BOp are equals.
protected Map<String,Object>	annotationsRef() A reference to the actual annotations map object.
Iterator<BOp>	argIterator() An iterator visiting the operator's arguments.
List<BOp>	args() The operator's arguments as list.
protected BOp[]	argsCopy() A copy of the args[] array.
int	arity() The #of arguments to the operation.
BOp	clearAnnotations(String[] names) Strips off the named annotations.
BOpBase	clearProperty(String name) Clear the named annotation.
protected static BOp[]	deepCopy(BOp[] a) Deep copy the arguments.
protected static Map<String,Object>	deepCopy(Map<String,Object> a) Deep copy the annotations.
BOp	get(int index) Return an argument to the operation.
Object	getProperty(String name) Return the value of a named property.
BOpBase	setArg(int index, BOp newArg) Return a new BOpBase in which the child operand has been replaced by the given expression.
BOpBase	setProperty(String name, Object value) Unconditionally sets the property.
BOpBase	setUnboundProperty(String name, Object value) Conditionally sets the property.
BOp[]	toArray() A shallow copy of the operator's arguments.
<T> T[]	toArray(T[] a) A shallow copy of the operator's arguments using the generic type of the caller's array.

Methods inherited from class com.bigdata.bop.CoreBaseBOp

annotationsEqual, annotationsToString, checkArgs, clone, equals, getEvaluationContext, getId, getProperty, getRequiredProperty, hashCode, indent, isController, toShortString, toString

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

BOpBase

public BOpBase(BOpBase op)

Deep copy constructor (required).

Each BOp MUST implement a public copy constructor with the signature:

 public Foo(Foo)
 

This construct is invoked by CoreBaseBOp.clone() using reflection and is responsible for the deep copy semantics for the BOp.

The default implementation makes a deep copy of args() and annotations() but DOES NOT perform field-by-field copying. Subclasses may simply delegate the constructor to their super class unless they have additional fields which need to be copied.

This design pattern was selected because it preserves the immutable contract of the BOp which gives us our thread safety and visibility guarantees. Since the deep copy is realized by the BOp implementation classes, it is important that each class take responsibility for the deep copy semantics of any fields it may declare.

Parameters:

op - A deep copy will be made of this BOp.

Throws:

NullPointerException - if the argument is null.

BOpBase

public BOpBase(BOp[] args,
               Map<String,Object> annotations)

Shallow copy constructor (required).

Parameters:

args - The arguments to the operator.

annotations - The annotations for the operator (optional).

Method Detail

annotations

public final Map<String,Object> annotations()

Description copied from interface: BOp

The operator's annotations.

annotationsEqual

protected boolean annotationsEqual(BOp o)

Description copied from class: CoreBaseBOp

Return true iff the annotations of this BOp and the other BOp are equals.

Note: This method permits override by subclasses with direct access to the maps to be compared.

Overrides:

annotationsEqual in class CoreBaseBOp

See Also:

CoreBaseBOp.annotationsEqual(Map, Map)

argsCopy

protected final BOp[] argsCopy()

A copy of the args[] array.

annotationsCopy

protected final Map<String,Object> annotationsCopy()

A copy of the annotations.

annotationsRef

protected final Map<String,Object> annotationsRef()

A reference to the actual annotations map object. This is used in some hot spots to avoid creating a new annotations map when we know that the annotations will not be modified (annotations are always set within the context in which the BOpBase instance is created so we can know this locally by inspection of the code).

get

public BOp get(int index)

Description copied from interface: BOp

Return an argument to the operation.

Parameters:

index - The argument index in [0:BOp.arity()-1].

Returns:

The argument.

_set

protected final void _set(int index,
                          BOp op)

Set the value of an operand.

Note: This is protected to facilitate copy-on-write patterns. It is not public to prevent arbitrary changes to operators outside of methods which clone the operator and return the modified version. This is part of the effectively immutable contract for BOps.

Parameters:

index - The index.

op - The operand.

setArg

public BOpBase setArg(int index,
                      BOp newArg)

Return a new BOpBase in which the child operand has been replaced by the given expression.

Parameters:

index - The index of the child expression to be replaced.

newArg - The new child expression.

Returns:

A copy of this BOpBase in which the child operand has been replaced.

arity

public int arity()

Description copied from interface: BOp

The #of arguments to the operation.

args

public final List<BOp> args()

The operator's arguments as list.

Note: This is much less efficient than argIterator().

argIterator

public final Iterator<BOp> argIterator()

An iterator visiting the operator's arguments.

The iterator does not support removal. (This is more efficient than #args()).

toArray

public BOp[] toArray()

Description copied from interface: BOp

A shallow copy of the operator's arguments.

toArray

public <T> T[] toArray(T[] a)

Description copied from interface: BOp

A shallow copy of the operator's arguments using the generic type of the caller's array. If the array has sufficient room, then the arguments are copied into the caller's array. If there is space remaining, a null is appended to mark the end of the data.

deepCopy

protected static BOp[] deepCopy(BOp[] a)

Deep copy the arguments.

Note: As long as we stick to the immutable semantics for bops, we can just make a shallow copy of the arguments in the "copy" constructor and then modify them within the specific operator constructor before returning control to the caller. This would result in less heap churn.

deepCopy

protected static Map<String,Object> deepCopy(Map<String,Object> a)

Deep copy the annotations.

Note: This does not know how to deep copy annotations which are not BOps or immutable objects such as Strings or Numbers. Such objects should not be used as annotations.

TODO:

When attaching large data sets to a query plan they should be attached using a light weight reference object which allows them to be demanded by a node so deep copy remains a light weight operation. This also has the advantage that the objects are materialized on a node only when they are needed, which keeps the query plan small. Examples would be sending a temporary graph containing an ontology or some conditional assertions with a query plan.

getProperty

public Object getProperty(String name)

Description copied from interface: IPropertySet

Return the value of a named property.

Parameters:

name - The property name.

Returns:

The property value.

_setProperty

protected Object _setProperty(String name,
                              Object value)

Set an annotation.

Note: This is protected to facilitate copy-on-write patterns. It is not public to prevent arbitrary changes to operators outside of methods which clone the operator and return the modified version. This is part of the effectively immutable contract for BOps.

Parameters:

name - The name.

value - The value.

Returns:

The old value.

_clearProperty

protected void _clearProperty(String name)

Clear an annotation.

Note: This is protected to facilitate copy-on-write patterns. It is not public to prevent arbitrary changes to operators outside of methods which clone the operator and return the modified version. This is part of the effectively immutable contract for BOps.

Parameters:

name - The name.

setProperty

public BOpBase setProperty(String name,
                           Object value)

Description copied from interface: BOp

Unconditionally sets the property.

Parameters:

name - The name.

value - The value.

Returns:

A copy of this BOp on which the property has been set.

setUnboundProperty

public BOpBase setUnboundProperty(String name,
                                  Object value)

Conditionally sets the property.

Parameters:

name - The name.

value - The value.

Returns:

A copy of this BOp on which the property has been set.

Throws:

IllegalStateException - if the property is already set.

clearProperty

public BOpBase clearProperty(String name)

Clear the named annotation.

Parameters:

name - The annotation.

Returns:

A copy of this BOp in which the named annotation has been removed.

clearAnnotations

public BOp clearAnnotations(String[] names)

Strips off the named annotations.

Parameters:

names - The annotations to be removed.

Returns:

A copy of this BOp in which the specified annotations do not appear.