QBox Class Reference

#include <QBox.h>

Inherited by AggregateQBox, BSortQBox, CombineQBox, DelayQBox, ExistsQBox, FilterQBox, InsertQBox, JoinQBox, JoinStatic, LockQBox, LRWaitForQBox, MapQBox, MySQLQBox, ResampleQBox, RevisionAggregateQBox, RevisionFilterQBox, SControlQBox, SelectQBox, UnionQBox, UnlockQBox, UpdateQBox, and WaitForQBox.

List of all members.

---

Detailed Description

A box in the catalog.

QBox is an abstract class - each box type is a subclass of QBox (FilterQBox, JoinQBox, etc.).

The lifecycle of a QBox is as follows:

• Construction. The QBox is instantiated, generally by QBoxRegistry::instantiateBox.

• Population of input descriptions. Use setInputDescription() to tell the QBox what the input streams will look like.

• Setup. Call setup(). This invokes the QBox implementation's setupImpl(), which does one of the following:
  • if a typing (or other) error occurs, throws an AuroraTypingException (in which case the QBox is invalid and should just be deleted).

  • if setup succeeded, sets the list of output stream descriptions.

  For example, JoinQBox's setupImpl() method will verify that there are exactly two input streams and that all the parameters make sure (else throw an AuroraTypingException). It will parse the join predicate, saving the Predicate object in an instance variable. It will then create the output stream's description by combining the two input descriptions the appropriate way, and calling setOutputDescription(0, theNewDescription).

  If only type inferencing or validation is desired, then at this point the QBox can simply be destroyed.

• Population of input/output streams. At this point, the actual input and output streams themselves must be provided (recall that up to this point only the descriptions have been specified). Call setInput() to set the input streams, and setOutput() to set the output streams.

  Each input stream must match the corresponding input description provided before typechecking. Each output stream must match the output description generated by typechecking.

• Initialization. Call init(), which invokes initImpl(). This is the box's chance to initialize any state which is necessary to run the box (beyond any state necessary to do type inferencing).

• Running. The scheduler periodically calls run(), which calls runImpl(), which is responsible for processing tuples. runImpl() should read tuples from TupleQueue::DeqIterators (obtained by calling the protected deq() method) and outputs tuples to Stream::EnqIterator (obtained by calling the protected enq() method).

Public Member Functions
virtual	~QBox ()
	Destructor.
const DOMElement *	getCatalogElement () const
	Return a pointer to the DOMElement for this QBox in the catalog.
Table *	getTable () const
	Returns the table associated with this box, if any.
void	setTable (Table *table)
	Sets the table associated with this box.
const TupleDescription &	getInputDescription (unsigned int i) const
	Returns the description of the ith input stream, zero-relative.
void	setInputDescription (unsigned int i, ptr< TupleDescription > desc)
	Sets the description of the ith input stream, zero-relative.
void	setInputDescription (unsigned int i, const TupleDescription &desc)
	Sets the description of the ith input stream, zero-relative.
const TupleDescription &	getOutputDescription (unsigned int i) const
	Returns the description of the ith output stream, zero-relative.
void	setOutputDescription (unsigned int i, ptr< TupleDescription > desc)
	Sets the description of the ith output stream, zero-relative.
void	setOutputDescription (unsigned int i, const TupleDescription &desc)
	Sets the description of the ith output stream, zero-relative.
Stream &	getInput (unsigned int n) const
	Returns the ith input stream.
void	setInput (unsigned int i, Stream *desc)
	Sets the ith input stream.
Stream &	getOutput (unsigned int n) const
	Returns the ith output stream.
void	setCPView (ptr< CPView > cpview)
	Sets the CPView for this box This is called when the CPView is created in AuroraNode.
void	setOutput (unsigned int i, Stream *desc)
	Sets the ith output stream.
unsigned int	getNumInputs ()
	Returns the number of input streams.
unsigned int	getNumOutputs ()
	Returns the number of output streams.
string	getName () const
	Returns the name of the box.
string	getType () const
	Returns the type of the box.
string	as_string () const
	Returns a string representation of the box.
void	setup (AuroraNode &, const DOMElement *elt) throw (AuroraException)
	Set up the box.
void	init (PagePool &pool) throw (AuroraException)
	Initialize the box.
void	setPendingQueueState (ptr< QueueState > packed_queues)
void	unpackQueue (ptr< QueueState > packed_queue)
ptr< QueueState >	packQueues ()
virtual void	setPendingBoxState (ptr< AbstractBoxState > packed_box)
virtual void	unpackState (ptr< AbstractBoxState > box_state)
virtual ptr< AbstractBoxState >	packState ()
void	run (QBoxInvocation &inv)
	Runs the QBox. Should be called only by the scheduler.
