Stumbling Towards the Finish Line

In my previous two articles, I indicated that my focus on the BackPack API would span three articles. In preparing for this article it became apparent that I was either going to have to cram an incredible amount of info into this last article or just gloss over a number of key points without giving them the coverage that they deserved. Neither of those options made sense, so I've decided to add an extra article—which will allow us to focus on some of the underlying architecture of our application a bit more prior to wrapping everything up in the fourth, and final, article.

So What's Left?

Our main goal in examining the BackPack API was to create a Windows Forms application that effectively mimics BackPack functionality while connected to the Internet, and that also provides the ability, while offline, to queue modifications that can be marshaled up to the BackPack servers once connectivity has been restored. In other words, we want to be able to take our BackPack data offline—using XML to store state, modifications, and other needed info. Of course, when editing offline, it will be nice to know which nodes (or data points) have been modified offline, and are therefore out of synch with the server—or master data. To accomplish this, we can just take advantage of the fact that TreeView controls make it fairly easy to toggle an image associated with each node. Therefore, once a node becomes "dirty," it will be visually flagged as such—then, once the change has been successfully made on the server, the icon can be toggled back to its original image—letting us know that the modification is complete, and that BackPack now looks like our local copy of the data.

The final UI will look similar to the image below. A TreeView will allow us to drill into pages, and as we click on certain nodes, we'll have the ability to edit the corresponding data points. As you can see below, when a Task is selected, the Title and Completed status are made available off to the left to allow for editing.

(Click image to zoom)

If we make a change to the Task's title, and change the Completion status, as follows:

We'll want a visual indication that the node is in a non-synchronized or "dirty" state until it's been successfully synchronized with the server. Providing that indication will be as simple as providing an icon with an exclamation point and a pencil (if you've got good eyes) that indicates that the node, or the object it represents, is in the process of being modified.

Not until the modification is complete will the title of the node be updated to reflect the change, but the change will be made in our local copy of the data, and an operation to change the data on the BackPack servers will be dispatched asynchronously. In the following diagram, the flow would effectively be:

1. User saves a change in the UI—which notifies the local data store.
2. The local data store records the info, and marshals the change to the BackPack servers (meanwhile the icon/state of the node in the UI is still flagged as dirty).
3. The BackPack server responds, and the local data store is notified of the outcome, whereupon the local data store can do any additional processing of its local data if needed to bring it into sync with the master data stored on the servers.
4. Once the local data store gets done processing the notification, it, in turn, raises a notification to the UI, letting it know about the status of the operation.
5. The UI processes the notification, and modifies the UI as needed.

But what if the application is offline?

Taking Our BackPack Off-Road

If the application is off-line, then the local data store isn't able to marshal the change up to the server, and won't be able to send back a notification to the UI that the change has been completed. Instead, the operation will be queued—and will be executed later, once connectivity is restored. Meanwhile, the "dirty" icon hangs out at the corresponding node on the TreeView control—indicating to the user that the underlying node data is unsynchronized with the data on the server. That's all fine and well—but what happens if the user closes the application, with operations pending? Obviously when they restart the application, they'll want to see which nodes are still out of sync, or pending modification. That's where things get fun—because our local data store will now not only need to persist commands to be marshaled against the server, but will also need to persist pending operations so that their state can be accurately reflected in the UI when the user reloads the application in offline mode.

The focus of this article, then, will be on the mechanism that we'll use to make this asynchronous, and potentially offline, communication between the UI, the local data store, and the remote BackPack servers possible. In this article we'll just work on the overall plumbing, and will focus on getting this process to work while online. Once the entire communication process is underway and working, making the whole thing work while offline isn't much more work—though we'll leave the offline details until the next article.

Taming the User Interface

One of the cool things about TreeView controls is that each corresponding TreeNode object has a Tag property—an object that acts as a data-slot into which we can cram information about the object the node represents. In our case, at the most basic level, the Tag property could therefore be used to flag whether a particular node represents a Page, a Note, a Task, or something else. More importantly, we could also use it to keep track of the id of the page, or note, etc. being represented. But rather than cram a bunch of sloppy data into the Tag property, I've opted to create a light-weight object called a ResourceDescriptor—which, well, describes a resource:

Having this descriptor available will make processing NodeClick events much easier—we can just interrogate the clicked node's Tag property to determine what kind of activity should be allowed, as follows:

Visual C#

private void treeView1_NodeMouseClick(object sender, TreeNodeMouseClickEventArgs e)
{
    ResourceDescriptor rd = e.Node.Tag as ResourceDescriptor;
    if(rd == null || this.IsLockedNode(rd))
    {
        this.ResetFormFields();
        return;
    }
    this._currentResource = rd;
    if (e.Button == MouseButtons.Left)
        this.BindFormFields(rd);
    else if (e.Button == MouseButtons.Right)
    {
        bool showMenu = false;
        this.contextMenuNewTask.Visible = false;
        this.contextMenuNewPage.Visible = false;
        this.contextMenuNewNote.Visible = false;
        switch (rd.ResourceType)
        {
            case ResourceType.PageList:
                this.contextMenuNewPage.Visible = true;
                showMenu = true;
                break;
            case ResourceType.NoteList:
                this.contextMenuNewNote.Visible = true;
                showMenu = true;
                break;
            case ResourceType.TaskList:
                this.contextMenuNewTask.Visible = true;
                showMenu = true;
                break;
            default:
                break;
        }

        if (showMenu)
        {
            this.treeView1.ContextMenuStrip.Show();
        }
    }
}

Visual Basic

Private Sub treeView1_NodeMouseClick(ByVal sender As Object, 
ByVal e As TreeNodeMouseClickEventArgs) Handles TreeView1.NodeMouseClick
    Dim rd As ResourceDescriptor = CType(e.Node.Tag, ResourceDescriptor)
    If ((rd Is Nothing) OrElse Me.IsLockedNode(rd)) Then
        Me.ResetFormFields()
        Return
    End If
    Me._currentResource = rd
    If (e.Button = MouseButtons.Left) Then
        Me.BindFormFields(rd)
    ElseIf (e.Button = MouseButtons.Right) Then
        Dim showMenu As Boolean = False
        Me.contextMenuNewPage.Visible = False
        Me.contextMenuNewTask.Visible = False
        Me.contextMenuNewNote.Visible = False
        Select Case (rd.ResourceType)
            Case ResourceType.PageList
                Me.contextMenuNewPage.Visible = True
                showMenu = True
            Case ResourceType.NoteList
                Me.contextMenuNewNote.Visible = True
                showMenu = True
            Case ResourceType.TaskList
                Me.contextMenuNewTask.Visible = True
                showMenu = True
        End Select

        If showMenu Then
            Me.treeView1.ContextMenuStrip.Show()
        End If
    End If
End Sub

As the code above indicates, if the node was right-clicked and it is a suitable container for child nodes (such as a PageList, NoteList, or TaskList), then a corresponding context menu item can be toggled and made visible. If the node represents a piece of data that can be modified, the ResourceDescriptor is dispatched to a method that will be tasked with altering the user interface and wiring it up to allow the end-user to edit the resource in question, as seen in the following code:

Visual C#

private void BindFormFields(ResourceDescriptor descriptor)
{
    this.ResetFormFields();

    this._currentlyEditedResource = this._currentResource;
    switch (descriptor.ResourceType)
    {
        case ResourceType.Page:
            this.BindFormFormToEditPage(descriptor.PageId);
            break;
        case ResourceType.Link:
            break;
        case ResourceType.Note:
            this.BindFormToEditNote(descriptor.PageId, descriptor.ChildId);
            break;
        case ResourceType.Tag:
            break;
        case ResourceType.Task:
            this.BindFormToEditTask(descriptor.PageId, descriptor.ChildId);
            break;
        default:
            break;
    }
}

Visual Basic


Private Sub BindFormFields(ByVal descriptor As ResourceDescriptor)
    Me.ResetFormFields()

    Me._currentlyEditedResource = Me._currentResource
    Select Case (descriptor.ResourceType)
        Case ResourceType.Page
            Me.BindFormFormToEditPage(descriptor.PageId)
        Case ResourceType.Link
        Case ResourceType.Note
            Me.BindFormToEditNote(descriptor.PageId, descriptor.ChildId)
        Case ResourceType.Tag
        Case ResourceType.Task
            Me.BindFormToEditTask(descriptor.PageId, descriptor.ChildId)
    End Select
End Sub

This simple bit of code just evaluates the type of object being represented, and makes a subsequent dispatch into a method that will look up the object to edit, and bind its properties to the Winform. If the user wanted to edit a Page object, the following code would be executed:

Visual C#

private void BindFormFormToEditPage(string pageId)
 {
    this.ResetFormFields();

    // toggle field values.. 
    this.txtTitle.Visible = true;
    this.txtBody.Visible = true;
    this.lblTitle.Text = "Page Title";
    this.lblTitle.Visible = true;
    this.lblBody.Text = "Page Body";
    this.lblBody.Visible = true;

    if (pageId != null)
    {
        Page page = this._pageManager.GetPageById(pageId);
        this.txtTitle.Text = page.Title;
        this.txtBody.Text = page.Body;
    }

    this.btnSave.Text = "Save Page";
    this.btnSave.Visible = true;

    this.txtTitle.Focus();
}

Visual Basic

Private Sub BindFormFormToEditPage(ByVal pageId As String)
    Me.ResetFormFields()

    ' toggle field values.. 
    Me.txtTitle.Visible = True
    Me.txtBody.Visible = True
    Me.lblTitle.Text = "Page Title"
    Me.lblTitle.Visible = True
    Me.lblBody.Text = "Page Body"
    Me.lblBody.Visible = True

    If (Not (pageId) Is Nothing) Then
        Dim page As Page = Me._pageManager.GetPageById(pageId)
        Me.txtTitle.Text = page.Title
        Me.txtBody.Text = page.Body
    End If

    Me.btnSave.Text = "Save Page"
    Me.btnSave.Visible = True

    Me.txtTitle.Focus()
End Sub

If the pageId is null, then blank fields for the Title and Body will be displayed in the Winform. If the pageId isn't null, the page represented by the node will be loaded from the PageManager (our local data store), and the page's title and body will be bound to the Winform for editing.

As you can see, ResourceDescriptors can be quite handy. They not only provide an easy way to determine what kind of an object a particular node represents—but they can also be used to painlessly retrieve that object from the PageManager which serves as our local data store. And, while it's nice to be able to use a Node to look up its corresponding object, we'll eventually need that 'lookup' process to be a two-way street. In other words, we'll want and need the ability to find the TreeNode that represents a given piece of BackPack data. The easiest way to do this is to bind the ResourceDescriptor's "signature" (its overridden .ToString() output) into a hash table with the node in question as nodes are initially created and bound to the Winform when pages are loaded. The following helper function handles the details for us:

Visual C#

private void RegisterNode(TreeNode node)
{
    ResourceDescriptor rd = node.Tag as ResourceDescriptor;
    if (rd != null) 
        this._nodeLookups.Add(rd.ToString(), node);
}

Visual Basic

Private Sub RegisterNode(ByVal node As TreeNode)
    Dim rd As ResourceDescriptor = CType(node.Tag, ResourceDescriptor)
    If (Not (rd) Is Nothing) Then
        Me._nodeLookups.Add(rd.ToString, node)
    End If
End Sub

With this simple lookup in place, the UI can use a notification from the data store about a particular data point being updated to find the node that represents the modified data and refresh, or update, the UI as needed (to remove the "dirty" icon, and other things).

ResourceDescriptors Go on a World Tour

In addition to allowing simple access to information about the object that a particular node represents, a ResourceDescriptor can also be used as part of a state object that can be sent clear into the BackPackGateway object, and returned back to the user interface as part of an accompanying EventArgs class announcing the completion of a remotely executed operation having completed. But, rather than pass it in all by its lonesome, we'll actually end up bundling it into a PendingOperation object—which will not only describe the piece of data being modified, but can also be used to describe the operation being attempted.

Having such an object will make "bouncing" data back and forth between our tiers much easier to manage. It will also provide an excellent way to serialize pending operations—which we'll look at in the next article.

The New Face of Modifications

In the first article on the BackPack API, we looked at how to translate user input into dynamically generated XML that could then be sent to the BackPack servers. Now that we have an object model in place (created in the second BackPack API article), and a better UI, as well as accompanying "descriptors" to describe the objects and operations being attempted, the flow for modifying data has changed a good deal. For example, consider the code below which handles the assembly of user input to save a modified (or newly created) page:

Visual C#

private void SavePage(ResourceDescriptor descriptor)
{
    // TODO: validate input:
    string newTitle = this.txtTitle.Text.Trim();
    string newBody = this.txtBody.Text.Trim();

    if (descriptor.PageId == null)
    {
        string tempId = this._pageManager.CreatePage(newTitle, newBody);

        ResourceDescriptor newPage = new ResourceDescriptor(tempId, null, ResourceType.Page);
        this.LockNode(newPage);
        this.FlagNodeAsDirty(newPage, OperationType.Create);
    }
    else
    {
        Page page = this._pageManager.GetPageById(descriptor.PageId);

        if (newTitle != page.Title)
        {
            page.UpdateTitle(newTitle);
            this.FlagNodeAsDirty(descriptor, OperationType.Update);
        }

        if (newBody != page.Body)
        {
            page.UpdateBody(newBody);
            this.FlagNodeAsDirty(descriptor, OperationType.Update);
        }
    }
}

Visual Basic

Private Sub SavePage(ByVal descriptor As ResourceDescriptor)
    ' TODO: validate input:
    Dim newTitle As String = Me.txtTitle.Text.Trim
    Dim newBody As String = Me.txtBody.Text.Trim

    If (descriptor.PageId = Nothing) Then
        Dim tempId As String = Me._pageManager.CreatePage(newTitle,
            newBody)
        Dim newPage As ResourceDescriptor = New
             ResourceDescriptor(tempId, Nothing, ResourceType.Page)
        Me.LockNode(newPage)
        Me.FlagNodeAsDirty(newPage, OperationType.Create)
    Else
        Dim page As Page = 
             Me._pageManager.GetPageById(descriptor.PageId)

        If (newTitle <> page.Title) Then
            page.UpdateTitle(newTitle)
            Me.FlagNodeAsDirty(descriptor, OperationType.Update)
        End If

        If (newBody <> page.Body) Then
            page.UpdateBody(newBody)
            Me.FlagNodeAsDirty(descriptor, OperationType.Update)
        End If
    End If
End Sub

Note that a ResourceDescriptor is passed into this method as the only argument—this descriptor is the Tag corresponding to the last TreeNode to have been place in edit mode. Having the descriptor available in this method allows us to fetch a copy of the underlying object being modified and allows us to compare it to the currently attempted changes. Some simple logic determines if the requested operation represents the modification of an existing page, or the attempt to create a new page, and handles bundling up the corresponding user input as needed. Once that's complete, the method then dispatches the user data to the appropriate BackPack object for processing (if it's a page, the page exposes methods for modifying its Title and Body, and if a new page is requested, the PageManager exposes a method for the creation of a new page). Once the actual operation to make the change has been routed to the appropriate object, there remains the task of toggling the node's icon to indicate that the underlying data is now out of sync. The "toggling" process is handled by a simple helper method that flags the node as dirty by changing its icon, and registering the node in a hash table that keeps a reference count to the current number of operations queued against the given node. If the operation involves the creation of a new object, then, in addition to being flagged as pending, the node is also locked—meaning that attempts to edit it (or add children) will be blocked—which needs to be the case, as we don't yet have an Id to use for modifying the object on the BackPack servers.

