DownloadQuery filters and sorts DownloadItems.

content/browser/download/download_query.h

+// Copyright (c) 2011 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef CONTENT_BROWSER_DOWNLOAD_DOWNLOAD_QUERY_H_
+#define CONTENT_BROWSER_DOWNLOAD_DOWNLOAD_QUERY_H_
+#pragma once
+
+#include <map>
+#include <string>
+#include <vector>
+
+#include "base/callback.h"
+#include "content/browser/download/download_item.h"
+
+// Filter and sort a vector of DownloadItem*s.
+//
+// The following example copies from |all_items| to |results| those
+// DownloadItem*s whose start time is not 0 or whose id is odd, sorts primarily
+// by bytes received ascending and secondarily by url descending, and limits the
+// results to 20 items. Any number of filter fields or sort rules is
+// permissible. If all sort fields compare two DownloadItems equivalently, then
+// they are sorted by their id ascending or db_handle ascending.
+//
+// DownloadQuery query;
+// CHECK(query.Filter(FILTER_FIELD_START_TIME, 0));
+// bool FilterOutOddDownloads(const DownloadItem& item) {
+//   return 0 == (item.GetId() % 2);
+// }
+// CHECK(query.Filter(FILTER_FIELD_FILTER, base::Bind(&FilterOutOddDownloads)));
+// query.Sort(SORT_FIELD_BYTES_RECEIVED, ASCENDING);
+// query.Sort(SORT_FIELD_URL, DESCENDING);
+// query.Limit(20);
+// DownloadVector all_items, results;
+// query.Search(all_items.begin(), all_items.end(), &results);
+class CONTENT_EXPORT DownloadQuery {
+ public:
+  typedef std::vector<DownloadItem*> DownloadVector;
+  typedef base::Callback<bool(const DownloadItem&)> FilterType;

[Randy Smith (Not in Mondays), 2011/11/30 19:26:17]

A comment here or on the Filter() interface that uses FilterType giving a one
line description of how to use this?  Currently all you've got is the example,
and it's easy to miss the part of the example that maps to FilterType.

[benjhayden, 2011/11/30 22:13:49]

Done.

+
+  enum FilterFieldName {
+    FILTER_FIELD_BYTES_RECEIVED,
+    FILTER_FIELD_DANGER_ACCEPTED,
+    FILTER_FIELD_ENDED_AFTER,
+    FILTER_FIELD_ENDED_BEFORE,
+    FILTER_FIELD_END_TIME,
+    FILTER_FIELD_ERROR,
+    FILTER_FIELD_FILENAME,
+    FILTER_FIELD_FILENAME_REGEX,
+    FILTER_FIELD_FILE_SIZE,
+    FILTER_FIELD_FILE_SIZE_GREATER,
+    FILTER_FIELD_FILE_SIZE_LESS,
+    FILTER_FIELD_MIME,
+    FILTER_FIELD_PAUSED,
+    FILTER_FIELD_QUERY,
+    FILTER_FIELD_STARTED_AFTER,
+    FILTER_FIELD_STARTED_BEFORE,
+    FILTER_FIELD_START_TIME,
+    FILTER_FIELD_TOTAL_BYTES,
+    FILTER_FIELD_TOTAL_BYTES_GREATER,
+    FILTER_FIELD_TOTAL_BYTES_LESS,
+    FILTER_FIELD_URL,
+    FILTER_FIELD_URL_REGEX,
+  };
+
+  enum SortFieldName {
+    SORT_FIELD_BYTES_RECEIVED,
+    SORT_FIELD_DANGER,
+    SORT_FIELD_DANGER_ACCEPTED,
+    SORT_FIELD_END_TIME,
+    SORT_FIELD_ERROR,
+    SORT_FIELD_FILENAME,
+    SORT_FIELD_FILE_SIZE,
+    SORT_FIELD_MIME,
+    SORT_FIELD_PAUSED,
+    SORT_FIELD_START_TIME,
+    SORT_FIELD_STATE,
+    SORT_FIELD_TOTAL_BYTES,
+    SORT_FIELD_URL,
+  };
+
+  enum SortFieldDirection {
+    ASCENDING,
+    DESCENDING,
+  };
+
+  DownloadQuery();
+  ~DownloadQuery();
+
+  // Returns false if |name| is unrecognized or if |value| is the wrong type or
+  // malformed. Otherwise, makes a new filter named |name|, sets its value to

[Randy Smith (Not in Mondays), 2011/11/30 19:26:17]

nit, suggestion: "makes" -> "adds"?  

[Randy Smith (Not in Mondays), 2011/11/30 19:26:17]

nit: "filter named |name|" implies that the name is arbitrary, which it's not. 
Maybe "makes a new filter of type |name|"?   (Note that the current wording
implies that you can't have multiple filters of the same name, which I don't
think is true.)

[benjhayden, 2011/11/30 22:13:49]

Done.

[benjhayden, 2011/11/30 22:13:49]

Done.

+  // |value|, and returns true. Search() will filter out all DownloadItem*s that
+  // do not match all filters.  See the implementation for the type of each

[Randy Smith (Not in Mondays), 2011/11/30 19:26:17]

nit: I dislike pointing people at the implementation for details of the
interface, especially when the implementation is complicated and potentially
confusing.  Any reason not to put the types in as comments in the enum above?

[benjhayden, 2011/11/30 22:13:49]

Done.

+  // |name|.
+  bool Filter(FilterFieldName name, int value);
+  bool Filter(FilterFieldName name, bool value);
+  bool Filter(FilterFieldName name, const std::string& value);
+  bool Filter(FilterFieldName name, const string16& value);
+  void Filter(DownloadStateInfo::DangerType danger);
+  void Filter(DownloadItem::DownloadState state);
+  void Filter(const FilterType& value);
+
+  // Makes a new sort field named |name| and sets its direction to |direction|.

[Randy Smith (Not in Mondays), 2011/11/30 19:26:17]

nit, suggestion: "Makes" -> "Adds"?

[benjhayden, 2011/11/30 22:13:49]

Done.

+  // After filtering DownloadItem*s, Search() will sort the results primarily by
+  // the sort field from the first call to Sort(), secondarily by the sort field
+  // from the second call to Sort(), and so on. For example, if the
+  // InputIterator passed to Search() yields four DownloadItems {id:0, error:0,
+  // start_time:0}, {id:1, error:0, start_time:1}, {id:2, error:1,
+  // start_time:0}, {id:3, error:1, start_time:1}, and Sort is called twice,
+  // once with (SORT_FIELD_ERROR, ASCENDING) then with (SORT_FIELD_START_TIME,
+  // DESCENDING), then Search() will return items ordered 1,0,3,2.
+  void Sort(SortFieldName name, SortFieldDirection direction);
+
+  // Limit the size of search results to |limit|.
+  void Limit(size_t limit) { limit_ = limit; }
+
+  // Filters DownloadItem*s from |iter| to |last| into |results|, sorts
+  // |results|, and limits the size of |results|. |results| must be non-NULL.
+  template <typename InputIterator>
+  void Search(InputIterator iter, const InputIterator last,
+              DownloadVector* results) const;
+
+  // Returns true if |item| matches all set filter fields; returns false if any
+  // filter fields have been set that the item does not match.
+  bool Matches(const DownloadItem& item) const;
+
+ private:
+  struct SortField;
+  class DownloadComparator;
+  typedef std::vector<FilterType> FilterFieldVector;
+  typedef std::vector<SortField> SortFieldVector;
+
+  FilterFieldVector filter_fields_;
+  SortFieldVector sort_fields_;
+  size_t limit_;
+
+  DISALLOW_COPY_AND_ASSIGN(DownloadQuery);
+};
+
+#endif  // CONTENT_BROWSER_DOWNLOAD_DOWNLOAD_QUERY_H_