void	scheduleRun ()
	Requests that the box get run again.
TupleQueue *	getInputQueue (unsigned int input)
	Returns the input queue corresponding to the inputth input stream.
string	param (string name, Params::Req req=PARAM_NOT_REQUIRED) const throw (AuroraBadEntityException)
string	param (string name, string def) const
template<typename T> bool	typedParam (string name, T &value, Params::Req req=PARAM_NOT_REQUIRED) const throw (AuroraBadEntityException)
const Params &	getParams ()
Static Public Member Functions
string	getBoxType (const DOMElement *) throw (AuroraException)
	Determine the type of a box from a DOM <box> tag.
QBox *	instantiate (const DOMElement *) throw (AuroraException)
Static Public Attributes
const Params::Req	PARAM_NOT_REQUIRED = Params::NOT_REQUIRED
const Params::Req	PARAM_REQUIRED = Params::REQUIRED
const Params::Req	PARAM_NON_EMPTY = Params::NON_EMPTY
Protected Types
typedef TupleQueue::DeqIterator	DeqIterator
typedef Stream::EnqIterator	EnqIterator
typedef TupleQueue::SeekIterator	SeekIterator
Protected Member Functions
	QBox ()
DeqIterator	deq (unsigned int index)
SeekIterator	seek (unsigned int index)
EnqIterator	enq (unsigned int index)
virtual void	setupImpl ()=0
virtual void	initImpl ()
virtual void	runImpl (QBoxInvocation &)
ptr< LockSet >	getLockSet (string name)
Protected Attributes
ptr< AbstractBoxState >	_pending_box_state
AuroraNode *	_node
ptr< CPView >	_cpview_on_input

---

Member Typedef Documentation

typedef TupleQueue::DeqIterator QBox::DeqIterator [protected]

typedef Stream::EnqIterator QBox::EnqIterator [protected]

typedef TupleQueue::SeekIterator QBox::SeekIterator [protected]

---

Constructor & Destructor Documentation

QBox::~QBox (   )  [virtual]

Destructor.

QBox::QBox (   )  [protected]

---

Member Function Documentation

string QBox::as_string (   )  const

Returns a string representation of the box.

DeqIterator QBox::deq (  unsigned int  index  )  [protected]

EnqIterator QBox::enq (  unsigned int  index  )  [protected]

string QBox::getBoxType (  const DOMElement *   )  throw (AuroraException) [static]

Determine the type of a box from a DOM <box> tag. Throws an exception if the <box> tag doesn't seem to be valid.

const DOMElement* QBox::getCatalogElement (   )  const

Return a pointer to the DOMElement for this QBox in the catalog. Should only be called by subclasses during setupImpl().

Stream& QBox::getInput (  unsigned int  n  )  const

Returns the ith input stream. Undefined behavior if no such input stream exists.

const TupleDescription& QBox::getInputDescription (  unsigned int  i  )  const

Returns the description of the ith input stream, zero-relative. Undefined behavior if no such input stream exists.

TupleQueue* QBox::getInputQueue (  unsigned int  input  )

Returns the input queue corresponding to the inputth input stream.

ptr< LockSet > QBox::getLockSet (  string  name  )  [protected]

string QBox::getName (   )  const

Returns the name of the box.

unsigned int QBox::getNumInputs (   )

Returns the number of input streams.

unsigned int QBox::getNumOutputs (   )

Returns the number of output streams.

Stream& QBox::getOutput (  unsigned int  n  )  const

Returns the ith output stream. Undefined behavior if no such input stream exists.

const TupleDescription& QBox::getOutputDescription (  unsigned int  i  )  const

Returns the description of the ith output stream, zero-relative. Undefined behavior if no such output stream exists.

const Params& QBox::getParams (   )

Table* QBox::getTable (   )  const

Returns the table associated with this box, if any.

string QBox::getType (   )  const

Returns the type of the box.

void QBox::init (  PagePool &  pool  )  throw (AuroraException)

Initialize the box. Calls setup() if setup has not yet been invoked. (The box must not have been inited already.)

virtual void QBox::initImpl (   )  [protected, virtual]

Reimplemented in AggregateQBox, BSortQBox, FilterQBox, JoinQBox, LockQBox, MapQBox, ResampleQBox, RevisionAggregateQBox, RevisionFilterQBox, SControlQBox, SJoinQBox, SOutputQBox, SUnionQBox, UnionQBox, UnlockQBox, WaitForQBox, JoinStatic, LRWaitForQBox, ExistsQBox, InsertQBox, SelectQBox, UpdateQBox, and MySQLQBox.