Logic for translating user input into XML and for generating the URL to access on the servers remains largely the same, as can be seen in the following code that handles the creation of a new page on the PageManager.

Visual C#

public string CreatePage(string title, string body)
{
    Page page = new Page(title, body);
    page.Id = PageManager.GenerateTemporaryObjectId(typeof(Page));

    this.AddPage(page);
    
    XmlDocument args = new XmlDocument();
    XmlElement pageNode = args.CreateElement("page");
    XmlElement titleNode = args.CreateElement("title");
    titleNode.InnerText = title;
    XmlElement description = args.CreateElement("description");
    description.InnerText = body;

    pageNode.AppendChild(titleNode);
    pageNode.AppendChild(description);

    ResourceDescriptor rd = new ResourceDescriptor(page.Id, null, ResourceType.Page);
    PendingOperation op = new PendingOperation(rd, OperationType.Create, null);

    string methodUrl = "/ws/pages/new";

    this.InvokeOperation(methodUrl, pageNode, op);
    return page.Id;
}

Visual Basic

Public Function CreatePage(ByVal title As String, ByVal body As String) 
    As String
    Dim page As Page = New Page(title, body)
    page.Id = PageManager.GenerateTemporaryObjectId(GetType(Page))

    Me.AddPage(page)

    Dim args As XmlDocument = New XmlDocument
    Dim pageNode As XmlElement = args.CreateElement("page")
    Dim titleNode As XmlElement = args.CreateElement("title")
    titleNode.InnerText = title
    Dim description As XmlElement = args.CreateElement("description")
    description.InnerText = body

    pageNode.AppendChild(titleNode)
    pageNode.AppendChild(description)

    Dim rd As ResourceDescriptor = New ResourceDescriptor(page.Id, 
         Nothing, ResourceType.Page)
    Dim op As PendingOperation = New PendingOperation(rd, 
         OperationType.Create, Nothing)

    Dim methodUrl As String = "/ws/pages/new"

    Me.InvokeOperation(methodUrl, pageNode, op)
    Return page.Id
End Function

The big difference is the creation of a ResourceDescriptor to describe the object being passed for modification out to the BackPack servers (I could have just passed in the existing ResourceDescriptor from the UI, but I didn't want them coupled that closely), as well as the creation of a PendingOperation object used to describe the operation being attempted. Note, too, that a call to this.AddPage() is also made in this method—before we even attempt to send our change to the BackPack Servers. This means that our local copy of the BackPack data has already been updated as if the operation had successfully completed. If the attempted operation fails we can rollback by interrogating the PendingOperation details and using the previous version of the object—if one was available (the third argument for creating a new PendingOperation is a slot for an object representing the previous 'version' of the object that is being modified).

When the operation is invoked, and routed to the BackPackGateway, the gateway effectively just ignores the PendingOperation object sent in, and merely attaches it to the EventArgs object used to notify the page manager that the operation has completed. The PageManager handles the event with the GatewayResponded method:

Visual C#

public void GatewayResponded(object sender, RemoteOperationCompleteEventArgs e)
{
    // handle the event (details covered below) 
}

Visual Basic


Public Sub GatewayResponded(ByVal sender As Object,
    ByVal e As RemoteOperationCompleteEventArgs)
    'handle the event (details covered below)
End Sub

The first thing that this method does is evaluate whether or not an error occurred—and then handles it accordingly (we'll cover rollbacks and other issues in the next article):

Visual C#   

    OperationCompleteEventArgs eventArgs = null;
    if (e.OperationStatus == CompletionStatus.Fail)
    {
        if (e.PendingOperation.OperationType == OperationType.Read)
            throw new Exception("Error Reading Data From Server", e.Exception);

        eventArgs = new OperationCompleteEventArgs(
            e.PendingOperation, CompletionStatus.Fail, e.Exception);
    }
    if (eventArgs != null)
        this.OnDataOperationComplete(eventArgs);

Visual Basic 

    Dim eventArgs As OperationCompleteEventArgs = Nothing
    If (e.OperationStatus = CompletionStatus.Fail) Then
        If (e.PendingOperation.OperationType = OperationType.Read) Then
            Throw New Exception("Error Reading Data From Server", 
                 e.Exception)
        End If

        eventArgs = New OperationCompleteEventArgs(e.PendingOperation, 
            CompletionStatus.Fail, e.Exception)
    End If
    If (Not (eventArgs) Is Nothing) Then
        Me.OnDataOperationComplete(eventArgs)
    End If

If there were no errors detected, the PageManager then needs to evaluate the operation type and do any additional processing necessary to bring the local data store into sync with the BackPack server—such as swapping out the tempId with the newId returned by the BackPack Servers in the case of objects that were successfully created, as follows:

Visual C#   

    else
    {
        // determine if extra processing is required and handle it if needed.
        switch (e.PendingOperation.OperationType)
        {
            case OperationType.Read:
                if (e.PendingOperation.Descriptor.ResourceType == ResourceType.PageList)
                    this.PagesListed(e.ResponseText);
                else if (e.PendingOperation.Descriptor.ResourceType == ResourceType.Page)
                    this.SinglePageReturned(e.ResponseText);
                // this operation doesn't need to be announced to the UI (we're done)
                break;
            case OperationType.Create:
                this.ReplaceTempIdWithPermanentId(e.PendingOperation, e.ResponseText);

                eventArgs = new OperationCompleteEventArgs(e.PendingOperation);
                break;
            case OperationType.Remove:
                // covered in the next article
                break;
            default:
                // just let the UI know to unbind/etc the matching node:
                eventArgs = new OperationCompleteEventArgs(e.PendingOperation);
                break;
        }
    }

    // remove the operation from the list of pending operations so that it won't be 
    //serialized upon form close.
    if (this._pendingOperations.Contains(e.PendingOperation))
        this._pendingOperations.Remove(e.PendingOperation);

    // notify the UI/Winform if needed:
    if (eventArgs != null)
        this.OnDataOperationComplete(eventArgs);

Visual Basic   

     Else
        ' determine if extra processing is required and handle it if
        ' needed.
        Select Case (e.PendingOperation.OperationType)
            Case OperationType.Read
                If (e.PendingOperation.Descriptor.ResourceType =
                    ResourceType.PageList) Then
                    Me.PagesListed(e.ResponseText)
                ElseIf (e.PendingOperation.Descriptor.ResourceType = 
                        ResourceType.Page) Then
                    Me.SinglePageReturned(e.ResponseText)
                End If
                ' this operation doesn't need to be announced to the UI
                ' (we're done)
            Case OperationType.Create
                Me.ReplaceTempIdWithPermanentId(e.PendingOperation, 
                    e.ResponseText)

                eventArgs = 
                    New OperationCompleteEventArgs(e.PendingOperation)
            Case OperationType.Remove
                ' covered in the next article
            Case Else
                eventArgs = 
                    New OperationCompleteEventArgs(e.PendingOperation)
        End Select
    End If

    ' remove the operation from the list of pending operations so that it
    ' won't be serialized upon form close.
    If Me._pendingOperations.Contains(e.PendingOperation) Then
        Me._pendingOperations.Remove(e.PendingOperation)
    End If

    ' notify the UI/winform if needed:
    If (Not (eventArgs) Is Nothing) Then
        Me.OnDataOperationComplete(eventArgs)
    End If

In addition to any local processing needed, the PageManager also removes the PendingOperation object from the internal list it is using to track pending operations (so that if the application is persisted, this operation won't end up being flagged as an artifact). Once the PageManager is done with processing, it, in turn, raises an event notifying the UI of the completed operation—and the UI can then respond with logic designed to bring the state of the UI into sync with the local data store (which is now synchronized with the BackPack servers). Think of it sort of as a ripple effect: the UI plunks data into the data store (PageManager) which causes it to notify the remote servers—and once the remote operation is complete, the PageManager is notified, and it ultimately notifies the UI. The code for handling that final notification, in the UI, is as follows:

Visual C#

private void DataOperationComplete(object sender, OperationCompleteEventArgs e)
{
    if (e.OperationStatus == CompletionStatus.Fail)
    {
        if (e.Operation.OperationType == OperationType.Read)
        {
            string inner = string.Empty;
            if (e.Exception != null)
                inner = System.Environment.NewLine + e.Exception.Message;
            MessageBox.Show("Error Reading Pages From the Server.");
        }
        else
        {
            // TODO:
            // rollback the node to it's previous state. 
        }
    }
    else
    {
        if (e.Operation.OperationType == OperationType.Create)
        {
            ResourceDescriptor replacement = null;
            TreeNode modified = 
               this._nodeLookups[e.Operation.Descriptor.ToString()]
               as TreeNode;
            if (modified != null)
            {
                string newId = (string)e.Operation.State;
                
                if (e.Operation.Descriptor.ResourceType == ResourceType.Page)
                {
                    replacement = 
                       new ResourceDescriptor(newId, null, ResourceType.Page);
                }
                else
                {
                    replacement = new ResourceDescriptor(
                        e.Operation.Descriptor.PageId, newId, 
                        e.Operation.Descriptor.ResourceType);
                }

                
                lock (this._nodeSync)
                {
                    this._nodeLookups.Remove(e.Operation.Descriptor.ToString());
                    this._nodeLookups.Add(replacement.ToString(), modified);

                    // now modify the pending nodes:
                    int count = 
                         (int)this._pendingNodes[e.Operation.Descriptor.ToString()];
                    this._pendingNodes.Remove(e.Operation.Descriptor.ToString());
                    this._pendingNodes.Add(replacement.ToString(), count);
                }
                this.BeginInvoke(new TreeNodeTagBinder(this.BindReplacementTag), 
                    new object[] { modified, e.Operation.Descriptor, replacement });
            }
            this.UnlockNode(e.Operation.Descriptor);
            this.UnFlagNode(replacement);
        }
        else
        {
            this.UnFlagNode(e.Operation.Descriptor);
        }
    }
}

Visual Basic

Private Sub DataOperationComplete(ByVal sender As Object, _
      ByVal e As OperationCompleteEventArgs)
    If (e.OperationStatus = CompletionStatus.Fail) Then
        If (e.Operation.OperationType = OperationType.Read) Then
            Dim inner As String = String.Empty
            If (Not (e.Exception) Is Nothing) Then
                inner = (System.Environment.NewLine + e.Exception.Message)
            End If
            MessageBox.Show("Error Reading Pages From the Server.")
        Else
            ' TODO:
            ' rollback the node to it's previous state. 
        End If
    ElseIf (e.Operation.OperationType = OperationType.Create) Then
        Dim replacement As ResourceDescriptor = Nothing
        Dim modified As TreeNode = 
            CType(Me._nodeLookups(e.Operation.Descriptor.ToString),
                TreeNode)
        If (Not (modified) Is Nothing) Then
            Dim newId As String = CType(e.Operation.State, String)

            If (e.Operation.Descriptor.ResourceType = 
             ResourceType.Page) Then
                replacement = New ResourceDescriptor(newId, Nothing, 
                 ResourceType.Page)
            Else
                replacement = New 
                 ResourceDescriptor(e.Operation.Descriptor.PageId, 
                 newId, e.Operation.Descriptor.ResourceType)
            End If

            modified.Tag = replacement
            SyncLock Me._nodeSync
                    
              Me._nodeLookups.Remove(e.Operation.Descriptor.ToString)
              Me._nodeLookups.Add(replacement.ToString, modified)
              ' now modify the pending nodes:
              Dim count As Integer = 
              CType(Me._pendingNodes(e.Operation.Descriptor.ToString), 
              Integer)
                    
              Me._pendingNodes.Remove(e.Operation.Descriptor.ToString)
              Me._pendingNodes.Add(replacement.ToString, count)
            End SyncLock
            Me.BeginInvoke(New TreeNodeTagBinder(
                AddressOf Me.BindReplacementTag), New Object() {
                modified, e.Operation.Descriptor, replacement})

        End If
        Me.UnlockNode(e.Operation.Descriptor)
        Me.UnFlagNode(replacement)
    Else
        Me.UnFlagNode(e.Operation.Descriptor)
    End If
End Sub

As you can see, that's a fairly hefty amount of code—and maybe it will deserve a refactoring in the final version of the application. The flow, however, isn't actually as complex as it looks at first blush. First the method checks to see if the operation failed remotely—in which case it will handle the rollback needed to put the UI back in sync with the BackPack servers. If the operation was successfully completed, things are very straight-forward UNLESS the operation was the creation of a new object. If it wasn't the creation of a new object, the descriptor accompanying the operation is handed off to a helper method that will un-toggle the "dirty" icon for the node in question. The helper method will also use the descriptor to "reach back in" to the underlying data store (where data is now synchronized with the servers) and grab the new title of the node, if there is one. It can then use the updated data to refresh the Node's title as needed.

If the pending operation was for the creation of an object, things are a bit messy—but effectively just involve replacing the tempId used as a placeholder with the actual Id of the object as returned from BackPack. Additional work is then needed to make sure references to the temporary node are replaced with references to the node with its new Id—so that modifications can be made, and children can be added.

Are We There Yet?

We're not quite there yet. But we've covered a decoupled way of marshalling data back and forth between our various tiers, which accomplishes two things: 1) it will let us provide end users with a visual indicator that their data is out of sync, and 2) because of the disconnected nature of everything, we'll be able to easily manage taking our application offline in the next article by persisting the state of our objects, as well as persisting information about pending operations.

