Add a Model to the download component.

components/download/internal/model.h

+// Copyright 2017 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 COMPONENTS_DOWNLOAD_INTERNAL_MODEL_H_
+#define COMPONENTS_DOWNLOAD_INTERNAL_MODEL_H_
+
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "components/download/public/clients.h"
+
+namespace download {
+
+struct Entry;
+class Store;
+
+// The model that contains a runtime representation of Entry entries. Any
+// updates to the model will be persisted to a backing |Store| as necessary.
+class Model {
+ public:
+  // The Client which is responsible for handling all relevant messages from the
+  // model.
+  class Client {
+   public:
+    virtual ~Client() = default;
+
+    // Called asynchronously in response to a Model::Initialize call.  If
+    // |success| is |false|, initialization of the Model and/or the underlying
+    // Store failed.  Initialization of the Model is complete after this
+    // callback.  If |success| is true it can be accessed now.
+    virtual void OnInitialized(bool success) = 0;
+
+    // Called asynchronously in response to a Model::Destroy call.  If |success|
+    // is |false|, destruction of the Model and/or the underlying Store failed.
+    // Destruction of the Model is effectively complete after this callback.
+    virtual void OnDestroyed(bool success) = 0;
+
+    // Called when an update or remove operation failed for |guid|.  At this
+    // point there is no guarantee that the underlying Store and this Model are
+    // in sync.
+    virtual void OnStoreUpdateFailed(DownloadClient client,
+                                     const std::string& guid) = 0;
+
+    // Called when an Entry addition is complete.  |success| determines whether
+    // or not the entry has been successfully persisted to the Store.
+    virtual void OnItemAdded(bool success,
+                             DownloadClient client,
+                             const std::string& guid) = 0;
+  };
+
+  using EntryList = std::vector<Entry*>;
+
+  virtual ~Model() = default;
+
+  // Initializes the Model.  Client::OnInitialized() will be called in response.
+  // The Model can be used after that call.
+  virtual void Initialize() = 0;
+
+  // Destroys the Model.  Client::OnDestroyed() will be called in response.
+  virtual void Destroy() = 0;
+
+  // Adds |entry| to this Model and attempts to write |entry| to the Store.
+  // Client::OnItemAdded() will be called in response.
+  virtual void Add(const Entry& entry) = 0;
+
+  // Updates |entry| in this Model and attempts to write |entry| to the Store.
+  // Will call Client::OnStoreUpdateFailed() if the write fails.

[Peter Beverloo, 2017/05/10 12:44:45]

There's cases when a client might want to wait for the update to finish. A
cleaner transactional design would be to create an OnItemUpdated analogous to
OnItemAdded, having the same arguments, allowing both success and failure to be
acknowledged.

This also goes for a theoretical OnItemRemoved. You have a much better
understanding here -- how'd you answer the "what do I do" question when
OnStoreUpdateFailed, or either of the OnItem{Updated,Removed} methods, gets
called with `false`?

[David Trainor- moved to gerrit, 2017/05/15 15:59:51]

Yeah I went back and forth on exposing those concepts for a while... there were
some cases where it ended up causing potential pain and complexity if you have
observers pushing new data to the model while we're notifying them.  Then
pushing two updates at once would cause some headaches as well.

I think your idea of only sending the DownloadClient and guid (and not the
old/new Entry state) might simplify things a bit.  And now that we only have one
Client for the Model we avoid a lot of the complexity.  Will add.

+  virtual void Update(const Entry& entry) = 0;
+
+  // Removes the Entry specified by |guid| from this Model and attempts to
+  // remove that entry from the Store.  Will call Client::OnStoreUpdateFailed()
+  // if the removal fails.
+  virtual void Remove(const std::string& guid) = 0;
+
+  // Retrieves an Entry identified by |guid| or |nullptr| if no entry exists.
+  virtual Entry* Get(const std::string& guid) = 0;
+
+  // Returns a temporary list of Entry objects that this Model stores.  Note
+  // that the Entry* list entries may not be valid if any modifications to this
+  // Store are made while holding on to the returned list!
+  virtual EntryList PeekEntries() = 0;

[Peter Beverloo, 2017/05/10 12:44:45]

Here and for Get() - document that the Entry*(s) should be used immediately
(i.e. a stronger warning). Since the Entries are owned by the model, any sort of
caching could result in UAF.

[David Trainor- moved to gerrit, 2017/05/15 15:59:51]

Done.

+};
+
+}  // namespace download
+
+#endif  // COMPONENTS_DOWNLOAD_INTERNAL_MODEL_H_