xflminterface IF_QueryNodeSource : public XF_RefCount
This class represents a query node source. XFLAIM does not provide an implementation of this interface. It is up to the application to provide an implementation. It is a way for an application to plug in a callback mechanism that returns IF_DOMNode objects for a specific XPATH component in a query expression. It basically represents a set of DOM nodes. There are many ways an application could choose to represent a set of nodes - they might be specifically enumerated, or it may be a complete embedded sub-query that finds the nodes based on query criteria. In this way an application can embed queries within queries.
|
Method Summary |
|
| RCODE | searchCost - Return an estimate of the search cost so XFLAIM can choose whether to use this node source over another one. |
| RCODE | getFirst - Position to and return the first node from the set of nodes that belong to the node source. |
| RCODE | getLast - Position to and return the last node from the set of nodes that belong to the node source. |
| RCODE | getNext - Position to and return the next node from the set of nodes that belong to the node source. (The node source should always remember its current position in the set.) |
| RCODE | getPrev - Position to and return the previous node from the set of nodes that belong to the node source. (The node source should always remember its current position in the set.) |
| RCODE | getIndex - Return the database index used by this node source - only applicable if the node source is an embedded query. |
| RCODE | getOptInfoCount - Return the number of optimization information structures contained in this node source - only applicable if the node source is an embedded query. |
| RCODE | getOptInfo - Return optimization information structures contained in this node source - only applicable if the node source is an embedded query. |
| RCODE | copy - Create a new node source object, and copy the information from this node source object into the new node source object. |
| RCODE | releaseResources - Release any resources being held onto by this node source. The node source object is about to be released. |
|
Method Detail |
RCODE searchCost(
IF_Db * pDb,
FLMBOOL bNotted,
FLMUINT * puiCost,
FLMBOOL * pbMustScan);
Return an estimate of the search cost so XFLAIM can choose whether to use this node source over another one. This method will be called by XFLAIM during the optimization phase of query processing. If the node source is an embedded query, it should return the optimization cost that XFLAIM would calculate for that query.
Parameters In:
IF_Db* pDb Pointer to database object being used during optimization. FLMBOOL bNotted Is this particular node source notted? This may change how search cost is calculated.
Parameters Out
FLMUINT * puiCost Search cost is returned here. FLMBOOL * pbMustScan If the node source must do a scan of the database, that information is returned here. This will affect how XFLAIM chooses to optimize the query this node source is part of.
RCODE getFirst(
IF_Db * pDb,
IF_DOMNode * pContextNode,
IF_DOMNode ** ppNode,
FLMUINT uiTimeLimit
IF_QueryStatus * pQueryStatus);
Position to and return the first node from the set of nodes that belong to the node source.
Parameters In:
IF_Db* pDb Pointer to database object being used to retrieve data. The node source should always be set up with the assumption that it will get nodes from the same database and collection as the query that it is embedded in. IF_DOMNode * pContextNode This is the node that is the context node for retrieving a node from the node source. This may or may not be important to the node source. If the node source is one component of an xpath expression, this context node is the prior step of that expression. The node source should know what kind of DOM node to expect here and what it's relationship to it is in the overall XPATH expression it is a part of. FLMUINT uiTimeLimit Time limit (milliseconds) for completing the operation. Zero means there is no time limit. IF_QueryStatus * pQueryStatus This is the application supplied query status object. It should be called by this method to report progress as the node source retrieves the node to be returned. This is in case the node source object is an embedded query and has to examine many objects in order to find the node that is to be returned.
Parameters Out
IF_DOMNode * ppNode Found node is returned here, if any.
See Also: getLast, getNext, getPrev
RCODE getLast(
IF_Db * pDb,
IF_DOMNode * pContextNode,
IF_DOMNode ** ppNode,
FLMUINT uiTimeLimit
IF_QueryStatus * pQueryStatus);
Position to and return the last node from the set of nodes that belong to the node source.
Parameters In:
IF_Db* pDb Pointer to database object being used to retrieve data. The node source should always be set up with the assumption that it will get nodes from the same database and collection as the query that it is embedded in. IF_DOMNode * pContextNode This is the node that is the context node for retrieving a node from the node source. This may or may not be important to the node source. If the node source is one component of an xpath expression, this context node is the prior step of that expression. The node source should know what kind of DOM node to expect here and what it's relationship to it is in the overall XPATH expression it is a part of. FLMUINT uiTimeLimit Time limit (milliseconds) for completing the operation. Zero means there is no time limit. IF_QueryStatus * pQueryStatus This is the application supplied query status object. It should be called by this method to report progress as the node source retrieves the node to be returned. This is in case the node source object is an embedded query and has to examine many objects in order to find the node that is to be returned.
Parameters Out
IF_DOMNode * ppNode Found node is returned here, if any.
See Also: getFirst, getNext, getPrev
RCODE getNext(
IF_Db * pDb,
IF_DOMNode * pContextNode,
IF_DOMNode ** ppNode,
FLMUINT uiTimeLimit
IF_QueryStatus * pQueryStatus);
Position to and return the next node from the set of nodes that belong to the node source. It is the responsibility of a node source object to remember where it was last positioned in the set of nodes it returns. Note that if no calls have yet been made to retrieve nodes from the node source, this method should return the first node in the node source. In other words, it should behave the same as if getFirst had been called.
Parameters In:
IF_Db* pDb Pointer to database object being used to retrieve data. The node source should always be set up with the assumption that it will get nodes from the same database and collection as the query that it is embedded in. IF_DOMNode * pContextNode This is the node that is the context node for retrieving a node from the node source. This may or may not be important to the node source. If the node source is one component of an xpath expression, this context node is the prior step of that expression. The node source should know what kind of DOM node to expect here and what it's relationship to it is in the overall XPATH expression it is a part of. FLMUINT uiTimeLimit Time limit (milliseconds) for completing the operation. Zero means there is no time limit. IF_QueryStatus * pQueryStatus This is the application supplied query status object. It should be called by this method to report progress as the node source retrieves the node to be returned. This is in case the node source object is an embedded query and has to examine many objects in order to find the node that is to be returned.
Parameters Out
IF_DOMNode * ppNode Found node is returned here, if any.
See Also: getFirst, getLast, getPrev
RCODE getPrev(
IF_Db * pDb,
IF_DOMNode * pContextNode,
IF_DOMNode ** ppNode,
FLMUINT uiTimeLimit
IF_QueryStatus * pQueryStatus);
Position to and return the previous node from the set of nodes that belong to the node source. It is the responsibility of a node source object to remember where it was last positioned in the set of nodes it returns. Note that if no calls have yet been made to retrieve nodes from the node source, this method should return the last node in the node source - in other words, it should behave the same as if getLast had been called.
Parameters In:
IF_Db* pDb Pointer to database object being used to retrieve data. The node source should always be set up with the assumption that it will get nodes from the same database and collection as the query that it is embedded in. IF_DOMNode * pContextNode This is the node that is the context node for retrieving a node from the node source. This may or may not be important to the node source. If the node source is one component of an xpath expression, this context node is the prior step of that expression. The node source should know what kind of DOM node to expect here and what it's relationship to it is in the overall XPATH expression it is a part of. FLMUINT uiTimeLimit Time limit (milliseconds) for completing the operation. Zero means there is no time limit. IF_QueryStatus * pQueryStatus This is the application supplied query status object. It should be called by this method to report progress as the node source retrieves the node to be returned. This is in case the node source object is an embedded query and has to examine many objects in order to find the node that is to be returned.
Parameters Out
IF_DOMNode * ppNode Found node is returned here, if any.
See Also: getFirst, getLast, getNext
RCODE getIndex(
IF_Db * pDb,
FLMUINT * puiIndex,
FLMBOOL * pbHaveMultiple);
Return the database index being used for this node source. This method only makes sense if the node source is an embedded query. If the node source is not an embedded query, it should return zero in *puiIndex.
Parameters In:
IF_Db* pDb Pointer to database object being used to retrieve data. The node source should always be set up with the assumption that it will get nodes from the same database and collection as the query that it is embedded in.
Parameters Out
FLMUINT * puiIndex Index being used, if any is returned here. Note that this method only makes sense if the node source is an embedded query. If the node source is not an embedded query, it should return zero here. FLMBOOL * pbHaveMultiple Returns TRUE if multiple indexes are being used, FALSE otherwise.
See Also: getOptInfoCount, getOptInfo
RCODE getOptInfoCount(
IF_Db * pDb,
FLMUINT * puiOptInfoCount);
Return the number of optimization information structures contained in this node source. This method only makes sense if the node source is an embedded query. If the node source is not an embedded query, it should return zero in *puiOptInfoCount.
Parameters In:
IF_Db* pDb Pointer to database object being used to retrieve data. The node source should always be set up with the assumption that it will get nodes from the same database and collection as the query that it is embedded in.
Parameters Out
FLMUINT * puiOptInfoCount Number of optimization information structures contained in this node source. Note that this method only makes sense if the node source is an embedded query. If the node source is not an embedded query, it should return zero here.
See Also: getIndex, getOptInfo
RCODE getOptInfo(
IF_Db * pDb,
XFLM_OPT_INFO * pOptInfoArray,
FLMUINT uiNumOptInfoStructsToGet);
Return the optimization information structures contained in this node source. This method only makes sense if the node source is an embedded query. If the node source is not an embedded query, and getOptInfoCount returns zero, then this method will never get called by XFLAIM.
Parameters In:
IF_Db* pDb Pointer to database object being used to retrieve data. The node source should always be set up with the assumption that it will get nodes from the same database and collection as the query that it is embedded in. FLMUINT uiNumOptInfoStructsToGet Number of optimization structures to return. NOTE: This should always correspond to the number of optimization structures that was returned by getOptInfoCount. XFLAIM will always call getOptInfoCount before calling this method. Whatever value is returned from getOptInfoCount will be passed into this method in this parameter.
Parameters Out
XFLM_OPT_INFO * pOptInfoArray Pointer to an array of XFLM_OPT_INFO structures where the optimization information is to be returned. This array will contain the number of elements specified in uiNumOptInfoStructsToGet. Only that number of structures should be returned.
See Also: getIndex, getOptInfoCount
RCODE copy(
IF_QueryNodeSource ** ppNodeSourceCopy);
Create another IF_QueryNodeSource object and copy the information from this object into it. All information from this node source should be copied into the new node source. The new node source should be able to be independent of this node source. In other words, it should be possible to free this node source without affecting the new node source. XFLAIM calls the copy method whenever it clones a query object. If a query object contains a node source in one or more places in its query criteria, it is necessary to have complete and independent copies of those node sources inside the query criteria of the cloned query object.
Parameters In: none
Parameters Out:
IF_QueryNodeSource * ppNodeSourceCopy Newly created node source object is returned here.
void releaseResources( void);
Release any resources being held on to by this node source. This is usually done just before XFLAIM actually releases the object. It may be unnecessary to do anything in this method since the Release() method will be called shortly after.
Parameters In: none
Parameters Out: none