C H A P T E R  6

Windows Phone 7: Persisting Bookmarks Locally

As I've mentioned several times now, as of the time of writing, there is no relational database available for third-party apps on Windows Phone 7. There is, in fact, an implementation of the SQL CE database on the devices, but this is locked down so that it is available only to Microsoft applications, notably the Office Hub applications available on the device. One can only assume that SQL CE will become available again given time. This would be a definite good thing—Microsoft has a proven track record in building synchronization frameworks that work between its full-on SQL Server database and devices. It would be nice to have this back again on its mobile devices. Over time we'll probably see close integration with its Azure cloud services.

All this means that this chapter is a bit of an oddball because it's the only one in the book in which we're not using a database at all, let alone SQLite, which features prominently on the other platforms.

Approach

The approach we're going to take in this chapter is to store individual entities in individual files within a folder in isolated storage. We'll be reproducing the same entity-based scheme, including the metadata subsystem. We'll also have a SqlFilter class, although, unlike the name implies, this won't work with SQL statements. My rationale for doing this is that we want to aim for consistency across the different code bases wherever possible.

Entities

In Chapter 3, we looked at the structure of the entity model and its associated metadata subsystem, and we built an implementation on Android and iOS. In this section, we'll repeat this work in C# for Windows Phone 7. This code will more or less work unchanged on Windows Mobile, and also in the Mono implementations on Android and iOS. More importantly, it will also work if you do move over to a proper relational database.

The EntityType Class