We still have a way to go yet, but for now you can take the current implementation for a test drive. You won't be able to delete objects with the application in its present state, but you will be able to modify pages, tasks, and notes—as well as create new ones by right-clicking the appropriate nodes. It may not seem like much to the uninitiated, but once you know what's going on under the covers, it's pretty cool to watch in action. Once you've done that, try tracing the flow of the various messages throughout the application, and see if you can spot the areas where serializing our application and its state make sense. Once you've found those, think about how you'd go about serializing them—we've covered almost all of the necessary information, from an XML standpoint, in previous articles—so there really won't be too much for us to do in the next article, apart from winding up a number of loose ends, ensuring serialization of state, and detecting network availability.

A while back I got tired of looking for a simple solution to performing 'on the fly' XSL Transformations. I didn't want some memory-hog tool to completely isolate me from the details of the transform through layers of abstraction—just a light-weight tool that would act as a simple transformation engine. I just needed something to run a transform based on my stylesheet and let me quickly check the results in an iterative fashion. I looked for a while, and didn't find anything like that available. So I built my own simple solution. It wasn't much—just a simple WinForm where I could specify the location of an XML file and a corresponding XSL file and then push a button to fire the results of the transformation to a text box for review. While that worked fine, I recently decided that my home-grown solution needed a bit of a face-lift. Nothing dramatic. Just a few tweaks to make it easier to fine-tune my stylesheets on the fly.

A Glorified Text Editor

To keep things simple, I just wanted the added ability to edit my XML and XSL (mostly the latter) documents in the same tool that I used to transform them. I'd been using either an open instance of Visual Studio to edit them (nice, but heavy), or NotePad. In a perfect world, I'd get some of the key benefits of an editor like Visual Studio, but with the "weight" of something like NotePad. NotePad is actually fine for editing text files—only I hate the fact that it doesn't remember my tab position. In other words, if I've "tabbed over" three times (for formatting purposes) and type something followed by a carriage return, I'm back at the left margin, and not tabbed to the place where I was in the previous line. So, my thoughts on the upgrade were that if I could just get the text boxes where I would be doing my editing to remember my tab position, then I'd be happy. Only... I really like having tag completion in Visual Studio as well. It's not like I can't do it myself, but I certainly like having my tags closed automatically. So, I figured I needed both aspects in my new "editor" enabled version of my transform tool to make me happy.

Making Mikey Happy: Remembering Tab Position

Figuring out how to remember tab positioning turned out to be tougher than I imagined—but in a strange way. Coding the solution wasn't very hard at all, and only took about half an hour to perfect. The hard part was figuring out that I had to code it myself. For some reason I figured that something in the Framework would make the task almost as easy as tweaking a property on one of the built-in TextBox controls that ship with the Framework. After poring over the MSDN docs, trying to track down existing solutions on the web, and bugging a listserve that I spend a lot of time on, I decided to just write the functionality myself.

Once I made the decision to code the functionality myself, the task became fairly easy. The trick was just to figure out what the number of preceding tabs were in the previous line, and plunk the same number of tabs in front of the cursor each time that a carriage return was detected. The logic to handle all of this was pretty simple and just revolved around getting a handle on the textbox housing the desired text, and then calculating the preceding line and existing tab count. Once those were located, all I had to do was insert a corresponding number of tabs into the textbox at the current position, and then advance the cursor by moving the SelectionStart property:

Visual C#

private bool HandleBlockTabbing(object sender)
{
    TextBox current = (TextBox)sender;
    int charIndex = current.SelectionStart;
    string work = current.Text.Substring(0, charIndex);

    int currentLineNumber = current.GetLineFromCharIndex(charIndex);

    // the carriage return hasn't happened yet... 
    //      so the 'previous' line is the current one.
    string previousLineText;
    if(current.Lines.Length <= currentLineNumber)
        previousLineText = current.Lines[current.Lines.Length - 1];
    else
        previousLineText = current.Lines[currentLineNumber];

    if (previousLineText.StartsWith("\t"))
    {
        string tabs = string.Empty;
        // first non-TAB character
        Match m = Regex.Match(previousLineText, "[^\t]");
        if (m.Success)
            tabs = previousLineText.Substring(0,
                previousLineText.IndexOf(m.Value));
        else // there were only tabs (no other chars)
            tabs = previousLineText;

        string added = "\r\n" + tabs;

        current.Text = current.Text.Insert(charIndex, added);
        current.SelectionStart = charIndex + added.Length;

        return true;
    }

    return false;
}

Visual Basic

Private Function HandleBlockTabbing(ByVal sender As Object) As Boolean
    Dim current As SimpleEditBox = CType(sender, SimpleEditBox)
    Dim charIndex As Integer = current.SelectionStart
    Dim work As String = current.Text.Substring(0, charIndex)
    Dim currentLineNumber As Integer = 
        current.GetLineFromCharIndex(charIndex)

    ' the carriage return hasn't happened yet... 
    '      so the 'previous' line is the current one.
    Dim previousLineText As String

    If current.Lines.Length <= currentLineNumber Then
        previousLineText = current.Lines(current.Lines.Length - 1)
    Else
        previousLineText = current.Lines(currentLineNumber)
    End If

    If previousLineText.StartsWith("" & vbTab) Then
        Dim tabs As String = String.Empty
        ' first non-TAB character
        Dim m As Match = Regex.Match(previousLineText, "[^\t]")
        If m.Success Then
            tabs = previousLineText.Substring(0, 
                previousLineText.IndexOf(m.Value))
        Else
            tabs = previousLineText
        End If
        Dim added As String = (vbCrLf + tabs)
        current.Text = current.Text.Insert(charIndex, added)
        current.SelectionStart = (charIndex + added.Length)
        Return True
    End If
    Return False
End Function

One big thing to note about the above code is that it's taking place in the KeyPress event—so the carriage return hasn't really "happened" yet; it's currently in the state of being processed. But once the KeyPress event is handled for a carriage return, the logic above makes a screen shot like the one below possible:

The cool thing is that in the above screen shot, the logic discerned that the previous line was one tab over and then just inserted a carriage return plus a single tab into the current line of text (technically the third line of text, because the carriage return hasn't actually happened yet). Once that was put in place, the current selection was advanced to the end of the carriage return and the newly inserted tab. Then the textbox was "told" that the keystroke was handled (the return true part of the code—more on that in a second), and the textbox therefore doesn't need to do any more processing on the keystroke (like add a carriage return of its own). The beauty of this approach is that there are no spooky characters in place; a simple BACKSPACE will remove the existing tab. It's like we've just used the textbox to do our typing for us, that's all.

Making Mikey Happy: Tag Completion

I initially figured that tag completion would just be a question of using a regular expression to determine the name of the currently uncompleted tag (if there was one) each time a ">" was detected, and then adding closing tags as needed. It turned out to be about that hard, only I needed to account for directives, comments, and empty tags as well. I also needed to be able to account for stray ">" characters. The goal of my tag completion was to create functionality that was more like cruise control (a lazy person's driving aid), instead of an auto-pilot (where you'd effectively give up control of what was going on). To handle all of these contingencies, I just threw in a helper method where I could encapsulate all of the various permutations and just report to the caller (main logic) if it was to close the tag or not. Here's the code to handle the detection of a ">" in the KeyPress event:

Visual C#

private bool HandleBlockTabbing(object sender)
{
    TextBox current = (TextBox)sender;
    int charIndex = current.SelectionStart;
    string work = current.Text.Substring(0, charIndex);

    int currentLineNumber = current.GetLineFromCharIndex(charIndex);

    // the carriage return hasn't happened yet... 
    //      so the 'previous' line is the current one.
    string previousLineText;
    if(current.Lines.Length <= currentLineNumber)
        previousLineText = current.Lines[current.Lines.Length - 1];
    else
        previousLineText = current.Lines[currentLineNumber];

    if (previousLineText.StartsWith("\t"))
    {
        string tabs = string.Empty;
        // first non-TAB character
        Match m = Regex.Match(previousLineText, "[^\t]");
        if (m.Success)
            tabs = previousLineText.Substring(0,
                previousLineText.IndexOf(m.Value));
        else // there were only tabs (no other chars)
            tabs = previousLineText;

        string added = "\r\n" + tabs;

        current.Text = current.Text.Insert(charIndex, added);
        current.SelectionStart = charIndex + added.Length;

        return true;
    }

    return false;
}

Visual Basic

Private Function HandleBlockTabbing(ByVal sender As Object) As Boolean
    Dim current As SimpleEditBox = CType(sender, SimpleEditBox)
    Dim charIndex As Integer = current.SelectionStart
    Dim work As String = current.Text.Substring(0, charIndex)
    Dim currentLineNumber As Integer = 
        current.GetLineFromCharIndex(charIndex)

    ' the carriage return hasn't happened yet... 
    '      so the 'previous' line is the current one.
    Dim previousLineText As String

    If current.Lines.Length <= currentLineNumber Then
        previousLineText = current.Lines(current.Lines.Length - 1)
    Else
        previousLineText = current.Lines(currentLineNumber)
    End If

    If previousLineText.StartsWith("" & vbTab) Then
        Dim tabs As String = String.Empty
        ' first non-TAB character
        Dim m As Match = Regex.Match(previousLineText, "[^\t]")
        If m.Success Then
            tabs = previousLineText.Substring(0, 
                previousLineText.IndexOf(m.Value))
        Else
            tabs = previousLineText
        End If
        Dim added As String = (vbCrLf + tabs)
        current.Text = current.Text.Insert(charIndex, added)
        current.SelectionStart = (charIndex + added.Length)
        Return True
    End If
    Return False
End Function

Note that, in many ways, it's very similar to the code that handles tabbing: it just determines if characters need to be added, and then inserts them if needed. The difference is that it only advances the cursor one space when it's done doing the inserting task, so as to place the cursor between the beginning and ending tags. Whether or not the tag needs to be closed is decided by the following bit of helper logic:

Visual C#

private bool CurrentPositionNeedsClosingTag(string input)
{
    string scrubbedText = input.Replace("\r", string.Empty);
    scrubbedText = scrubbedText.Replace("\n", string.Empty);
    scrubbedText = scrubbedText.Replace(" ", string.Empty);
    // check lots of various tag ending types, and then other issues/hacks

    // ignore directives, comments, and empty tags:
    bool isDirective = scrubbedText.EndsWith("?");
    bool isComment = scrubbedText.EndsWith("--");
    bool isEmptyTag = scrubbedText.EndsWith("/");
    if (isDirective || isComment || isEmptyTag)
        return false;

    // watch out for stray tags and truly empty tags ("<>")
    if (scrubbedText.EndsWith(">") || scrubbedText.EndsWith("<>"))
        return false;

    // watch out for explicit closing tags 
    //      ("</endMyTagByHand>" - don't want: "</end><//end>")
    //  HACK: should be done with a regex.. 
    int position = scrubbedText.LastIndexOf("<");
    if (scrubbedText.Substring(position).StartsWith("</"))
        return false;

    return true;
}

Visual Basic

Private Function CurrentPositionNeedsClosingTag(ByVal input As String) As Boolean
    Dim scrubbedText As String = input.Replace(vbCr, String.Empty)
    scrubbedText = scrubbedText.Replace(vbLf, String.Empty)
    scrubbedText = scrubbedText.Replace(" ", String.Empty)
    ' check lots of various tag ending types, and then other issues/hacks
    ' ignore directives, comments, and empty tags:
    Dim isDirective As Boolean = scrubbedText.EndsWith("?")
    Dim isComment As Boolean = scrubbedText.EndsWith("--")
    Dim isEmptyTag As Boolean = scrubbedText.EndsWith("/")
    If (isDirective _
                OrElse (isComment OrElse isEmptyTag)) Then
        Return False
    End If
    ' watch out for stray tags and truly empty tags ("<>")
    If (scrubbedText.EndsWith(">") OrElse scrubbedText.EndsWith("<>")) 
    Then
        Return False
    End If
    ' watch out for explicit closing tags 
    '      ("</endMyTagByHand>" - don't want: "</end><//end>")
    '  HACK: should be done with a regex.. 
    Dim position As Integer = scrubbedText.LastIndexOf("<")
    If scrubbedText.Substring(position).StartsWith("</") Then
        Return False
    End If
    Return True
