edu.wpi.cs.dsrg.xmldb.xat.component.statisticsgatherer
Class StatisticsGatherer

java.lang.Object
  |
  +--edu.wpi.cs.dsrg.xmldb.xat.common.operator.XATPropertiesImp
        |
        +--edu.wpi.cs.dsrg.xmldb.xat.component.statisticsgatherer.StatisticsGatherer

public final class StatisticsGatherer
extends XATPropertiesImp
implements java.io.Serializable

StatisticsGatherer is a large statistics engine that supports arbitrary statistics and many different access methods. See below for a description on using this Gatherer, including how to add new properties, retrieve values, retrive objects, and update values

The Gatherer works by organizing statistics into categories. The statsTable will always have 2 categories called HISTORICAL and GENERIC(records are identified by a Object identifier right now). HISTORICAL keeps track of the statistics for the operators regardless of the scheduling algorithm or query plan. HISTORICAL also contains the aggregate stats for the whole system.

GENERIC contains basic statistics that do not depend on the category. These statistics, such as NUMBER_OF_TUPLES_IN_INPUT_QUEUES, should have the same values regardless of the category, otherwise, there are consistency issues.

Because the HISTORICAL name may (and has already) change, it is safest to refer to it using StatisticsGatherer.OVERALL

Additional categories can be added to the statsTable that will correspond to smaller views of the overall statistics. For example, categories could be added that correspond to a particular scheduling algorithm or a certain plan.

The individual categories are organized by property names. The property names are are gathered using XATQueryObject.getProperties(). Each property name has a ModifiedArrayList (extention of ArrayList with some different access methods) that sorts the XATOperators based on the property. Queries, such as what is the operator with the lowest (insert propery name), can be made against the Gatherer