The purpose of the EntityType class is to bundle together all of the information that you need in order to build code that can “magically” manipulate the underlying store and user interface depending on the structure of the data. In our case, instances of EntityType classes are going to group fields together, plus static memory on EntityType itself will hold a list of entity types. (But in this example we're going to have only one entity type.)

Each entity type will have two names—a programmatic name and a native name. Having separate values for the names makes it possible to smooth out other problems with the underlying store. For example, you may have a database table called TBL_CUST that you would like to refer to as Customer in code. In this case, TBL_CUST would be the native name, and Customer would be the programmatic name.

To this end, we'll create a class called EntityItem that will act as a base class for things that we want to store using the metadata system. Here's the code:

We'll look at the fields first. Each field will store the following information:

• A native name and programmatic name
• A data type
• A size
• In this chapter, we're going to have only one, which indicates whether the field is a key field. In a full-on implementation, another example of a flag would be indicating whether the field could be nullable.

In this example, we're going to support just two data types; in a more full-on implementation, we'd obviously need to support all of the data types that the underlying database supports. (If we implement all of them now, half the book will be taken up with methods exposing out all of the data types.) Our server-side service used only strings and 32-bit integers, so we will need these, plus a Boolean type that we'll use on fields that are held locally and not on the server. Here's the SBDataType enumeration that we need to support those three types:

Now that we have the enumeration, we can build EntityField. As well as supporting native name, name, data type, size, and an indication as to whether the field is a key, we'll have another property holding the ordinal of the field within the type. Here's the code:

One other thing we need EntityField to be able to do is return a default value for the given type. We need this in order to support the insert operation. We'll talk more about this at that time—for now, here's the DefaultValue property:

So that we can effectively work with entities, we need EntityType to be able to instantiate instances of individual entities and collections of entities. In this example, we're going to have only one entity—Bookmark. In any real-world application, you're likely to have many entitity types. This will be done by holding references to the relevant .NET types. Our motivation for doing this is so that we can say to framework code “give me a list of bookmarks” and the framework code itself will be able to create an appropriate collection type and individual entities. (Of all the platforms that we've seen in this book, the reflection subsystem in .NET is far and away the best.)

In addition, we're going to add a method to EntityType called AddField. This will be used to programmatically define the fields available on an entity type. Here's the code:

An important part of the code there is that when we add a field using the AddField method, we need to assign each field a unique ordinal. By passing in the length of the array as the ordinal, we effectively do that.

Next we can look some of the other methods on EntityType. We're going to need to be able to find a field with a specific name, find the key field, or determine whether a field with a specified name actually exists. (This latter one is used for populating entities from data received over XML where the XML may reference fields that we don't know about.) Here are the three methods that also need to be added to EntityType:

Recall that the other function EntityType needs is the ability to hold a register of the available entity types. We'll do this by creating a static hashtable on EntityType and methods called RegisterEntityType and GetEntityType.

We can now use this class to create and store entity types. Let's look now at building the Entity base class.

The Entity Class

The basic functionality of an entity is to store a dynamic list of data that represents the columns in the underlying database table. An entity will be created either manually by the developer or by framework code that retrieves the data from some source. (In our application, the source of data is going to be either the local files on disk or the Bookmarks data service at http://services.multimobiledevelopment.com/.) At some point during the entity's life, the data stored within will either be read for display on a screen, or be used to issue some sort of change request to the underlying store.

In our entity, we are going to hold three sets of values. Firstly we're going to store a reference to our related EntityType instance. Secondly we're going to store an array of values that map 1:1 with the data in the underlying store. Thirdly and finally, we're going to store a bunch of flags that help the entity keep track of its internal state.

Storage of data within the entity will be done in “slots.” You will notice on our EntityField instance we have a property called Ordinal. This ordinal value is the index of the slot in the entity. Thus if we have five fields, we'll have five slots numbered from zero to four inclusive.

To manage the lifetimes of values stored within the new Entity class, we need to create an enumeration that indicates the status of the slots. We'll call this enumeration EntityFieldFlags, and it needs to be defined prior to building Entity. Here's the listing:

Next we'll look at the definition for the basic “storage” capability of Entity. The first thing we do is capture the entity type in the constructor. We'll need this later to allow all of the methods on the base class to reflect against the metadata. The second thing that we do is create two arrays—one to hold the values of the slots, the other to hold the flags. Here's the code:

We'll now look at making our entity do something interesting.

Setting Values in an Entity

Whenever we set a value within an entity, we'll be doing one of two things—we'll be plugging in either a value that the user has provided through some form of input, or a value that we have retrieved from a database or service. It's important that we can distinguish between these two operations—if the user has changed something, we may need to update the underlying store with that value. Conversely, if the user has not changed something, we do not want to be issuing unnecessary update requests back to the underlying store.

To keep track of which operation we intend when we set a value, we'll create an enumeration called SetReason. Here's the code:

As we add methods to the entity, we'll find that oftentimes we need to add overloads for each of the methods that take either the name of a field as a string or an actual instance of an EntityField class. This is going to create additional code, but there is a substantially higher level of utility in not requiring the caller to dig out an EntityField instance every time the caller wishes to access field data. Whenever one of the string-based “name” overloads is used, we'll defer to the EntityType for the field name. Here's a collection of methods that allow values to be set:

The function of SetValue is twofold. Firstly, it sets the value in the Values array to be the value passed in. Secondly, it sets the value in the Flags to indicate the state of the field. Regardless of the value of the reason parameter, it will indicate that the field has been loaded. If the value of reason indicates that the user changed a value, the field is marked as having been modified.

Retrieving the values is—oddly—a little trickier. In the first instance, we need to be able to behave differently depending on the state of the data. For example, if we're trying to retrieve the value for a field and we have not loaded it, we need to throw an error indicating that the value is not available. (Some implementations, including BootFX, will demand load data in this situation. However, for simplicity, we're not doing this here.)

Before we do that, we'll add a few methods that will help us understand whether fields have been loaded or modified, or whether the entity as a whole is new. We'll need these later on. Here's the implementation:

Those methods lay the groundwork for the GetValue method that we implied must exist when we created our SetValue earlier. One implementation point is that we have to add a rule whereby if we're not new and we don't have it, we have to throw an error as we can't demand-load the value. This is called “demand-loading.” It's common enough in ORM tools, but to keep things simple, I have chosen not to implement it here. (Plus, seeing as we're not using a database at the moment on WP7, there's no mileage in not loading the whole entity in memory.)

We've touched a few times on this idea that we have deliberately limited data type support in this application to keep the code simple. We're about to see an example—there's quite a lot of code here to support just the few data types that we do support.  Here's the code:

Now that we can get data into and out of our base entity, let's look at creating a strongly typed Bookmark class.

Building Bookmark

The point of ORM is that you're looking to get the entity layer to do most of the hard work of managing the data for you—i.e., it's easier to call a property called Name and know you're getting a string value back than it is to request an item with the name “name” out of a bucket of values returned over a SQL interface. Thus we need to add a bunch of properties to Bookmark that abstract calls to GetValue and SetValue.

Before we do that, though, there's one thing to consider. As discussed in Chapter 2, the database stores against each bookmark an internal ID, the user ID, the name, the URL, and ordinal values. In our database, in order to support the synchronization functionality that we'll build in the next chapter, we also need to store flags to indicate whether the item has been modified or deleted locally. We'll add IsLocalModified and IsLocalDeleted to achieve this.

Here's the definition of Bookmark:

As well as the singleton entity, we'll create a strongly typed collection. (I'm always a fan of building strongly typed collections when building entities, as it makes building a strong API on your business tier easier.) Here's the code:

When we built our EntityType class previously, we missed a couple of methods—specifically ones that would dynamically create singleton entity instances and collections. Here's the code to add to EntityType:

Creating SBEntityType Instances

Before we can create instances of Bookmark and use them, we need to be able to create an instance of EntityType that supports it. In more sophisticated ORM layers, it's commonplace to build the metadata up from some sort of decoration in the code (this is very easy to do using attributes in .NET). In this implementation, we're going to add code to the SixBookmarksRuntime that we built in the last chapter and have it register the entity type on start. Here's the code to the constructor of SixBookmarksRuntime:

We're essentially done here—we can now move on to creating some fake bookmarks and showing them on the device.

Displaying Some Fake Bookmarks

To keep us going until we have real data on the device, we'll display some fake bookmarks on the screen. To do this, we'll need a form that in previous incarnations of the application we have called the “navigator.”

To the project, add a new Windows Phone Portrait Page called NavigatorPage.xaml. We'll add nine buttons to the form, one for each of the six buttons and one for each of the three options—configure, logoff, and about. These can be dragged and dropped onto the design surface in the usual way. For each of the buttons, change the Content value as per Figure 6-1, and set the Name properties to be buttonNavigate1, buttonNavigate2, etc., buttonConfigure, buttonLogoff, and buttonAbout.

Figure 6-1. The design surface for the Navigation page

Here's the XAML that creates this view:

This gets as far as having a view that we can actually show. What we need to do now is create our set of fake bookmarks and update the view.

Creating Fake Bookmarks

Creating the fake bookmarks is very straightforward—we just need to create instances of the Bookmark class that we built earlier and populate the properties accordingly.

To add a little finesse, we'll add a static method to Bookmark called GetBookmarksForDisplay. This will make more sense in the next chapter, but for now what we're looking to do is provide a mechanism whereby we can “soft-delete” bookmarks from the local data store by marking them as deleted. The real implementation of GetBookmarksForDisplay will return a list of bookmarks that are not soft-deleted. For now, here's the implementation that returns the fakes:

Showing and Populating the View

To use the bookmarks, we need to firstly modify the logon form so that it launches the navigator form, and we also need to implement a page load handler on the navigator form so that it displays the buttons. We do the logon form changes first.

As I alluded to earlier, Silverlight uses an approach of exposing out a class that provides navigation services to the application as a whole, which in this context means providing access to different views. These are done via URIs. In order to move from the logon form to the navigator form, we need to construct a URI for the navigator form and ask the Silverlight navigation service to show it. This is actually pretty straightforward—as the forms are in the root of the project, we create a URI relative to the root of the application that specifies the name of the .xaml file that drives the form. Here's the code that shows the change to the LogonOk method in the LogonPage class:

Those are all the changes that we need to make to the logon form.

Going back to the navigator form, in the designer, double-click the white background of the design surface. This will add a Loaded event handler, like this one:

The approach we'll take on this form is that we'll create a property called Bookmarks that will hold a List<Bookmark>. When this property is set, we will refresh the view. This will involve going through each of the six buttons and resetting them to a “not set” state, which in our case will mean returning them to having an ellipsis (“…”) for their text. For each bookmark that we do have, we'll find the appropriate button and set the text to be the name. Here's the code to be added to NavigatorPage.

You can now run the code and log on. Figure 6-2 shows you what to expect.

Figure 6-2. The Navigation form running and displaying fake bookmarks

Implementing Button Clicks

Those of you familiar with .NET and a particular product in its ancestry called Visual Basic will know that when you double-click a button on a design surface, it will give you a handler method for that button. This is the case with the toolset we're using now. However, we want to create just a single handler method for the navigation buttons. One way to do this is to change the XAML for all six buttons with the name of the handler that we want and double-click one of the buttons to create an appropriate handler in code.

The XAML is changed by adding a Click attribute. This snippet of the XAML from the designer shows the method reference in place:

If you double-click one of these buttons, you will get a method handler stub. Here's the listing for the stub. This code goes back into the Bookmarks property and extracts the bookmark with the matching ordinal. (Again the code to de-reference the button could be slicker—I'm biased toward ease of reading.)

You'll notice that the way we open a web resource is to defer to a to-be-built method on SixBookmarksRuntime called ShowUrl. Here's what this method this looks like:

This method, as you can see, uses the WebBrowserTask class. The operation of this class is to open the instance of Internet Explorer installed on the phone.

If you run the application and click one of the links, IE will launch and show the page. Figure 6-3 illustrates.

Figure 6-3. Internet Explorer showing a web page that we have navigated to

Tombstoning—A Brief Word

At this point, it's worth introducing the idea of “tombstoning.” Windows Phone 7 has a feature whereby rather than having proper multitasking, when you switch to a new application (as we have done by opening the web browser), your application is dumped out of memory. Should you click the phone's back button, your application will be brought back to life. The only wrinkle with this is that you are the one responsible for saving and restoring your application's global state when this happens. Windows Phone 7 is unique in this regard—none of the other phones works in this way.

I personally think this is a neat idea—it keeps memory usage and processor cycles on the device down to a minimum. What I don't think is neat is that you have to manage this yourself (i.e., you have to open a file of some kind and dump your static data into it)! You would think that in the OS design they would have built in a mechanism for serializing the application state down to the disk itself.

But I digress—for now, we're not going to look at tombstoning, but we will come back to it toward the end of the chapter. We're going to use the ORM subsystem to store data, and we can't do that until we've been through getting the ORM system working.

Storing Entities in the Data Box