End Function

Once in place, the tag completion turned out to be pretty spiffy. It won't close comments, directives, or empty tags (i.e. <tag />); just open tags, even ones that span multiple lines:

Coupled with the "tab memory" functionality, I now had enough editor functionality to make me happy.

Making Consumers Happy: Subclassing

When I was first testing out the tabbing and tag-completion logic, I just did it in a WinForm, and handled the KeyPress event. My long-term goal, though, was to create a subclass of System.Windows.Forms.TextBox that would encapsulate this logic away to make reuse much easier. Imagine trying to handle tabbing and tag-completion for three textboxes on the same form, for example; it could be done, but wouldn't be pretty. Creating the subclass of TextBox was very easy. I just added a new user control to my current project, changed its inheritance from UserControl to TextBox and then dropped in the code as follows:

Visual C#

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Drawing;
using System.Data;
using System.Text;
using System.Windows.Forms;
using System.Text.RegularExpressions;

namespace XSLT_Former
{
    
    public partial class SimpleEditorBox : TextBox
    {
        public SimpleEditorBox()
        {
            InitializeComponent();

                // make sure that tab and enter are allowed by
                // default in this specialized text box:
            base.AcceptsReturn = true;
            base.AcceptsTab = true;
        }

        protected override void OnKeyPress(KeyPressEventArgs e)
        {
            if (e.KeyChar == 13) // enter/carriage return
                e.Handled = this.HandleBlockTabbing(this);
            if (e.KeyChar == '>')
                e.Handled = this.HandleTagCompletion(this);

            base.OnKeyPress(e);
        }
        private bool HandleBlockTabbing(object sender)
        {
             // elided - code same as above
        }

        private bool HandleTagCompletion(object sender)
        {
             // elided - code same as above 
        }

        private bool CurrentPositionNeedsClosingTag(string input)
        {
             // elided - code same as above
        }
    }
}

Visual Basic

Imports System.Text.RegularExpressions

Public Class SimpleEditBox
    Inherits System.Windows.Forms.TextBox

    Public Sub New()
        ' This call is required by the Windows Form Designer.
        InitializeComponent()

        MyBase.AcceptsReturn = True
        MyBase.AcceptsTab = True
    End Sub

    Protected Overrides Sub OnKeyPress(ByVal e As KeyPressEventArgs)
        If (e.KeyChar = CType(ChrW(13), Char)) Then
            e.Handled = Me.HandleBlockTabbing(Me)
        End If
        If (e.KeyChar = CType(ChrW(62), Char)) Then
            e.Handled = Me.HandleTagCompletion(Me)
        End If
        MyBase.OnKeyPress(e)
    End Sub

    Private Function HandleBlockTabbing(ByVal sender As Object) As Boolean
        ' elided - code same as above
    End Function

    Private Function HandleTagCompletion(ByVal sender As Object) 
        As Boolean
        ' elided - code same as above
    End Function

    Private Function CurrentPositionNeedsClosingTag(ByVal input As String)
        As Boolean
        ' elided - code same as above
    End Function
End Class

As you can see, nothing special. The KeyPress event is no longer being handled; rather, the OnKeyPress method has been safely overridden such that this control can be further sub classed if desired. The big plus, of course, is that dropping a SimpleEditBox onto a WinForm provides a textbox that now remembers tab position and closes XML (and HTML) tags.

Creating a Work Area

With a SimpleEditorBox control now available to handle the whiz-bang features for text editing, it was time to create a WinForm that I could use as a work area. In it I needed an area to display the XML document, an XSL document (or my stylesheet) as well as the output. I wanted all three areas to editable, but maximizing the space for each area would have been problematic to try and manage. So I cheated and just used two splitter controls to allow a high degree of flexibility at run time. The first splitter divided the top (work area) from the bottom (output/results area) so that either section could be sized as needed. The second splitter—placed in the top half of the previous splitter—was to divide the XML work area from the XSL work area as follows:

Each work area was then fitted with a few simple controls to allow for the loading and saving of files. A button to execute the transform was placed in the bottom of the form, which only becomes enabled once both work areas have a file loaded. By playing around with the Anchor properties for each control and GroupBox, each work area not only retains a decent perspective when the Winform is maximized, but as the sliders are moved around to focus on one are or the other, the other two areas maintain a decent aspect ratio as well (even when seriously "scrunched" so as to appear inside an image like the one below):

As seen in the above image, I'm focusing my attention on the transform, where I've dedicated more of my real estate by tugging on the splitter bars to the desired sizing. However, the output and XML areas are still coherent and could easily become the focus of my efforts just through some more dragging on the darkened splitter bars.

Doing the Transform

The logic to handle the transform itself ends up being some pretty simple code. All it needs to be able to do is stream the contents of the XML and XSL SimpleEditBoxes in as XML, and run them through a transform.

Visual C#

private void TransformOutput()
{
    string xml = this.edtXml.Text.Trim();
    string xsl = this.edtXsl.Text.Trim();

    try
    {
        // stream the xml:
        byte[] data = Encoding.UTF8.GetBytes(xml);
        MemoryStream ms = new MemoryStream(data);

        XmlReader input = XmlReader.Create(ms); // to allow modification by xform

        // load the xsl:
        XmlDocument stylesheet = new XmlDocument();
        stylesheet.LoadXml(xsl);

        XslCompiledTransform transform = new XslCompiledTransform();
        transform.Load(stylesheet);

        // create output streams:
        MemoryStream buffer = new MemoryStream();
        StreamWriter sw = new StreamWriter(buffer);

        // transform the document:
        transform.Transform(input, null, sw);

        // turn results into a string:
        byte[] chars = buffer.ToArray();
        string output = Encoding.UTF8.GetString(chars);

        this.edtOut.Text = output;

        this.btnSaveOutput.Enabled = true;
    }
    catch (Exception ex)
    {
        this.edtOut.Text = "Error Occurred: " + Environment.NewLine + ex.Message;
    }
}

Visual Basic

Private Sub TransformOutput()
    Dim xml As String = Me.edtXml.Text.Trim
    Dim xsl As String = Me.edtXsl.Text.Trim
    Try
        ' stream the xml:
        Dim data() As Byte = Encoding.UTF8.GetBytes(xml)
        Dim ms As MemoryStream = New MemoryStream(data)
        Dim input As XmlReader = XmlReader.Create(ms)
        ' to allow modification by xform
        ' load the xsl:
        Dim stylesheet As XmlDocument = New XmlDocument
        stylesheet.LoadXml(xsl)
        Dim transform As XslCompiledTransform = New XslCompiledTransform
        transform.Load(stylesheet)
        ' create output streams:
        Dim buffer As MemoryStream = New MemoryStream
        Dim sw As StreamWriter = New StreamWriter(buffer)
        ' transform the document:
        transform.Transform(input, Nothing, sw)
        ' turn results into a string:
        Dim chars() As Byte = buffer.ToArray
        Dim output As String = Encoding.UTF8.GetString(chars)
        Me.edtOut.Text = output
        Me.btnSaveOutput.Enabled = True
    Catch ex As Exception
        Me.edtOut.Text = ("Error Occurred: " _
                    + (Environment.NewLine + ex.Message))
    End Try
End Sub

Exceptions are handled in a very simple fashion by just outputting the details of the exception to the output window. If no exception occurs, then the transform results are written to the output window. There they can be modified as needed or saved to disk using the menu options or button control available.

And there it is: a simple tool that allows you to get your hands dirty with the gory details of XSLT, along with a simple button that will render the transform for you whenever you are ready. The simple additions to the editor panes make it easier to perform ad hoc modification of the XML and XSL documents, and being able to render the transform on the fly helps make for a great way to modify your stylesheet in an iterative fashion.

One of the exciting new features of .NET 2.0 is the introduction of Generics: special template-like classes that allow developers to quickly and easily interact with collections of objects in an efficient, strongly-typed, manner. However, while a wealth of information can be found by searching the internet for articles and documentation on Generics, there's very little information available about the serialization of Generics into XML. In fact, documentation is virtually non-existent. This is too bad, because Generics lend themselves very well to serialization, and can really help make serializing collections of objects quite easy—once a few simple, but key, points are addressed. This article will take a look at some of those key points and provide some concrete examples of serializing Generics, as well as providing an overview of just how beneficial Generics are when it comes to serializing collections of objects.

The Back Pack API - Roadmap to our sample application

In my previous article, I introduced the BackPack API and mentioned that I'd spend three articles looking into how to build a Winforms application that would not only allow for direct interaction with BackPackIt.com servers to manipulate user information, but that would also allow the data to be pulled down locally and manipulated off-line. In the previous article the focus was on providing an overview of BackPack, its accompanying API, and on writing code that dynamically generated XML data that represented user input which could then be sent back to the BackPack servers for processing. While the sample application in the previous article was a bit weak, it did cover some of the key concepts of dynamic XML generation with the DOM, and also showcased how easy it is to communicate with an 'XML' Web server—all of which were key components in building the final application which will be completed in the third installment of this series.

The focus of this article will be on another key consideration and needed component of the final application: local storage of BackPack data. In order to facilitate being able to use BackPack off-line, the final application will need to operate against a local copy of a user's BackPack data. In the final application, when the user wants to change their data, the change will first be made against the local data store, and a corresponding modification will be sent for processing against the server. If the application is online, the modification will be sent immediately; otherwise, the command will be shelved until the application regains an Internet connection and can pass the command up to the BackPack servers as needed. The primary goal, therefore, will be to make BackPack "portable"—and XML will be a key player in making that so (and serializing Generics will play a large role in harnessing XML for our needs).

Of course, until operations have been successfully completed on the server, we'll want some way to know that a local copy of a page is "dirty" or pending an update on the server. We'll also want to make sure that if something happens, and the modification can't be correctly executed on the server, that we'll have some way of recovering from such an issue. But we'll deal with all of those details in the next article. Here we'll focus on a framework that will allow us to save BackPack data locally so that it can be queried as needed—and serve as the basis for making changes against the server whether we're online or offline. In other words, the goal of this article will be to provide a few more key building blocks towards the final application in the form of a simple application that will allow us to:

1. load pages from the server,
2. save them to disk, and then
3. load them from the server or from disk as needed.

Architecture and Game Plan

The BackPack API returns data as XML. That's an excellent transport mechanism, but not something we want to work with in our final application. What we really want is the ability to interact with objects—to be able to tell them WHAT to do, and not have to worry about HOW that gets done. In other words, we want encapsulation: the ability to hide implementation details from other "players" in our application such that if the HOW needs to be changed, our application doesn't break. A quick review of the BackPack API shows that it provides a number of ways to access user data. For example, notes for a given page can be pulled back by querying a specific URL which will return an XML "data-gram" full of current notes associated with the requested page, as shown in the following screen capture taken from the API's documentation:

In other words, the API provides the ability to SLICE and DICE data—which is handy, but something our final application won't need. The goal of the final application will be to encapsulate EVERYTHING (well close to everything) available in the API, and, since the BackPack application revolves around pages, our application will also target pages. In other words, if we have a local copy of every page, we can then see which lists, notes, tags, links, etc. belong to any given page as needed—without requiring a bunch of chatty interactions with the server each time we need to know something. We'll therefore want to architect our application in such a way that it's page-centric. As such, the general focus and flow of this article will be to:

1. Create a page-centric Object Model where interacting with a page provides us the ability to see assets (data) that belongs to said page, and (later, in article 3) modifying data belonging to the page is handled by the Page object itself.
2. Construct the basis of a Business Object, or middle tier, that can manipulate page objects as needed—and can handle all of the gory details associated with bringing pages in and out of existence, whether from the server or from disk.
3. Finally, we'll need to wrap the above functionality in a rudimentary GUI that will let us easily handle operations around loading and saving pages.