QBox * QBox::instantiate (  const DOMElement *   )  throw (AuroraException) [static]

ptr<QueueState> QBox::packQueues (   )

virtual ptr<AbstractBoxState> QBox::packState (   )  [virtual]

Reimplemented in AggregateQBox, FilterQBox, JoinQBox, SOutputQBox, and SUnionQBox.

string QBox::param (  string  name, string  def )  const

string QBox::param (  string  name, Params::Req  req = PARAM_NOT_REQUIRED )  const throw (AuroraBadEntityException)

void QBox::run (  QBoxInvocation &  inv  )

Runs the QBox. Should be called only by the scheduler.

virtual void QBox::runImpl (  QBoxInvocation &   )  [protected, virtual]

Reimplemented in AggregateQBox, BSortQBox, FilterQBox, JoinQBox, LockQBox, MapQBox, ResampleQBox, RevisionAggregateQBox, RevisionFilterQBox, SJoinQBox, SOutputQBox, SUnionQBox, UnionQBox, UnlockQBox, WaitForQBox, CombineQBox, DelayQBox, JoinStatic, LRWaitForQBox, ExistsQBox, InsertQBox, SelectQBox, UpdateQBox, and MySQLQBox.

void QBox::scheduleRun (   )

Requests that the box get run again. (Currently just calls notifyEnq() on the first input stream, which is a hack.)

SeekIterator QBox::seek (  unsigned int  index  )  [protected]

void QBox::setCPView (  ptr< CPView >  cpview  )

Sets the CPView for this box This is called when the CPView is created in AuroraNode.

void QBox::setInput (  unsigned int  i, Stream *  desc )

Sets the ith input stream.

void QBox::setInputDescription (  unsigned int  i, const TupleDescription &  desc )

Sets the description of the ith input stream, zero-relative.

void QBox::setInputDescription (  unsigned int  i, ptr< TupleDescription >  desc )

Sets the description of the ith input stream, zero-relative.

void QBox::setOutput (  unsigned int  i, Stream *  desc )

Sets the ith output stream.

void QBox::setOutputDescription (  unsigned int  i, const TupleDescription &  desc )

Sets the description of the ith output stream, zero-relative.

void QBox::setOutputDescription (  unsigned int  i, ptr< TupleDescription >  desc )

Sets the description of the ith output stream, zero-relative.

virtual void QBox::setPendingBoxState (  ptr< AbstractBoxState >  packed_box  )  [virtual]

Reimplemented in AggregateQBox, FilterQBox, JoinQBox, SOutputQBox, and SUnionQBox.

void QBox::setPendingQueueState (  ptr< QueueState >  packed_queues  )

void QBox::setTable (  Table *  table  )

Sets the table associated with this box.

void QBox::setup (  AuroraNode &  , const DOMElement *  elt )  throw (AuroraException)

Set up the box. (The box must not have been setup or inited yet.) See the QBox lifecycle overview.

virtual void QBox::setupImpl (   )  [protected, pure virtual]

Implemented in AggregateQBox, BSortQBox, FilterQBox, JoinQBox, LockQBox, MapQBox, ResampleQBox, RevisionAggregateQBox, RevisionFilterQBox, SControlQBox, SJoinQBox, SOutputQBox, SUnionQBox, UnionQBox, UnlockQBox, WaitForQBox, CombineQBox, DelayQBox, JoinStatic, LRWaitForQBox, ExistsQBox, InsertQBox, SelectQBox, UpdateQBox, and MySQLQBox.

template<typename T> bool QBox::typedParam (  string  name, T &  value, Params::Req  req = PARAM_NOT_REQUIRED )  const throw (AuroraBadEntityException)

void QBox::unpackQueue (  ptr< QueueState >  packed_queue  )

virtual void QBox::unpackState (  ptr< AbstractBoxState >  box_state  )  [virtual]

Reimplemented in AggregateQBox, FilterQBox, JoinQBox, SOutputQBox, and SUnionQBox.

---

Member Data Documentation

ptr<CPView> QBox::_cpview_on_input [protected]

AuroraNode* QBox::_node [protected]

ptr<AbstractBoxState> QBox::_pending_box_state [protected]

const Params::Req QBox::PARAM_NON_EMPTY = Params::NON_EMPTY [static]

const Params::Req QBox::PARAM_NOT_REQUIRED = Params::NOT_REQUIRED [static]

const Params::Req QBox::PARAM_REQUIRED = Params::REQUIRED [static]

---

The documentation for this class was generated from the following files:

• QBox.h
• QBox.cc

---