As you know by now, as of the time of writing, a database management system is not available for Windows Phone 7, and, as such, we need to store our entities on disk. In the rest of this chapter, we'll examine how to do this by storing entities into what I'm going to call a “data box.” (This isn't a fabulous name, but it will do!)

We've already seen in the last chapter how we can use .NET's isolated storage feature to store files on disk. We'll use this feature again as part of our data box.

The design that we're going to aim for is one whereby we will create exactly one XML file per entity and we'll use the ID of the entity as the file name. When we create a data box, we'll give it an entity type, and it will use this entity type as part of the name of the folder. So, if we want to store a bookmark with ID 27, it would have a path like this:

One complication with this arrangement is that we cannot rely on the store to manage the IDs for us. (With SQLite, or any relational DBMS we have an “autonumbering” scheme that manages the IDs of values as we put them into the store.)

Finally, as mentioned before, we'll build the SQL filter and change processor implementations as we have done on the other implementations with a proper SQL database.

Data Box Basics

The basics of a data box are a class with a property that holds a reference to an entity type and another that holds a reference to a folder. As mentioned before, we'll be using isolated storage for this. I'm also proposing creating a folder underneath a root Entities folder—this is analogous to a table. In our case, it makes it easier to get all the entities of a given type in a single hit. Here's the code:

The first things we'll look at are methods to insert and update entities. These are actually the same operation—if we're doing an insert, we do not have a file to insert into, and if we're doing an update, we have an existing file that we wish to overwrite.

In both cases, we need to be able to transform the ID of an entity of a known type into a full file path within isolated storage. This is one example where the metadata system pays dividends. We can ask the entity type to return the key value for a given entity. We can then use this in the file name. Here's a method called GetFilePath that, when given an entity, de-references the ID and transforms it into a file name:

This means that we can now take a bookmark entity with an ID of, say, 27 and turn it into a file path, such as ~/Entities/Bookmark/27.xml.

If we need to insert an entity, we need to obtain the next ID in the set. As alluded to earlier, if we were using a proper relational database management system (RDBMS) to do this, we could ask it to retrieve an ID from its internal table. We don't have as much luck—what we need to do is ask isolated storage to return a list of file names to us. We can then walk these file names and look for the largest ID. The result of GetNextId would be this largest ID value plus one. Here's the code:

As a thought on this method, this is fine if you don't mind potentially repeating IDs. For example, if you had bookmark 27 and asked for the next ID, you would get 28. If you created 28.xml and deleted it, if you called GetNextId again, the largest ID would be 27, and hence you be given 28 again. This almost certainly works OK for our method here, but this behavior does not mimic that of a regular database, which, without explicit instruction, will not return the same ID twice.

As just mentioned, Insert and Update are pretty similar. Insert will retrieve an ID value and set that ID value into the entity before deferring to Update. (This process ensures not only that the ID is written to the internals of the file, but also that Entity.IsNew will return false after SaveChanges is called.) The Update method will obtain a file path and then save the entity via SaveEntity. (We'll build SaveEntity shortly.)

There is one special thing that Insert has to do that Update does not. When we write an entity to disk for the first time, we need to make sure that all of the fields are populated. If we don't do this, if we later rely on a field being there (for example, we want to select out entities by constraining on the field's values), we'll get an error. Therefore, after we have set the ID, we loop through all of the fields and find any not marked as modified. If we find any that are not modified, we set the value of the field to be the default value for that field type. (Recall that when we built EntityField field, we added the DefaultValue property.)

Here's the code:

The operation of SaveEntity will be to call a method called EntityToXml, which will return back to us an XDocument instance. After we have the XML, we save it by asking isolated storage to give us a file stream. The operation of EntityToXml is straightforward—it uses the metadata on the entity type to enumerate the fields and simply dumps the entity's current value for that field to the XML document. Here's the code:

For completeness, we'll also build the Delete method. Here's the code:

Creating the Entity Change Processor

In this section, we're going to build the change processor. However, the approach I'm going to propose is to build it so that we can swap out the data box implementation for a proper RDBMS implementation at a future point. To do this, we'll build a strategy class that knows how to work with data boxes and a base class that is strategy-agnostic. When the time comes, we can create a new strategy class for the database.

Here's the implementation for the base class. All it needs to do is look at the state of the entity and decide whether to insert, update, delete, or take no action.

You may notice that on the EntityChangeProcessor class we have Insert, Update, and Delete methods. What we'll do is implement a DataBoxEntityChangeProcessor class that defers to an instance of a DataBox. Here's the implementation:

All that remains now is to add a SaveChanges method to Entity. We'll hard-code the DataBoxEntityChangeProcessor instantiation in here. In a more sophisticated implementation, we would look at this being a factory method of some sort, but for our purposes here, this is fine. Here's the code:

Now that we can write entities onto disk, we'll look at building our Sync class. In this chapter, we'll implement this so that it will download bookmarks from the OData service. In the next chapter, we'll modify this implementation so that we can transmit changes back.

Building the Sync Class

The Sync class will be the provider of the functionality to our application that downloads bookmarks from the server and pushes changes back again. We'll call it when we log on, and we'll also call it in the next chapter in response to the user actually changing bookmarks.

If you've followed along during the Android and iOS implementations, you'll know that we had to handcrank the code to talk to the OData service. Ideally, back in the Microsoft “we'll give you a wizard to do everything” world, we should not have to do this. However, it transpires that there is no support for the kind of OData operation that we wish to build on Windows Phone 7.

Interesting story—when the first draft of this chapter was written against the CTP bits for Windows Phone 7, this support was there! However, by the time it went to release, support was dropped. There is some support available through open source efforts, but the major initiative in this space approaches the problem in a way that's not directly compatible with the other platforms. Therefore, in this chapter and the next, we're going to roll our own OData support, just as we have done for the other chapters.

Let's get started and build a class called Sync that we'll use whenever we need to upload changes to the server or download the definitive set of bookmarks from the server. (In this chapter, we're not going to upload changes—that'll happen in the next chapter.)

As you know from the last chapter, when we communicate with the server, we do so asynchronously. While this adds extra difficulty to building the application, it's worth doing so because the effect is much nicer for the user. (Plus on Windows Phone you do not have a non-asynchronous—i.e., synchronous—option.)

Each of the calls that we build will use the pattern we saw last time of providing one callback delegate for the successful path and another callback delegate for the error path. Moreover we'll reuse the Failed delegate that we introduced last time.

Let's look now at consuming the OData service. First of all, here's the code for ODataServiceProxy. We'll add more to this later.

On our BookmarksService class, we need to add a method called GetAll. The method ultimately needs to call up to the server and retrieve a set of bookmarks. This is done by building and issuing a query to the server.

As you know from our work on the basic REST services, all HTTP requests happen asynchronously, and hence, when we call the GetAll method, we will pass in a success callback and a failure callback. We'll make the success delegate accept a list of bookmarks by way of a return value. In order to pass these callbacks through to the delegate that gets called when the query has executed, we'll create a private class in BookmarksService called ODataFetchState that holds the state that we need, and has some methods on it to help interpret and package the results. (This class in a real-world implementation would be internal rather than private, but this would mean making it more generic, and this seems overkill for this example.) Here's the basic implementation of BookmarksService:

Let's look at how to build the ODataFetchState class first. This class will be a generic class and will accept a type related to an entity that we support (the Bookmark instance in this case). As part of its state, we need to track a callback to call when we have data (which will be passed into the GetAll method), and a callback if there's a failure (again, passed into the GetAll method).

The GetAll method itself will run asynchronously and will retrieve XML from the server. This will be passed into a method called ReceiveXml on the state class. Here's the implementation of GetAll first:

And here's the stub implementation of the state class and its ReceiveXml method:

You can see there that ReceiveXml actually defers to a method called LoadEntities, and it's this LoadEntities call that actually does the work. This will reel through the XML from the server, creating entities as it goes.

By way of a reminder, here's what the XML from the server typically looks like (I've included only one bookmark here for brevity, but a larger snippet is shown in Chapter 2).