Building the Object Model

To build a suitable page-centric object model, we just need to gain an idea of what data points, or attributes, are found in each BackPack page, and create a corresponding data point, or property, for each in our classes. (In the third article we'll model behaviors, or methods that will allow us to modify and interact with page objects.) The quickest way to gain a sense of what data points need to be represented is to just take a look at a sample page documented in the API:

As I mentioned in the previous article, the BackPack API is well documented with good, solid, examples. This is true of the sample page covered in the API; it successfully models all of the data points potentially needed in a single page. Therefore, as you can see, a Page consists of an id, a title, a body, and potential collections of lists, notes, tags, etc. Modeling these last resource types is easy—and the logical place to start, as they are the constituent elements of any given page.

NOTE: Because a Generic Collection is frequently stored in a System.Collections.Generic.List, I've opted to call lists, in BackPack parlance, Tasks in my object model—just to make sure there won't be any confusion.

A few seconds of typing in C# Express (using Code Snippets to generate the property definitions—woot!) and Links, Notes, Tags, and Tasks have been quickly modeled (though the following image was generated in VS 2005):

Once these objects are defined, a Page object, which contains these data types as child nodes, can then be created in similar fashion. Like the classes above, it too consists of an id property, along with a couple of other string fields, and then potential collections of the classes created above:

At this point, our object model is complete—at least from the standpoint of storing data at run time.

Let the Serialization Begin!

With the object model in place, it's time to turn our attention to the process of translating our objects into XML and back out again to meet our persistence needs. For the final application, we'll need to "create" page objects from XML, whether they're being loaded from the BackPackIt.com servers or from the File System, where we've saved local copies to use when there is no connection to the Internet. Normally when basing objects off of XML provided by an outside party, it's a good idea to make sure that if the external party changes the XML, it doesn't break your application—or at least that such a change is easily dealt with. A good way to do that is to run the external XML through a transform that converts it to a dependable format used internally by your application. This can easily be done via an XML Transform, which can be thought of as a buffer interface designed to help abstract details of the foreign XML away from our application.

Using a transform also provides another benefit: If we transform the incoming XML into the same format used by our application, then we can deserialize objects from BackPack servers and the file system using, effectively, the same functionality. In other words, a single page loaded from the server, once transformed, will look the same to our application as a collection of pages serialized to disk. And speaking of collections, that's where we need to turn our attention back to Generics. If you look at the implementation of the Page class, you'll see that the Notes, Tasks, Tags, and Links are implemented as a Generic Type: SerializableList. That's a custom class that I've created especially for this application. The entire declaration of that type is as follows:

Visual C#

[XmlType("{T}s")]
public class SerializableList<T> : List<T> { }    

Visual Basic

<XmlType("{T}s")> _
Public Class SerializableList(Of T)
    Inherits List(Of T)
End Class

Not a lot of code, is there? That's because a SerializableList is just a class that derives from the System.Collections.Generic.List class (a container for Generics) that ships with the .NET Framework 2.0. Under the covers it behaves the exact same way as a List object, but there's one subtle difference: this custom class has an XML Serialization attribute that describes the type of information that will be serialized. That's what the [XMLType("{T}s"] denotes, where the {T} is a token used as a placeholder for the type of object held in the collection. Here's a conceptual view of how it would serialize in the wild:

<{T}s>
    <TypeName>data</TypeName>
    <TypeName>data</TypeName>
</{T}s>

Where the type of the object contained would be output as a parent element, denoted by the {T} token, and then subsequent child elements would be serialized as needed. So, if the SerializableList contained something simple, like a string (SerializableList<string>), the XML tags would look like:

<strings>
    <string>one</string>
    <string>two</string>
    <string>etc.</string>
</strings>

See? Simple. Complex objects serialize the same way, making Generics a powerful ally in the serialization of collections. The only trick is coming up with an XmlTypeAttribute name that is generic enough to describe whatever is being serialized; that way, one collection object will fit all of your serialization needs. In my case, I've just added an s to the end of the type name itself, and called it good—but you could easily do something like add "list" to the end of yours and that would work equally well.

So, with that bit of information covered, a Page object will then serialize, and any Tasks, Tags, Links, or Notes, will serialize out as lists of the corresponding entities if any data is currently present. Here's an example:

<?xml version="1.0" ?>
<Pages>
<Page>
    <PageIsDirty>false</PageIsDirty>
    <Title>Example Page</Title>
    <Body>This page was created via the BackPack API.</Body>
    <Tasks />
    <Notes>
        <Note>
            <Title>Sample Note</Title>
            <Body>This is the body of a note</Body>
            <Id>279762</Id>
            <Created>2005-09-29 15:08:08</Created>
        </Note>
        <Note>
            <Title>Another Note</Title>
            <Body>More body/sample</Body>
            <Id>279385</Id>
            <Created>2005-09-29 17:05:35</Created>
        </Note>
    </Notes>    
    <Links />
    <Tags />
</Page>

Note how the collection of Note objects serialized as <Notes> (or <{T}s> where the name of the type was a Note), and so on. What's more is that when we go to serialize a collection of Pages, they too serialize the same way—as a <Pages> collection, with corresponding, nested, collections of their constituent data—making everything tidy and easy to handle.

<Pages>
 <Page>
      <PageIsDirty>false</PageIsDirty>
      <Title>Example Page</Title>
      <Body>This page was created via the BackPack API.</Body>
      <Tasks>
        <!-- elided from above -->
   </Tasks>                
      <Links />
      <Tags />
 </Page>
 <Page>
      <PageIsDirty>false</PageIsDirty>
      <Title>Another Page</Title>
      <Body>This page doesn't have any data in it yet—other than title/body.</Body>
      <Tasks />
      <Notes />
      <Links />
      <Tags />
 </Page>
 <Page>
      <PageIsDirty>false</PageIsDirty>
      <Title>And Yet Another Page</Title>
      <Body>Unlike the above page, this one has some data loaded...</Body>
      <Tasks>
     <Task>
            <Text>Get Stuff Done</Text>
            <Id>1347087</Id>
            <Complete>false</Complete>
        </Task>
        <Task>
            <Text>Do more stuff</Text>
            <Id>1347088</Id>
            <Complete>false</Complete>
        </Task>
      </Tasks>
      <Notes />
      <Links />
      <Tags />
 </Page>
</Pages>

Serializing objects is also terribly easy at this point as well. We just need to know the type of object to serialize (in this case a Generic Collection), a location to save the information, and an instance of the type of object to serialize that contains the data we need to serialize. Because we'll be serializing credentials and connection information, as well as pages (and later on even commands to modify data when offline), I've created a helper method as follows:

Visual C#

private void SerializeToFile(Type type, object data, string path, SavedFileType resourceType)
{
    try
    {
        XmlSerializer serializer = new XmlSerializer(type);
        XmlTextWriter tw = new XmlTextWriter(path, Encoding.UTF8);

        tw.Formatting = Formatting.Indented;
        tw.WriteRaw("<?xml version=\"1.0\" ?>");

        XmlSerializerNamespaces ns = new XmlSerializerNamespaces();
        ns.Add(string.Empty, string.Empty);

        serializer.Serialize(tw, data, ns);
        tw.Close();

        this.OnSerializationComplete(new SerializationCompleteEventArgs(resourceType));
    }
    catch // etc.. 
}

Visual Basic

Private Sub SerializeToFile(ByVal type As Type, ByVal data As Object, ByVal path As String, ByVal resourceType As SavedFileType)
Try
    Dim serializer As XmlSerializer = New XmlSerializer(type)
    Dim tw As XmlTextWriter = New XmlTextWriter(path, Encoding.UTF8)
    tw.Formatting = Formatting.Indented
    tw.WriteRaw("<?xml version=""1.0"" ?>")
    Dim ns As XmlSerializerNamespaces = New XmlSerializerNamespaces
    ns.Add(String.Empty, String.Empty)
    serializer.Serialize(tw, data, ns)
    tw.Close()

    Me.UpdateResourceStates(resourceType)

    Me.OnSerializationComplete(
        New SerializationCompleteEventArgs(resourceType))
    Catch ex As Exception
    Throw New NotImplementedException(
        "Need to do a serialization exception..", ex)
    End Try
End Sub

The code is pretty straightforward: it just creates an XmlSerializer instance of the type indicated, and contains a few snippets of code that replace the default XML Serialization namespaces (injected into the serialized XML) with null, or blank, namespaces which keep the serialized XML clean and tidy.

Transforming incoming XML

Now that we've seen what our pages look like once serialized, we can build a quick XSL transform to convert incoming BackPack XML into that same format so that we can deserialize BackPack pages from the server just as easily as those stored locally in our own format. The transform is a simple one, because both the BackPack XML and our own format are very element-heavy, which makes mapping really just a question of changing names from the incoming document to match the names of our objects.

<?xml version="1.0"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="xml" />
<xsl:template match="/">
    <Page>
        <PageIsDirty>false</PageIsDirty>
        <Title><xsl:value-of select="response/page/@title" /></Title>
        <Body><xsl:value-of select="response/page/description" /></Body>
        <xsl:if test="count(response/page/items/*) > 0">
        <Tasks>
            <xsl:apply-templates select="response/page/items" />
        </Tasks>
        </xsl:if>
        <xsl:if test="count(response/page/notes) > 0">
        <Notes>
            <xsl:apply-templates select="response/page/notes" />
        </Notes>
        </xsl:if>
        <xsl:if test="count(response/page/links) > 0">
        <Links>
            <xsl:apply-templates select="response/page/links" />
        </Links>
        </xsl:if>
        <xsl:if test="count(response/page/tags) > 0">
        <Tags>
            <xsl:apply-templates select="response/page/tags" />
        </Tags>
        </xsl:if>
    </Page>    
</xsl:template>
<xsl:template match="item">
    <Task>
        <Text><xsl:value-of select="." /></Text>
        <Id><xsl:value-of select="./@id" /></Id>
        <Complete><xsl:value-of select="./@completed" /></Complete>
 </Task>
</xsl:template>
<!-- elided for brevity (see sample code for more info) -- >
</xsl:stylesheet>

I'm also a bit of a *cough* clean freak, so I've added a bit of logic to make sure that empty elements arriving from the server aren't included in our transformed XML—but that's a total waste of energy and cycles in case anyone was wondering (but serves as a simple example of how that could be done if you wanted your XML more human-readable).

As for performing the transform, that will be done in memory as pages arrive from the server, as demonstrated by the following code:

Visual C#

private void SinglePageReturned(string pageData)
{
    // TODO: add try/catch etc

    byte[] data = Encoding.UTF8.GetBytes(pageData);
    MemoryStream stream = new MemoryStream(data);
    XPathDocument input = new XPathDocument(stream);

    XslCompiledTransform xsl = new XslCompiledTransform();
    XmlNode stylesheet = this.LoadTransformDocument();
    xsl.Load(stylesheet);

    MemoryStream ms = new MemoryStream();
    StreamWriter sw = new StreamWriter(ms);

    xsl.Transform(input, null, sw);

    XmlDocument page = new XmlDocument();
    byte[] bytes = ms.ToArray();
    string transformedXml = Encoding.UTF8.GetString(bytes);
    page.LoadXml(transformedXml);
    sw.Dispose();
    ms.Close();
    ms.Dispose();

    XmlNode node = page.SelectSingleNode("/");
    Page output = this.GetPageFromXml(node);

    this.AddPage(output);
}

Visual Basic

Private Sub SinglePageReturned(ByVal pageData As String)
        ' TODO: add try/catch etc
        Dim data() As Byte = Encoding.UTF8.GetBytes(pageData)
        Dim stream As MemoryStream = New MemoryStream(data)
        Dim input As XPathDocument = New XPathDocument(stream)
        Dim xsl As XslCompiledTransform = New XslCompiledTransform
        Dim stylesheet As XmlNode = Me.LoadTransformDocument
        xsl.Load(stylesheet)
        Dim ms As MemoryStream = New MemoryStream
        Dim sw As StreamWriter = New StreamWriter(ms)
        xsl.Transform(input, Nothing, sw)
        Dim page As XmlDocument = New XmlDocument
        Dim bytes() As Byte = ms.ToArray
        Dim transformedXml As String = Encoding.UTF8.GetString(bytes)
        page.LoadXml(transformedXml)
        sw.Dispose()
        ms.Close()
        ms.Dispose()
        Dim node As XmlNode = page.SelectSingleNode("/")
        Dim output As Page = Me.GetPageFromXml(node)
        Me.AddPage(output)
End Sub

Note the helper method there that grabs the XSL file: LoadTransformDocument(). I've added that method as a helper to abstract the method used for grabbing the transform document listed above. In this sample application I'm grabbing that XSL document from the assembly itself. I did that ONLY to show that it can be done—which is a handy trick if you want to be able to load XSL transforms completely in memory and not require them to be dependent upon satellite files, etc. But in our case it doesn't really make the most sense as we're partially using the XSL document to shield us against changes to the incoming XML—meaning that if 37Signals ever changed their XML format, we'd have to build a new transform, and then recompile our application to get the XSL document back into the Assembly's Resource Stream for further, continued, use in our application. So, with the caveat that I only did it this way to model how to pull XML documents out of your assembly, here's the code that fetches the XSL document:

Visual C#

private XmlNode LoadTransformDocument()
{
    if (this._stylesheetNode == null)
    {
        // pull back the xslt document from the manifest:
        Assembly current = Assembly.GetExecutingAssembly();
        XmlDocument doc = new XmlDocument();

        using (StreamReader sr = new StreamReader(current.GetManifestResourceStream(this.GetType(), "transform.xsl")))
            doc.Load(sr);

        XmlNode output = doc.SelectSingleNode(".");
        this._stylesheetNode = output;
    }
    return this._stylesheetNode;
}

Visual Basic

Private Function LoadTransformDocument() As XmlNode
    If (Me._stylesheetNode Is Nothing) Then
    ' pull back the xslt document from the manifest:
    Dim current As Assembly = Assembly.GetExecutingAssembly
    Dim doc As XmlDocument = New XmlDocument
    Dim sr As StreamReader = 
        New StreamReader(current.GetManifestResourceStream(
        Me.GetType, "transform.xsl"))
    doc.Load(sr)
    Dim output As XmlNode = doc.SelectSingleNode(".")
    Me._stylesheetNode = output
    End If
    Return Me._stylesheetNode
End Function

In the final application, it would probably be better to just have this method open up a stream to the Current Directory where the application resides, and pull in a .xsl document—that way if the format ever needed to change, you could just replace the Transform document, and wouldn't need to recompile the app/bits.

Translating Pages into Objects from XML

With the transform built, and with a method to serialize pages to disk, we now just need to focus on pulling pages back from the BackPack server and turning them into objects. Then we can turn our attention to converting pages saved to disk back into objects as well. But, because the XML formats are the same, both operations will end up being quite similar—and are covered by the following two methods (one of which returns a single Page, the other which returns a Collection, or SerializableList, of Pages):

Visual C#

private Page GetPageFromXml(XmlNode input)
{
    XmlSerializer s = new XmlSerializer(typeof(Page));
    Page page = (Page)s.Deserialize(new XmlNodeReader(input));

    return page;
}

Visual Basic

Private Function GetPageFromXml(ByVal input As XmlNode) As Page
Dim s As XmlSerializer = New XmlSerializer(GetType(Page))
Dim page As Page = CType(s.Deserialize(New XmlNodeReader(input)), Page)
Return page
End Function

Visual C#

private SerializableList<Page> GetPagesFromXml(XmlNode input)
{
    XmlSerializer s = new XmlSerializer(typeof(SerializableList<Page>));
    SerializableList<Page> list =
        (SerializableList<Page>)s.Deserialize(new XmlNodeReader(input));

    return list;
}

Visual Basic

Private Function GetPagesFromXml(ByVal input As XmlNode) As
   SerializableList(Of Page)
    Dim s As XmlSerializer = New XmlSerializer(GetType(
    SerializableList(Of Page)))
    Dim list As SerializableList(Of Page) = CType(s.Deserialize(
        New XmlNodeReader(input)), SerializableList(Of Page))
    Return list
End Function

Because the XML representing a BackPack page has been translated to the very format output by our serialized objects, hydration is a quick and simple operation. And, because our Generic SerializableList has an XML Serialization attribute that lets it morph element names based upon the type of object collection being serialized, all of our nested objects line up perfectly and can therefore be hydrated and dehydrated as needed.

Loading Pages - Without Freezing the User Interface

Many of the key components of the final application are now complete. We have a connection mechanism, created in the first article, that allows us to fetch XML from the BackPackIt.com servers, and we now have a mechanism in place that can turn XML into objects that can be used in our application. We also now have the ability to store those objects as a collection of Pages on disk for use offline. All we really need at this point is to wire up existing functionality from the last article to request pages from the server so that they can be turned into objects that can be used by our application. We'll also need a user interface that will allow us to specify credentials, and direct operations—such as loading pages from the server (or from the file) as well as being able to save the pages to disk.

In building the user interface, one thing we'll want to ensure is that we don't allow long-running interactions with the file system or remote servers to stall, or freeze the UI. To accomplish that, we'll need to implement those interactions asynchronously which will prevent locking the UI thread, and will avoid the possibility of collisions, or race conditions, from happening with data returned from either the remote server or the file system. Concurrent with our use of asynchronously invoking long running methods, we'll make use of events to "announce" the arrival of new pieces of data, and then handle binding that data to the user interface as needed. This will allow the Winform to be responsive while individual pages are being loaded from either the server or file system, and will further serve as the framework for the modification-oriented operations that we'll be working on in the next article.

Asynchronous Architecture

To keep the application responsive, the user interface will route user requests into the business logic layer (the PageManager object), where an asynchronous delegate will be used to perform the actual operation requested—leaving the UI thread free to stay focused on user interaction. Once the requested operation completes, it will raise in the PageManager a RemoteMethodComplete event that will then be bubbled up and handled by the Winform. Handler logic associated with each event type will let the Winform process incoming information as needed, and the actual details of the operation itself (such an individual page) will be passed along in the event as part of a corresponding EventArgs class accompanying each event. This will ensure that the state, or data, associated with the completion of each operation doesn't run the risk of getting overwritten by another operation completing concurrently (which was the case in the first example where I used a member variable to handle state data returned by the logging delegate).

The actual invocation of any of the methods needed to request data from the BackPack servers will be routed through a helper method in the PageManager that bundles up any needed XML, and the corresponding XML and places it implicitly on its own thread by "scheduling" the operation for completion by invoking it asynchronously on a delegate signature bound to the Connection object:

Visual C#

private void InvokeRemoteOperation(string url, XmlElement[] args)
{
    if (this._gateway.ConnectionInfo.IsOnline)
    {
        AsyncRemoteOperation operation = new AsyncRemoteOperation(this._gateway.ExecuteWebMethod);
        operation.BeginInvoke(url, args, null, null);
    }
    else
        // covered in part III
}

Visual Basic

Private Overloads Sub InvokeRemoteOperation(ByVal url As String, 
    ByValargs() As XmlElement)

    If Me._gateway.ConnectionInfo.IsOnline Then
        Dim operation As AsyncRemoteOperation = 
            New AsyncRemoteOperation(
            AddressOf Me._gateway.ExecuteWebMethod)
        operation.BeginInvoke(url, args, Nothing, Nothing)
    Else
        ' covered in part III
    End If
End Sub

Note too, that since this helper method serves to route all commands, it's the perfect place to either route the commands to the BackPack servers, or store the commands for later execution—which will be covered in the next article. As with the example from the last article, XML data is generated as needed, and passed in as an XmlElement array of args that will be fired against the appropriate URL. But in the last article, the Winform was responsible for bundling up that data and preparing it. Logically, such interaction should be handled transparently by the Winform via the PageManager class, which should know about how to handle the details of bundling XML and locating the correct URL, so that's how we'll do it in this article—by letting the PageManager handle all of those details. Once the XML is generated, and the URL is built, the PageManager routes the request into the InvokeRemoteOperation() method which asynchronously routes the commands into a BackPackGateway object—a slight modification of the BackPackRequest class used in the previous article. The BackPackGateway object handles the connection details, transfers data as needed, and once complete, raises an event which is then handled by the PageManager which can evaluate the type of event raised, and determine what to do with the information returned:

Visual C#

public void GatewayResponded(object sender, RemoteMethodCompleteEventArgs e)
{
    if (e.OperationStatus == CompletionStatus.Fail)
    {
        throw new BackPackServerException("Asynchronous BackPack Method Failed.", e.Exception);
    }
    // later: we'll parse the returned info much more fully, and handle it as
    //  appropriate - for now we just need to know if it was a single page, or a
    //  list of all the pages:
    if (e.MethodUrl == "/ws/pages/all")
    {
        this.PagesListed(e.ResponseText);
    }
    else // it's an individual page
    {
        this.SinglePageReturned(e.ResponseText);
    }
}

Visual Basic

Public Sub GatewayResponded(ByVal sender As Object, 
    ByVal e As RemoteMethodCompleteEventArgs)
    If (e.OperationStatus = CompletionStatus.Fail) Then
        Throw New BackPackServerException(
        "Asynchronous BackPack Method Failed.", e.Exception)
    End If
    ' later: we'll parse the returned info much more fully, and handle it 
    ''as appropriate - for now we just need to know if it was a single 
    page, 'or a list of all the pages:
    If (e.MethodUrl = "/ws/pages/all") Then
        Me.PagesListed(e.ResponseText)
    Else
        Me.SinglePageReturned(e.ResponseText)
    End If
End Sub

When the PageManager detects a list of pages being returned, it knows that those pages need to be loaded, and will therefore proceed to request each page in the collection on the current background thread. A URL is therefore built to handle the request, and routed into the BackPackGateway object, which will again bundle the request with user credentials, route the request to the appropriate URL on the BackPack server, process the response, and bundle the results into a corresponding RemoteMethodCompletedEventArgs class which will be bubbled up to the PageManager via the RemoteMethodCompleted Event. The PageManager will then again handle the event in the GatewayResonded handler—only this time it will see that an individual page has been returned. The data from the event, XML representing the page, will be routed into a method that will transform the XML into our own persistence format, which will then translate the resultant XML into a full-blown Page object. Once the page is fully hydrated, the PageManager, in turn, will add the page to its own internal collection of Pages, and will then bundle the page into a PageAddedEventArgs class, and announce the arrival of the new page to the Winform via the PageAdded event. The Winform, which has been sitting around waiting for user input (or notification from back end processes), will handle the PageAdded event and will, in this article, respond by binding the Page's title to the TreeView control used to represent our Page objects:

(click image to zoom)

In this way, the actions required to load the pages take place transparently under the covers, and the pages just appear in the UI once they are fully loaded and announced to the Winform by backend logic and processing. Once the pages are fully loaded from the server, the UI will toggle a Pages Menu Item command that will let us save pages to disk—which can be accomplished by simply sending the PageManager's internal collection of Page objects to the serialization helper method that we created earlier (SerializeToFile()).

Once the pages are saved to disk, they can then be loaded from disk, in much the same way as they are loaded from the server: an asynchronous delegate will open up a stream to the persisted XML, and will then hand that off to the GetPagesFromXml() helper method, which will return a SerializableList of Pages. This Generic Collection of Pages can then be assigned to the PageManager's internal collection of Pages, and each page can be announced to the Winform by bundling it up in a PageAddedEventArg and bubbling it up to the Winform via the PageAdded event such that it can then be bound to the Winform's TreeView control in the same manner as individual pages were bound as they arrived from the BackPack server.

Wrapping it all up

We're now, effectively, feature-complete for this article: we have the ability to 1) load pages from the server, 2) save them to disk, and then 3) reload them from disk. To the application, specifically the Winform, there's really no difference between pages loaded from the server and those loaded from disk—they're just objects which were once expressed as XML. In the next article we'll look at interacting with those objects, and marshalling changes made to them back and forth between our application and the BackPack servers. If the application is offline, then the commands to modify the data will be persisted locally as XML which can be re-hydrated and sent to the server once the application regains an Internet connection. Once the modification against the server is complete, an event will be raised by the BackPackGateway, processed by the PageManager, and announced to the Winform as needed—be it a success or a failure.

Now, if you've made it this far, there's some homework: go take a look at the sample code. Note that the helper method used to serialize pages to disk has also been used for serializing credentials, which can now be serialized to disk as well—making it so that you don't need to keep pasting in the API Key each time you fire off the application for testing and debugging. Check out the event model, and how it allows us to keep data channels clear, and free from potential collisions, or race conditions that would otherwise occur if we were using shared variables between multiple, concurrent threads. Then take the application for a test ride, and watch how responsive it is as long-running applications take place in the background—something that will be a key consideration when we change data in the next article: the data will be flagged as changed locally, and once completed/committed on the server, an event will be raised locally which will un-flag a particular data point as being dirty. And the cool thing? This will happen whether we're online or offline, making it possible for us visually to keep an eye on nodes that have been altered while our BackPack is offline.

In the "old days" there was a debate that raged between Palm and Windows CE zealots. The focus of the debate was a question of whether Palm, with its simple OS and simple functionality, was better suited to meeting users needs, or whether Windows CE, with all of its complex functionality, provided a better option. In simplest terms, the argument was really a question of which was more. Was more more, or was less more? I was always of the impression that more was more—at least in that debate.

But sometimes less can definitely be more. Enter a small company made up of five individuals that understands this very well: 37 Signals. They've successfully launched three VERY SIMPLE online applications that have made them nearly legendary in the web development community. The secret of their success: carefully targeted applications that leverage cutting-edge technology to make collaboration intuitive through absurdly clean and simple user interfaces that anyone can quickly and easily use. Couple those strengths with a "first hit is free" marketing model to compel users to upgrade to paid services for improved productivity, and it's not hard to see why they've done so well.

Glad you like the 37 Signals Kool-Aid, but I thought this was an article about XML?

One of the great things about XML is that it is close to becoming ubiquitous. It really is becoming the lingua franca of data transfer. (There's still an inordinate amount of delimited, flat-file, legacy, evil out there in the corporate universe, though.) 37 Signals obviously appreciates the inherent benefits of XML as a data exchange mechanism, and has therefore provided an easy-to-use API that allows users to interact with one of their core products: BackPack.

BackPack is definitely a "less is more" application. It can be used solely by individuals, but it truly shines when used by small groups for effective collaboration. The best way to summarize it is to think of it in terms of being a terribly streamlined wiki—one that's so easy to use that even pointy-haired bosses would feel at home slicing and dicing with it. It's successful because it really doesn't need much in the way of explanation; the user interface nimbly guides users along to being able to quickly and deftly master the product—all without realizing that they've strayed into something as geeky as a wiki because the user interface does such a great job of shielding the user from all of the underlying complexity. And in many ways, that same simplicity is carried over very well into the XML API.

XML4Fun and the BackPack API

So, over the next three articles we're going to take a look at the BackPack API and put it to use for our own amusement. In the first article we'll quickly cover how to set up a free BackPack account, grab the XML Token needed to interact with the BackPack web service, and delve into connecting to the server to send commands and data back and forth. We'll do this by building a very rough and tumble Windows Forms application that models all of the available operations for just the BackPack page object. In the next two articles we'll quickly flesh out the rest of the API, improve the UI for our application, and then play around with XML serialization and other goodness to make our BackPack portable—in the sense that we'll pimp out the sample app for use when we're offline by making it capable of caching data and queuing changes/commands.

Creating an account

In order to play around with the API, you'll need to set up an account. Basic accounts are free and easy to set up. Once you register for your free account, you'll want to zip into your account details and grab your service token—a SHA1 security token that identifies you to the BackPack Service. Your service token is found at the bottom of your account page:

The API

The API is well documented with excellent examples on the BackPack site. The introduction to the API defines the interchange requirements (more on those in a second), and presents a bevy of examples showing both the posted data, and the corresponding response. It's an API that teaches through examples—and one that doesn't cut corners, which is usually quite rare.

The thing I just love about this API is the sheer simplicity of it. It reminds me of what I like to call the poor man's web service (web services too old or too poor to use SOAP). Lots of these "services" existed back in the day before SOAP became all the rage, and they were almost invariably just clients and servers shooting XML packages back and forth to each other. Only those "'services" were usually horribly documented, and hacked together with franken-logic that made them hard to understand. The BackPack API, on the other hand, is very cut-and-dried and logically constrained. Small XML packages are sent up to logically defined URLs on the server for each "method," and packets of XML "data" are sent back down for consumption.

Creating a Communication Mechanism

Once you've had a moment to scroll through the API documentation and get a good feel for it, it's time to address the creation of a communication mechanism between our client and the BackPack Service. Fortunately, .NET makes this kind of interaction brutally simple by providing the System.Net.HttpWebRequest, and corresponding System.Net.HttpWebResponse objects. All we need to do is add a bit of "decoration" to a standard POST screen-scrape, and we be flipping XML back and forth in no time.

The BackPack API specifies that we need to include a custom request header: X-POST_DATA_FORMAT (set to the value of "xml") in order to have our requests properly identified on the server. For good measure I also always like to specify the MIME Type wherever possible, which I've done as well:

Visual C#

HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
request.Method = "POST";
request.Headers.Add("X-POST_DATA_FORMAT", "xml");
request.ContentType = "application/xml";

// won't work: needs to be encoded:
request.ContentLength = xml.Length;
StreamWriter post = new StreamWriter(request.GetRequestStream());
post.Write(xml);
post.Close();

HttpWebResponse response = (HttpWebResponse)request.GetResponse();

StreamReader responseBody = new StreamReader(response.GetResponseStream());
string responseInfo = responseBody.ReadToEnd();
responseBody.Close();

Visual Basic


Dim request As HttpWebRequest = CType(WebRequest.Create(url), HttpWebRequest)

request.Method = "POST"
request.Headers.Add("X-POST_DATA_FORMAT", "xml")
request.ContentType = "application/xml"

' won't work: needs to be encoded:
request.ContentLength = xml.Length
Dim post As StreamWriter = New StreamWriter(request.GetRequestStream())
post.Write(xml)
post.Close()

Dim response As HttpWebResponse = CType(request.GetResponse(), HttpWebResponse)

Dim responseBody As StreamReader = New 
    StreamReader(response.GetResponseStream())
Dim responseInfo As String = responseBody.ReadToEnd()
responseBody.Close()

And that's about it. An HttpWebRequest abstracts away all the gory socket details, and the response, if everything works out correctly, is returned to a simple string that can easily be consumed as needed.

Building an Application to Interact with the API

Once we've got a suitable chunk of communication code, we can build an application around it. I'm using Visual C# Express, which makes creating and laying out form controls very simple. Since stubbing out code for an API usually involves lots of semi-repetitive copy/paste/tweak activities, typos are probably going to abound. That, and just to make this sample application cooler, I'm going to provide a simple way to view the XML sent up as well as the XML sent back down. Real estate for that will cover a large section of the sample app. Not only will this will help make debugging easier, it will provide a window on what is taking place from an XML standpoint as the gears churn inside our app.

In this first article we'll only be covering Page operations (we'll cover Notes, Tags, Reminders, etc. in the next article), but I'll still need a way to display a running list of pages from which we can pick targets to update, delete, display, etc. So we'll need a list box to house a list of available pages, and another section of the Winform dedicated to implementing the Page operations outlined by the API. Finally, we'll need a way to specify which account to connect to, along with a way to provide our API Key for inclusion during requests.

(click image to zoom)

As you can see, the choice of which API method to invoke is controlled through a simple radio button—with the exception of the List All method—which is bound to the Load Pages button (which makes more sense). A couple of text boxes and a check box are then laid off to the side of the radio buttons for use in collecting user input, and fields are toggled on and off as needed, depending upon which radio button is selected. (Something tells me that 37 Signals' UI is a tad better than mine.)

Constructing the XML

Of course, pushing buttons, no matter how elegantly (or horribly) laid out on a Winform, doesn't do much for an application that needs to communicate with a server in XML. Again, because of how simple the API is, and because the XML is also very simple, using the XML Document Object Model (DOM) is the perfect choice to generate suitable XML to translate user input where needed.

Working with the DOM is quite fun when it comes to generating new XML. The basic idea is that with an XML Document loaded (even a blank one) you can "float" new XML Elements (or other nodes, e.g. comments, attributes, etc.) off of the root of the document, meddle with the node's internal data, and then append that node to a selected location somewhere specific within the document. If you've done this before, it's second nature; but learning how it all takes place can be a bit of a mind-bender for many people. Within the .NET Framework, the DOM is abstracted into the System.Xml.XmlDocument object, which provides all of the needed functionality to create new elements, populate them with content, and then to arrange them as desired.

For example, to create a new page, the API indicates that we need to have two child elements (title and description), nested into the page element. The following code shows how a blank XmlDocument instance is used to create three new elements programmatically. When these elements are created, they're out in limbo—just sticking off of the XmlDocument like hideous extraneous appendages. It's not until they are ordered and arranged that they take the shape that we want:

Visual C#

XmlDocument args = new XmlDocument();
XmlElement page = args.CreateElement("page");
XmlElement title = args.CreateElement("title");
title.InnerText = this.txtPageTitle.Text.Trim();
XmlElement description = args.CreateElement("description");
description.InnerText = this.txtPageBody.Text.Trim();

page.AppendChild(title);
page.AppendChild(description);

Visual Basic

Dim args As XmlDocument = New XmlDocument()
Dim page As XmlElement = args.CreateElement("page")
Dim title As XmlElement = args.CreateElement("title")
title.InnerText = Me.txtPageTitle.Text.Trim()
Dim description As XmlElement = args.CreateElement("description")
description.InnerText = Me.txtPageBody.Text.Trim()

page.AppendChild(title)
page.AppendChild(description)

Pretty simple, isn't it? With that little bit of code we've created the XML necessary for interaction with the API.

Herding Ducks—or How to Wrap an API

With connectivity and XML manipulation logic in place, as well as a Winform to handle user input and interaction, it's time to figure out the best way to wrap the BackPack API. Any time you wrap an API, you are invariably embedding oodles of logic into your code, and one of the key goals is to do so without repetition—which makes code harder to maintain. The other goal is to make sure that you don't end up making your logic too aware of itself to the point where code in region x KNOWS how code in section y should behave, and comes to rely upon that anticipated behavior. Making that mistake is the sin of poor coupling, and can result in shame, ruin, and discredit to you and your children's children's children.

One of the key things I wanted to accomplish in my effort to wrap the API was to keep as much of the core logic as close together as possible without adding lots of "logic-bloat" around one of the core pieces of the API—manipulation of the URLs that effectively act as the method names. These "method names" needed to be dynamically selected based on the user action, but from there, similarity between the methods effectively breaks down. This is where Delegates come in. Using Delegates allowed me to keep all of the URL-building-goodness localized to one single routine: an event handler for the Submit button. Here all of the URLs could be easily mapped and dynamically created (if needed), and comparatively complex logic such as building XML-grams of various types of user data could be handled in subsequent "starting point" methods as required.

But Delegates also bring something else to the table. Winforms that spend time communicating with various off-box server endpoints are subject to "freezing up" while communication is underway unless a background thread is directed to handle the communication—leaving the main Winform thread free to handle UI tasks. Using Delegates allows for a clean and easy way to spawn new background threads that can handle implementation details such as gathering user input, bundling it up, and then invoking the proper web method—all while leaving the Winform's main thread open to handle the message pump and UI tasks. Here's a code snippet of the entire event handler for the Submit button, where the URL is constructed as needed, a Delegate is wired up with the correct handling routine, and a thread is started to handle the communication:

Visual C#

private void button2_Click(object sender, EventArgs e)
{
    // everything except for creating a new page requires a pageID:
    if (this._currentOperation != PageOperation.Create)
    {
        if (this._currentPageId == 0)
        {
            MessageBox.Show("Please Select a Page First.");
            return;
        }
    }

    // specify the path to connect to on the backpack server, and call appropriate methods
    //
        to load xml 'args' as needed:
    OperationDelegate operation = null;
    switch (this._currentOperation)
    {
        //case PageOperation.ListAll:
        //    break;
        case PageOperation.Create:
            this._webMethodPath = "/ws/pages/new";
            operation = new OperationDelegate(this.InvokeCreatePage);
            break;
        case PageOperation.Show:
            this._webMethodPath = string.Format("/ws/page/{0}/show", 
                this._currentPageId.ToString());
            operation = new OperationDelegate(this.InvokeSimpleMethod);
            break;
        case PageOperation.Destroy:
            this._webMethodPath = string.Format("/ws/page/{0}/destroy", 
                this._currentPageId.ToString());
            operation = new OperationDelegate(this.InvokeSimpleMethod);
            break;

    // elided for brevity... 
    
        case PageOperation.Email:
            this._webMethodPath = string.Format("/ws/page/{0}/email", 
                this._currentPageId.ToString());
            operation = new OperationDelegate(this.InvokeSimpleMethod);
            break;
        default:
            MessageBox.Show("Woops.");
            break;
    }

    if (operation != null)
    {
        Thread operationHandler = new Thread(new ThreadStart(operation));
        operationHandler.IsBackground = true;
        operationHandler.Start();
    }
}

Visual Basic

Private Sub Button2_Click(ByVal sender As System.Object, 
    ByVal e As System.EventArgs) Handles Button2.Click
    If Me._request Is Nothing Then
        MessageBox.Show("Please enter your credentials first.")
        Return
    End If

    If Me._currentOperation <> PageOperation.Create Then
        If Me._currentPageId = 0 Then
            MessageBox.Show("Please Select a Page First.")
            Return
        End If
    End If


    ' specify the path to connect to on the backpack server, and call 
    'appropriate methods
    'to load xml 'args' as needed:

    ' vb.net doesn't play nicely with delegates... so the vb.net version 
    'will create a different threadstart in each
    '   case:
    Dim ts As ThreadStart = Nothing
    Select Case Me._currentOperation
        'case PageOperation.ListAll:
        '    break;
        Case PageOperation.Create
            Me._webMethodPath = "/ws/pages/new"
            ts = New ThreadStart(AddressOf Me.InvokeCreatePage)
        Case PageOperation.Show
            Me._webMethodPath = String.Format("/ws/page/{0}/show", 
                Me._currentPageId.ToString())
            ts = New ThreadStart(AddressOf Me.InvokeSimpleMethod)
        Case PageOperation.Destroy
                Me._webMethodPath = String.Format("/ws/page/{0}/destroy",
                    Me._currentPageId.ToString())
                ts = New ThreadStart(AddressOf Me.InvokeSimpleMethod)
        Case PageOperation.UpdateTitle
                Me._webMethodPath = 
                    String.Format("/ws/page/{0}/update_title", 
                    Me._currentPageId.ToString())
                ts = New ThreadStart(AddressOf Me.InvokeUpdateTitle)
        Case PageOperation.UpdateDescription
                Me._webMethodPath = 
                    String.Format("/ws/page/{0}/update_body", 
                    Me._currentPageId.ToString())
                ts = New ThreadStart(AddressOf Me.InvokeUpdateDescription)
        Case PageOperation.Duplicate
            Me._webMethodPath = String.Format("/ws/page/{0}/duplicate", 
                Me._currentPageId.ToString())
            ts = New ThreadStart(AddressOf Me.InvokeSimpleMethod)
        Case PageOperation.Link
            Me._webMethodPath = String.Format("/ws/page/{0}/link", 
                Me._currentPageId.ToString())
            ts = New ThreadStart(AddressOf Me.InvokePageLinkManagment)
        Case PageOperation.Unlink
            Me._webMethodPath = String.Format("/ws/page/{0}/unlink", 
                Me._currentPageId.ToString())
            ts = New ThreadStart(AddressOf Me.InvokePageLinkManagment)
        Case PageOperation.Share
            Me._webMethodPath = String.Format("/ws/page/{0}/share", 
                Me._currentPageId.ToString())
            ts = New ThreadStart(AddressOf Me.InvokeSharePage)
        Case PageOperation.Unshare
            ' NOTE: Though this doesn't return an error, it doesn't seem 
            'to do ANYTHING in terms of sharing. 
            ' So the API/docs are either in error, or I don't understand 
            'what we're trying to do here (most likely).
            Me._webMethodPath = 
                String.Format("/ws/page/{0}/unshare_friend_page",
                    Me._currentPageId.ToString())
            ts = New ThreadStart(AddressOf Me.InvokeSimpleMethod)
        Case PageOperation.Email
            Me._webMethodPath = String.Format("/ws/page/{0}/email", 
                Me._currentPageId.ToString())
            ts = New ThreadStart(AddressOf Me.InvokeSimpleMethod)
        Case Else
            MessageBox.Show("Woops.")
    End Select

    If (ts <> Nothing) Then
        ' vb doesn't do delegates the same way as the c# code:
        Dim operationHandler As Thread = New Thread(ts)
        operationHandler.IsBackground = True
        operationHandler.Start()
    End If
End Sub

Now, I've managed to keep all of my URLs in one tidy location, without a ton of code crammed into each case, to help improve readability. Instead, Delegates allow the complex logic to be handled in a suitable method that will be started on another thread. For example, the creation of a page, which requires additional XML arguments to be assembled, is handled like so:

Visual C#

private void InvokeCreatePage()
{
    XmlDocument args = new XmlDocument();
    XmlElement page = args.CreateElement("page");
    XmlElement title = args.CreateElement("title");
    title.InnerText = this.txtPageTitle.Text.Trim();
    XmlElement description = args.CreateElement("description");
    description.InnerText = this.txtPageBody.Text.Trim();

    page.AppendChild(title);
    page.AppendChild(description);

    this._request.ExecuteWebMethod(this._webMethodPath, page);
}

Visual Basic


Private Sub InvokeCreatePage()
    If Me.txtPageTitle.Text.Length < 1 Or Me.txtPageBody.Text.Length < 1 
    Then
        MessageBox.Show("Please enter a title and description.")
        Return
    End If

    Dim args As XmlDocument = New XmlDocument()
    Dim page As XmlElement = args.CreateElement("page")
    Dim title As XmlElement = args.CreateElement("title")
    title.InnerText = Me.txtPageTitle.Text.Trim()
    Dim description As XmlElement = args.CreateElement("description")
    description.InnerText = Me.txtPageBody.Text.Trim()

    page.AppendChild(title)
    page.AppendChild(description)

    Me._request.ExecuteWebMethod(Me._webMethodPath, page)
End Sub

API operations that don't require any XML other than the service token are all handled by a catch-all method that just fires off the URL against a helper method:

Visual C#

private void InvokeSimpleMethod()
{
    this._request.ExecuteWebMethod(this._webMethodPath);
}

Visual Basic

Private Sub InvokeSimpleMethod()
    Me._request.ExecuteWebMethod(Me._webMethodPath)
End Sub

Also note: I don't pass the URL and other goodies into these delegated methods, as I need them to be void methods (Subs in VB.NET parlance) that contain no arguments so that their signature matches that of the System.Threading.ThreadStart delegate.

Connection Goodness, Revisited

To avoid scattering connection logic and the API key all throughout the application, I then created a class called a BackPackRequest class to abstract out all of the connection details. Its purpose is to abstract connection details away from the callers and provide a uniform way to ensure that calls to the BackPack service are properly formatted, and all provided with the requisite service token.

Each time user credentials (username and API Key) are entered, or changed in the Winform, a new instance of the BackPackRequest object is created, which requires the account name, API Key, and a logging delegate (more on that in a second) in the constructor. The constructor wires up the base BackPack URL, squirrels away the API key for each subsequent connection request, and offers a handful of overloads to one single point of contact to callers—a method that takes, effectively, a method location URL along with an optional array of XmlElements serving as arguments where needed.

In order to include the service token in each request, a private helper method was created to join the always-required token, wrapped in a request element, with any optional XmlElements representing user input. However, building that chunk of XML required floating elements off of a new, blank XmlDocument owned by the BackPackRequest instance. The optional elements to append would actually be coming from another document—causing a bit of a problem: while you can float new elements on a document and append them as desired, you can't "float" them on to another document. It wouldn't make any sense to have two classes (the Winform and the BackPackRequest instance) share a single XmlDocument in order to create nodes from a common trunk (that would be an unbearable coupling faux pas)—so I had to import the nodes from one document to the other. Again, the Framework makes this quite easy, and as you can see below, the logic to add zero to multiple elements was pretty easy to implement with the use of the XmlDocument's ImportNode() method:

Visual C#

private XmlNode BuildCommand(XmlElement[] args)
{
    XmlDocument command = new XmlDocument();
    XmlElement request = command.CreateElement("request");
    XmlElement token = command.CreateElement("token");

    token.InnerText = this._apiKey;
    request.AppendChild(token);
    command.AppendChild(request);

    if (args != null)
    {
        for (int i = 0; i < args.Length; i++)
        {
            XmlNode arg = command.ImportNode(args[i], true);
            request.AppendChild(arg);
        }
    }

    return command.SelectSingleNode("/"); // root
}

Visual Basic

Private Function BuildCommand(ByVal args() As XmlElement) As XmlNode

    Dim command As XmlDocument = New XmlDocument()
    Dim request As XmlElement = command.CreateElement("request")
    Dim token As XmlElement = command.CreateElement("token")

    token.InnerText = Me._apiKey
    request.AppendChild(token)
    command.AppendChild(request)

    If Not args Is Nothing Then
        Dim i As Integer
        For i = 0 To args.Length - 1 Step i + 1
            Dim arg As XmlNode = command.ImportNode(args(i), True)
            request.AppendChild(arg)
        Next
    End If

    Return command.SelectSingleNode("/") ' root
End Function

Note that in the above code, I'm making a deep copy of the nodes that are being imported (the second argument of ImportNode() is set to true). A shallow copy would only have served to import the element in name only—without the inner data.

Logging XML Interaction Details

The only big thing left at this point was to wire up logging functionality in the Winform. Each invocation of the delegate by the BackPackRequest instance sends information back to the Winform without the request really even knowing or caring what it is doing—which is why Delegates are such powerful tools, and such great allies in the war on coupling.

To handle the logging needs, and to account for the connectivity functionality mentioned above, the initial connection logic introduced early ended up being augmented into a full-blown method, which gets executed asynchronously as follows:

Visual C#

internal string ExecuteWebMethod(string methodLocation, XmlElement[] args)
{
    try
    {
        string url = this._url + methodLocation;
        XmlNode xmlCommandNode = this.BuildCommand(args);

        string xml = xmlCommandNode.InnerXml;
        this._screenWriter(" ");
        this._screenWriter("Send: (" + url + ")" + System.Environment.NewLine + xml);
        HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);

        request.Method = "POST";
        // ... 
        // elided - (this is the exact same connection code as listed initially)
        // ...    
        responseBody.Close();

        this._screenWriter("Response:" + System.Environment.NewLine + responseInfo);
        return responseInfo;
    }
    catch (Exception ex)
    {
        this._screenWriter("EXCEPTION: " + ex.ToString());
        return null;
    }
}

Visual Basic

Friend Function ExecuteWebMethod(ByVal methodLocation As String, 
    ByVal args() As XmlElement) As String
    Try
        Dim url As String = Me._url + methodLocation
        Dim xmlCommandNode As XmlNode = Me.BuildCommand(args)

        ' if (isOnline)
        ' otherwise, append the two args into a single element, and 
        ' append it to another thingy.

        Dim xml As String = xmlCommandNode.InnerXml
        Me._screenWriter(" ")
        Me._screenWriter("Send: (" + url + ")" + 
            System.Environment.NewLine + xml)
        Dim request As HttpWebRequest = CType(WebRequest.Create(url), 
            HttpWebRequest)

        request.Method = "POST"
        request.Headers.Add("X-POST_DATA_FORMAT", "xml")
        request.ContentType = "application/xml"

        ' won't work: needs to be encoded:
        request.ContentLength = xml.Length
        Dim post As StreamWriter = 
            New StreamWriter(request.GetRequestStream())
        post.Write(xml)
        post.Close()

        Dim response As HttpWebResponse = CType(request.GetResponse(), 
            HttpWebResponse)

        Dim responseBody As StreamReader = 
            New StreamReader(response.GetResponseStream())
        Dim responseInfo As String = responseBody.ReadToEnd()
        responseBody.Close()

        Me._screenWriter("Response:" + System.Environment.NewLine + 
            responseInfo)
        Return responseInfo
        Catch ex As Exception
            Me._screenWriter("EXCEPTION: " + ex.ToString())
            Return Nothing
    End Try
End Function

Only, there's an issue with that code: a background thread will be executing the code above, and the point of logging is to write the info written to the txtLog TextBox on our Winform. Winforms, however, get exceptionally cranky (literally) about a background thread touching their user controls (only the UI thread or owner of the controls can touch them). To account for this, we need to direct the delegate at a simple method that will store the log information in a local variable and then inform the UI thread that there's some new information to log to the screen:

Visual C#

private void OnLogged(string info)
{
    this._logMessage = info;
    this.BeginInvoke(new MethodInvoker(this.BindLogMessage));
}

Visual Basic

Private Sub OnLogged(ByVal info As String)
    Me._logMessage = info
    Me.BeginInvoke(New MethodInvoker(AddressOf Me.BindLogMessage))
End Sub

And when it comes time to paint the logged information to the screen, we need a way of "scrolling" the contents in the textbox so that the latest results are output as they are received. I accomplished this by capturing the control that currently has focus, stealing the focus and directing it to the txtLog TextBox, outputting the text, scrolling the text box to the end of its contents, and then returning control back to the control that should truly have it:

Visual C#

private void BindLogMessage()
{
    // probably should pay attention to race conditions/locking/etc.
    this.txtLog.Text += System.Environment.NewLine + this._logMessage;

    // handle jiggling, focus stealing, output scrolling, voodo:
    Control current = this.ActiveControl;
    this.txtLog.Focus();

    this.txtLog.SelectionStart = this.txtLog.Text.Length;
    this.txtLog.SelectionLength = 0;
    this.txtLog.ScrollToCaret();

    current.Focus();
    Application.DoEvents();
    
}

Visual Basic

Private Sub BindLogMessage()
    ' probably should pay attention to race conditions/locking/etc.
    Me.txtLog.Text += System.Environment.NewLine + Me._logMessage

    ' handle jiggling, focus stealing, output scrolling, voodo:
    Dim current As Control = Me.ActiveControl
    Me.txtLog.Focus()

    Me.txtLog.SelectionStart = Me.txtLog.Text.Length
    Me.txtLog.SelectionLength = 0
    Me.txtLog.ScrollToCaret()

    current.Focus()
    Application.DoEvents()

End Sub

It feels a bit like a hack, but I couldn't think of a better way to do it given the fact that that scrolling requires that the control to be "scrolled" have focus.

Test Driving your BackPack

At this point, we've got a user interface that routes operation choices into a single event handler that determines the correct URL to invoke, assembles any required user input into XML, and then fires it off against the server. It has been a bit of a long road, but Page functionality from the BackPack API is now fully implemented and can be taken for a test drive:

(click image to zoom)

Once you enter your Account Name and API Key details (and leave the Connection Information Group Box), the Winform detects that both fields have been filled out and creates an instance of the BackPackRequest class in the background, so you can then press the Load Pages button to load your pages (if you have any—if not, you can create a page, and then Load Pages). Once your pages are loaded, you can destroy pages, rename them, or link and share them, etc. You can even direct BackPack to email you a copy of your pages—which, for some reason, is very satisfying to my inner geek.

Conclusion—Part I

So, we've taken a look at an XML API, and played around with dynamically generating XML documents using the DOM to build "data grams" from our own crude user interface. We've largely ignored using or consuming the returned XML, with the exception of the Pages List box, which simply iterates through the returned pages nodes and binds them to a Hashtable and to the List Box. Otherwise, the only use we make of the XML returned from the service is to output it to the Winform via the logging functionality.

However, in the next article we'll take a better look at how to usefully and effectively consume the returned XML. In addition to fleshing out the rest of the API, we'll also make our application functional—by making it so that we can grab BackPack data from the web, go offline, make updates and changes in our application, and then marshal those changes back up to the server when we get back online. It should make for a very cool tool once we're done.