The StatisticsGather should be used as follows:

  1. getStatisticsGatherer() This will instantiate the statisticsGather. Note that there can only be 1 statistics gatherer so subsequent calls will just return a handle to the lone statsisticsGatherer
  2. initStatsTable(XATTree) or initStatsTable(XATNode[]) This will initialize the statsTable with the given XATNodes This can only be called once.
  3. The rest depends on what you want to do:
    1. To add a new XATQueryObject: addNewQueryObject(newQueryObject)
    2. To add a new statistics category with a given description: addNewCategory(Object)

    3. To have the StatisticsGatherer work with a new property:
      • If the property requires a special calculation besides just replacing the old value with a new one (such as LAST_TIME_RUN), then:
        1. you need to create a new StatisticsObject type and implement the calculateNewValue() or calculateNewValue(String). Use the 2nd method if you require some outside information to calculate the value. The first is used if no outside information is used.
        2. you need to update StatisticsReference.initReferenceTable() with the name of the property and the name of the StatisticsObject that calculates the property. You should also decide if it is a category specific or a generic statistics. See StatisticsReference for more.
      • If the property does not require a special calculation, then you dont have to do anything extra
      For the rest of the operations, it is important to note that the category is not specified each time. This makes it easier to to access data without specifying the same parameter over and over. To change the category, use setCurrentCategory(Object)

    4. To add a new value of a property to the Gatherer: updateValue(String propertyName, XATOperator operator) Note: This will update the value for the current category as well as OVERALL (if the currentcategory != OVERALL)
    5. To get a value of a property of a QueryObject from the Gatherer: getValue(String propertyName, XATQueryObject queryObject)

      This last method is probably the most useful and powerful in the StatisticsGatherer

    6. To get a QueryObject with a certain value for a given property:
      • getOperator(String propertyName, int identifier)
      • getQueue(String propertyName, int identifier)
      • getQueryObject(String propertyName, int identifier
      Note: The first two are merely convience methods and they avoid casting on the client end. They are identical to calling getQueryObject and then casting.

      The identifier is any of the static constants found in StatisticsReference. Some examples are FIRST, LAST, HIGHEST, LOWEST, and AVERAGE. Depending on the identifier, the method will return the XATQueryObject whose propertyValue matches the given identifier with respect to the other XATQueryObjects.

See Also:
Serialized Form

Field Summary
static java.lang.String GENERIC
           
static java.lang.String OVERALL
           
 
Method Summary
 void addNewCategory(java.lang.Object identifier)
          Adds a new category of statistics into the StatisticsGatherer A category is defined as a grouping of statistics.
 void addNewQueryObject(XATQueryObject newQueryObject)
          Add an QueryObject to the statsTable.
 void addNewQueryObject(XATQueryObject[] newQueryObjects)
          Adds an array of QueryObject to the statsTable.
 java.util.Iterator getAllKnownQueryObjects()
          Returns an Iterator of all of the query objects that are known in this stats gatherer.
 java.util.Enumeration getCategories()
          Returns the currentCategory
 java.lang.Object getCurrentCategory()
          Returns the currentCategory
 XATQueryObject getQueryObject(java.lang.String propertyName, int valueIdentifier)
          Gets the XATQueryObject whose propertyValue corresponds to the propertyName and valueIdentifier in the currentCategory.
 XATQueryObject getQueryObject(java.lang.String propertyName, int valueIdentifier, boolean updateValue)
          Gets the XATQueryObject whose propertyValue corresponds to the propertyName and valueIdentifier in the currentCategory.
static StatisticsGatherer getStatisticsGather()
          we want there to be only 1 statistics gatherer so a singleton design pattern is used.
 java.lang.String getValue(java.lang.String propertyName, XATQueryObject queryObject)
          Returns the value for given property of the queryObject in the current category Creation date: (1/15/2003 2:05:37 PM)
 java.lang.String getValue(java.lang.String propertyName, XATQueryObject queryObject, int description)
          Returns the value for given property of the queryObject in the current category If this statistics object does not support this operation, an error will be thrown
 void initStatsTable(XATTree initTree)
          Allows you to specify an initial XATTree that contains all of the operators.
 boolean isStatisticSupported(java.lang.String propertyName)
          Checks if the propertyName is in the StatisticsGatherer
 void removeQueryObject(XATQueryObject object)
          Removes a query object from the statistics gatherer.
 void reset()
          This will reset the statistics gatherer to its pre-init state.
 void setCurrentCategory(java.lang.Object newCurrentCategory)
          Set the current category.
protected  void setDefaultProperties()
          called by the constructor.
 java.lang.String toString()
          Insert the method's description here.
 void updateValue(java.lang.String propertyName, XATQueryObject queryObject)
          This will update the given propertyName for the currentCategory.
 void updateValue(java.lang.String propertyName, XATQueryObject queryObject, java.lang.String newPropertyValue)
          This will update the given propertyName for the currentCategory.
 
Methods inherited from class edu.wpi.cs.dsrg.xmldb.xat.common.operator.XATPropertiesImp
addProperty, getProperties, getProperty, isValidPropertyName, setNewPropertyValue, setProperty
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

OVERALL

public static final java.lang.String OVERALL

GENERIC

public static final java.lang.String GENERIC
Method Detail

addNewCategory

public void addNewCategory(java.lang.Object identifier)
                    throws java.lang.Exception
Adds a new category of statistics into the StatisticsGatherer A category is defined as a grouping of statistics. For example, some categories would be Scheduling algorithms, XATTrees, or any other object. The only category that cannot be added is one with a String Identifier named "OVERALL". This category is used in the StatisticsGather by default so adding another would create problems

Before categories can be added, the statsgather must have been initialized.

One problem with this is that the new catgory will have its starting values set to thato of the OVERALL category. I am not sure how to get around this, nor do I know if it is a major problem. If all of the categories are initialized at the beginning, then it will not matter much, if at all.

Parameters:
identifier - java.lang.Object
Throws:
XATStatisticsException - if the category named identifier already exists in the statistic gatherer

addNewQueryObject

public void addNewQueryObject(XATQueryObject[] newQueryObjects)
Adds an array of QueryObject to the statsTable. This seems like a relatively expensive operation.
Parameters:
newQueryObject -  

addNewQueryObject

public void addNewQueryObject(XATQueryObject newQueryObject)
Add an QueryObject to the statsTable. This seems like a relatively expensive operation.
Parameters:
newQueryObject -  

getAllKnownQueryObjects

public java.util.Iterator getAllKnownQueryObjects()
Returns an Iterator of all of the query objects that are known in this stats gatherer. This is useful for making queries against the statsGather when the query objects are not known.

This does not traverse the GENERIC query objects b/c those generally are not useful except to calculate other statistics.

Note, this is an expensive operation. It runs on the order of n^2 where n is the number of query objects in the system.

Returns:
java.util.Iterator

getCategories

public java.util.Enumeration getCategories()
Returns the currentCategory
Returns:
java.lang.Object

getCurrentCategory

public java.lang.Object getCurrentCategory()
Returns the currentCategory
Returns:
java.lang.Object

getQueryObject

public XATQueryObject getQueryObject(java.lang.String propertyName,
                                     int valueIdentifier)
Gets the XATQueryObject whose propertyValue corresponds to the propertyName and valueIdentifier in the currentCategory.

For example, getQueryObject("SELECTIVITY", StatisticsReference.LOWEST) will return the XATQueryObject with the lowest selectivity within the currentCategory. getOperator("LAST_TIME_RUN", StatisticsReference.HIGHEST) will return the XATQueryObject ran most recently (lastTimeRun is highest).

See StatisticsReference for a list of supported identifiers

Parameters:
propertyName - java.lang.String
identifier - int
Returns:
edu.wpi.cs.dsrg.xmldb.xat.common.operator.XATQueryObject

getQueryObject

public XATQueryObject getQueryObject(java.lang.String propertyName,
                                     int valueIdentifier,
                                     boolean updateValue)
Gets the XATQueryObject whose propertyValue corresponds to the propertyName and valueIdentifier in the currentCategory.

For example, getQueryObject("SELECTIVITY", StatisticsReference.LOWEST) will return the XATQueryObject with the lowest selectivity within the currentCategory. getOperator("LAST_TIME_RUN", StatisticsReference.HIGHEST) will return the XATQueryObject ran most recently (lastTimeRun is highest).

See StatisticsReference for a list of supported identifiers

Added 5/26: You can now ask for any position in the list, not just highest, lowest, average, etc. Just pass in the position you want. To retrieve highest, lowest, etc, still make use of the constants in StatisticsReference

Parameters:
propertyName - java.lang.String
identifier - int
updateValue - boolean true if the values should be updated first before the first, last, etc value is retrieved
Returns:
edu.wpi.cs.dsrg.xmldb.xat.common.operator.XATQueryObject

getStatisticsGather

public static StatisticsGatherer getStatisticsGather()
we want there to be only 1 statistics gatherer so a singleton design pattern is used.
Returns:
StatisticsGatherer a handle to the statistics gatherer

getValue

public java.lang.String getValue(java.lang.String propertyName,
                                 XATQueryObject queryObject)
Returns the value for given property of the queryObject in the current category Creation date: (1/15/2003 2:05:37 PM)
Parameters:
propertyName - java.lang.String
queryObject - XATQueryObject
Returns:
java.lang.String

getValue

public java.lang.String getValue(java.lang.String propertyName,
                                 XATQueryObject queryObject,
                                 int description)
Returns the value for given property of the queryObject in the current category If this statistics object does not support this operation, an error will be thrown
Parameters:
propertyName - java.lang.String
queryObject - XATQueryObject
description - the type of value to retrieve. Available constants are found in StatisticsReference
Returns:
java.lang.String

initStatsTable

public void initStatsTable(XATTree initTree)
                    throws XATStatisticsException
Allows you to specify an initial XATTree that contains all of the operators. The ordering (structure) of the operators is irrelevant because the query plan may change later. If the operators themselves change (new operators added) then this statistics gather will have to be updated.

The properties of each operator will be stored inside of a hashtable along with a Comparator so they can be sorted later and organized later.

Parameters:
initialTree - edu.wpi.cs.dsrg.xmldb.xat.common.treestructure.XATTree
Throws:
XATStatisticsException - if the Statistics Gatherer has already been initialized. This prevents the statsTable from being initialized multiple times.

isStatisticSupported

public boolean isStatisticSupported(java.lang.String propertyName)
Checks if the propertyName is in the StatisticsGatherer
Parameters:
propertyName - java.lang.String
Returns:
boolean

removeQueryObject

public void removeQueryObject(XATQueryObject object)
Removes a query object from the statistics gatherer. This will help to reduce the memory footprint of the statistics gatherer by removing unused and unnessary query objects. Of course this could be abused by removing necessary query objects.
Parameters:
object - edu.wpi.cs.dsrg.xmldb.xat.common.operator.XATQueryObject

reset

public void reset()
This will reset the statistics gatherer to its pre-init state. This will remove all categories and all statistics. Care should be given with this method, otherwise it could really mess up execution

setCurrentCategory

public void setCurrentCategory(java.lang.Object newCurrentCategory)
Set the current category. An XATStatisticsException will be thrown if the category does not belong to the stats table
Parameters:
newCurrentCategory - java.lang.Object
Throws:
XATStatisticsException -  

setDefaultProperties

protected void setDefaultProperties()
called by the constructor. this will set the default properties that the ALL query objects will support. Each subclass should override this method and add their own unique properties, but should also call super.setDefaultProperties() so that the common properties may be set.
Overrides:
setDefaultProperties in class XATPropertiesImp

toString

public java.lang.String toString()
Insert the method's description here. Creation date: (1/14/2003 1:17:54 PM)
Overrides:
toString in class java.lang.Object
Returns:
java.lang.String

updateValue

public void updateValue(java.lang.String propertyName,
                        XATQueryObject queryObject)
This will update the given propertyName for the currentCategory. If the currentCategory is something besides "OVERALL", then the OVERALL will be updated as well. The OVERALL will be updated after the other is updated. The value is updated by calling the calculateNewValue method in the corresponding StatisticsObject
Parameters:
propertyName - java.lang.String
queryObject - the XATQueryObject whose property is being updated

updateValue

public void updateValue(java.lang.String propertyName,
                        XATQueryObject queryObject,
                        java.lang.String newPropertyValue)
This will update the given propertyName for the currentCategory. If the currentCategory is something besides "OVERALL", then the OVERALL will be updated as well. The OVERALL will be updated after the other is updated. The value is updated by calling the calculateNewValue method in the corresponding StatisticsObject
Parameters:
propertyName - java.lang.String
queryObject - the XATQueryObject whose property is being updated
newPropertyValue - a string representing the new propertyvalue that will assist the StatisticsObject in calculating its new value