Thus, to read in a bookmark, all we have to do is find the entry elements and then walk the properties contained within the m:properties element. Here's the code that does that:

During the read process, LoadEntities calls a helper method called GetValue. This latter method's job is to interpret the data type and return strongly typed values back to the caller, ready to store within the entity. We're going to support only two data types here—a real-world implementation would contain more first-class support for different types.

            private Object GetValue(XElement field)
            {
                // fields are provided with a data element, like this....
                // <d:BookmarkId m:type="Edm.Int32">1002</d:BookmarkId>

                // look up the type name...
                string typeName = null;
                XAttribute attr = field.Attribute(XName.Get("type", MsMetadataNamespace));
                if (attr != null)
                    typeName = attr.Value;

                // nothing?
                if (string.IsNullOrEmpty(typeName))
                    return XmlHelper.GetStringValue(field);
                else if (string.Compare(typeName, "Edm.Int32", StringComparison.InvariantCultureIgnoreCase) == 0)
                    return XmlHelper.GetInt32Value(field);
                else
                    throw new Exception(string.Format("Cannot handle '%s'.", typeName));
            }


Calling GetAll

The operations of the Sync class have to run asynchronously, as we've already stated that all server communication has to be done in this way. As a result, the DoSync method on the Sync class will also need to accept a success callback and a failed callback. As we'll need to use these from various places in the code, we'll store these callbacks as properties on the Sync class.

