mozIStorageAggregateFunction 编辑

This is an interface that must be implemented by consumers.  It allows consumers to add  aggregate functions that are available to SQL queries and triggers.  An aggregate function is a function that returns one value from a series of values.  There are a number of already defined aggregate functions provided by SQLite.  Objects implementing this interface can be registered with mozIStorageConnection.createAggregateFunction().

Inherits from: nsISupports

Method overview

Methods

onStep()

This is called for each row of results returned by the query.  The implementation should store or perform some work to prepare to return a value.

Note This callback is executed on the thread that the statement or trigger is executing on. If you use mozIStorageConnection.executeAsync() or, mozIStorageStatement.executeAsync() this callback will run on a different thread from the rest of your code. Likewise, if you execute SQL on a different thread, this callback will be executed on that thread. This callback should be reentrant if any of the above applies to your use of the storage APIs!

void onStep(
  in mozIStorageValueArray aFunctionArguments
);

Parameters

aFunctionArguments

A mozIStorageValueArray holding the arguments passed in to the function.

onFinal()

This is called after all results have been obtained and notified via mozIStorageAggregateFunction.  The implementation should finish its calculations on the data, and return a result.

Note This callback is executed on the thread that the statement or trigger is executing on. If you use mozIStorageConnection.executeAsync() or, mozIStorageStatement.executeAsync() this callback will run on a different thread from the rest of your code. Likewise, if you execute SQL on a different thread, this callback will be executed on that thread. This callback should be reentrant if any of the above applies to your use of the storage APIs!

nsIVariant onFinal()

Return value

An nsIVariant this is the return value of the function.

Sample Code

Both of the following code samples assume that the variable dbConn is an opened mozIStorageConnection.

JavaScript

// First, create our object that will represent our function.
var standardDeviationFunc = {
  _numbers: [],
  onStep: function(aArguments) {
    this._numbers.push(aArguments.getInt32(0));
  },
  onFinal: function() {
    let total = 0;
    let iLength = this._numbers.length;
    this._numbers.forEach(function(elt) { total += elt });
    let mean = total / this._numbers.length;
    let data = this._numbers.map(function(elt) {
      let value = elt - mean;
      return value * value;
    });
    total = 0;
    data.forEach(function(elt) { total += elt });
    this._numbers = [];
    return Math.sqrt(total / iLength);
  }
};

// Now, register our function with the database connection.
dbConn.createAggregateFunction("stdDev", 1, standardDeviationFunc);

// Run some query that uses the function.
let stmt = dbConn.createStatement("SELECT stdDev(value) FROM some_table");
try {
  while (stmt.executeStep()) {
    // handle the results
  }
}
finally {
  stmt.reset();
}

C++

// First, create our class that will represent our function.
class standardDeviationFunc : public mozIStorageAggregateFunction
{
public:
  NS_IMETHOD OnStep(mozIStorageValueArray *aArguments)
  {
    PRInt32 value;
    nsresult rv = aArguments->GetInt32(&value);
    NS_ENSURE_SUCCESS(rv, rv);

    mNumbers.AppendElement(value);
  }

  NS_IMETHOD OnFinal(nsIVariant **_result)
  {
    PRInt64 total = 0;
    for (PRUint32 i = 0; i < mNumbers.Length(); i++)
      total += mNumbers[i];
    PRInt32 mean = total / mNumbers.Length();

    nsTArray<PRInt64> data(mNumbers);
    for (PRUint32 i = 0; i < data.Length(); i++) {
      PRInt32 value = data[i] - mean;
      data[i] = value * value;
    }

    total = 0;
    for (PRUint32 i = 0; i < data.Length(); i++)
      total += data[i];

    nsCOMPtr<nsIWritableVariant> result =
      do_CreateInstance("@mozilla.org/variant;1");
    NS_ENSURE_TRUE(result, NS_ERROR_OUT_OF_MEMORY);

    rv = result->SetAsDouble(sqrt(double(total) / double(data.Length())));
    NS_ENSURE_SUCCESS(rv, rv);

    NS_ADDREF(*_result = result);
    return NS_OK;
  }
private:
  nsTArray<PRInt32> mNumbers;
};

// Now, register our function with the database connection.
nsCOMPtr<mozIStorageFunction> func = new standardDeviationFunc();
NS_ENSURE_TRUE(func, NS_ERROR_OUT_OF_MEMORY);
nsresult rv = dbConn->CreateFunction(
  NS_LITERAL_CSTRING("stdDev"),
  1,
  func
);
NS_ENSURE_SUCCESS(rv, rv);

// Run some query that uses the function.
nsCOMPtr<mozIStorageStatement> stmt;
rv = dbConn->CreateStatement(NS_LITERAL_CSTRING(
  "SELECT stdDev(value) FROM some_table"),
  getter_AddRefs(stmt)
);
NS_ENSURE_SUCCESS(rv, rv);
PRBool hasMore;
while (NS_SUCCEEDED(stmt->ExecuteStep(&hasMore)) && hasMore) {
  // handle the results
}