Internal to the Sync class will be a GetLatest method. The operation of this method will be to call the GetAll method and wait until some bookmarks are returned. The bookmarks that are returned will be ready for committal to disk via a change to SaveChanges. In addition to this, we also need to delete the existing bookmarks from disk; however, we cannot do this part yet as we have not built the code that retrieves the bookmarks back. (We'll do this shortly.)

As a result, the Sync method is actually pretty simple. Here's the code:

If you recall, when we built the logon form, we added a method called LogonOk, and also added a comment indicating where the code to the synchronization code would go. We can now add this in—on success what we want to do is navigate over to the navigator form using the Silverlight NavigationService.

There's one wrinkle that we have to deal with, however. When our success callback is invoked, we'll be running on a worker thread and not on the main user interface thread. As a result, we have to use the Silverlight Dispatcher class to marshal control back to the main thread before using the NavigationService.

Here's the modified implementation of LogonOk:

Now you can run the application, and the sync code will complete. However, you won't be able to see anything different, as all we're doing is writing files to disk and there's no way of browsing those files on the device. In the next section, we'll look at reading the files back out.

Selecting Entities

In this section, we're going to create a class called DataBoxFilter that can be used to read entities from disk.

If you've been reading along the Android and iOS implementations, you'll know that we built a class called SqlFilter that was able to select data out of a table in a relational store. This class worked by assuming that when you created a filter you wanted all entities of a given type. You could then add constraints to limit the entities that were returned.

In DataBoxFilter, we're going to do much the same thing. This class will be bound to a data box and initially be configured to return back a list of all entities of a given type. We can add constraints to limit the results returned. (Because we are trying to move to a world where we have a relational store, I'm 120going to call the constraint class SqlConstraint, as ultimately we'd like to do away with DataBoxFilter and use SqlFilter instances instead.) In terms of how we're going to do the filtering, we'll always load all entities from disk and walk them one by one to see if they are included based on the constraints. This is the easiest way to achieve what we want, but it is the least efficient. Given that we need to keep this code easy to read in order to make the book more comprehendable, and given that our dataset is small, this approach is suitable in this case. If you were looking to work with a larger set of data, you'd need to be more sophisticated with your approach.

The first method we'll need is one that returns all of the entities out of the data box. We'll implement this on DataBox itself and use it from within DataBoxFilter. This method will need to be able to create a strongly typed, generic collection of entities for a given entity type, and therefore we'll add a method called CreateCollectionInstance to EntityType. This method uses some semi-advanced .NET magic to create an appropriate collection type at runtime—suffice it to say that if we call this method on the entity type that represents Bookmark, we'll get a List<Bookmark> returned. Here's the code:

We can now implement our GetAll method on DataBox. The operation of this method will be to ask isolated storage for a list of file names. These file names will then be turned into full paths (e.g., 27.xml → ~/Entities/Bookmark/27.xml) and passed to a method called EntityFromXml for rehydration back into an instance. Here's the implementation of the basic GetAll method:

The EntityFromXml method is intended to be able to be able to hydrate any form of entity (i.e., it's not Bookmark-specific). Its operation is to use the field definition within the entity type to identify elements contained within the document. If there is a match between a field and an element, the field's value is set and marked as loaded. If there is no match, no error occurs. Here's the code:

Now that we can load the entities, we can turn our attention to creating a filter. The first class we need to support our filter is SqlConstraint. This class exists simply as a pair of properties—specifically an EntityField instance and the value be constrained. (In more sophisticated implementations, this may include an operator, such as “not equal to” or “greater than.” Our implementation will support only “equal to.”)

Here's the code:

For our actual DataBoxFilter, we'll hold a DataBox instance and set of constraints in instance fields. For our ExecuteEntityCollection method, we'll call GetAll to get them all back and then go through and “black ball” any in the collection that do not meet the constraints. For extra flexibility, when we know we're matching string fields, we'll do the matching in a case-insensitive fashion. Here's the code:

Now all that remains is to create a filter, configure it, and call the ExecuteEntityCollection method.

At this point, we already have a method on Bookmark called GetBookmarksForDisplay. At the moment, this returns a list of fake bookmarks; what we can do now is change it so that it returns the bookmarks from the data box. At this stage, we're going to return all of them—in the next chapter, we're going to add an additional flag to the bookmark and make a further change to GetBookmarksForDisplay to constrain against that field. For now, here's the revised implementation of GetBookmarksForDisplay:

With that method in place, all we have to do is run the project, and it will load the real bookmarks and display them. Figure 6-4 shows the result.

Figure 6-4. The Navigation form showing real bookmarks from the server

That's it! The whole thing works from end to end. We can connect up to the server, download the bookmarks, and show them on the screen. There's just one housekeeping task missing, which we'll do next.

Implementing Delete All on the Sync

The synchronization routine needs to delete all of the bookmarks off of the local device before the new bookmarks are downloaded. Although it's not obvious, at this stage we're actually creating an ever-increasing list of bookmarks on the device. It's not obvious because when the UI is built, the ordinal of the bookmark is used to choose the button to associate the bookmark with. Hence we can have multiple bookmarks with the same ordinal, and the result is to just keep reconfiguring the same bookmark again and again.

Here's the code:

All we have to do once we have that method is call DeleteAll from within the GetLatest method on Sync. Here's the code:

Using the ORM Subsystem to Support Tombstoning

Before we finish the chapter, we should clear up the issue related to tombstoning the applications.

As discussed previously, when we switch to another application (of which Internet Explorer is one), we will get dismissed from memory automatically. The state of our application is not preserved when this happens—we are responsible for serializing and deserializing whatever state we want to keep in order to maintain our application. The only state that we absolutely need to keep in this fashion is our logon token to the services.

Various bits of documentation related to tombstoning suggest using isolated storage to keep the data safe. We already use isolated storage with our ORM subsystem, so it seems logical to reuse this for this purpose. Specifically we'll build a new entity called TombstoneItem and create a related entity type. The format of TombstoneItem will be as a basic name/value pair.

Without further ado, we'll define our TombstoneItem class like this:

To use this name/value collection, we'll need to be able to get a TombstoneItem instance for a given name. We'll do this via a method called GetTombstoneItem, which will use the DataBoxFilter that we built earlier, plus it will have the capability to create a new item, should one not be found. Here's the code:

As you know, in order to use entities, we need to define an entity type. As before, we'll do this within the SixBookmarksRuntime class. Here's the modified code:

To support tombstoning, the Windows Phone 7 runtime will call events on our application class—specifically Activated and Deactivated. When we're deactivated, we need to store the user token held in static memory within the RestServiceProxy base class. (For a more elegant solution, each class that you know should be storing state could be enlisted in some sort of chain, and each class given responsibility for storing its own state. However, this is probably good enough for this example.) Here's the “deactivated” event handler:

The “activated” handler is a similar shape, although, on top of restoring the data, we also have to “reboot” the application runtime. This is done by using a method called EnsureInitialized, which we'll build in a moment. Here's the “activated” handler:

The operation of EnsureInitialized is very straightforward. By calling any static method on the class, we'll end up calling the constructor as we did before. Here's the code:

There's one final thing to consider. Our state is persistently stored on disk; therefore we have to reset it when the application starts. We can listen out for the “launching” event and delete the tombstone item out at this stage. Here's the code:

That's all we need to do! Now we can flip back and forth between our application and Internet Explorer with impunity.

Conclusion

In this chapter, we have seen how, despite the lack of a relational database management system on Windows Phone, we can still use the object-relational mapping approach we outlined in the system architecture chapter and implemented on iOS and Android. We saw how we could create a “data box” and entities in it as individual files. We also saw how to communicate with the standard OData service in order to download entities from the cloud service. In the next chapter, we'll look at how to push up changes to the server.