Download source code - 1.6 MB

Introduction

In this sixth delivery of my end-to-end BlackBerry application walk-through, I will cover the following topics:

Creating a .NET HTTP Handler to send and receive information from a handheld application
Consuming server-side business logic services from our HTTP Handler
Making requests from a handheld application and receiving data

While the previous articles of this series dealt with creating a Java application that will be installed on the handheld device, today I will be working on the server-side modules. Let’s take another look at our basic building blocks:

The server-side modules consist of a .NET HTTP handler, a set of class libraries that contain the business logic and data access code, and a SQL Server database that will serve as the articles repository of our Knowledge Base application.

Creating the HTTP Handler

The mission of the HTTP Handler is to extract information from the HTTP requests made from the handheld, determine what type of action is required, and ask the business logic layer to execute such actions. It will also append the results produced by the business logic to HTTP responses and send them to the handheld application.

In order for the handheld application and the handler to be able to talk to each other, all the commands that the handheld application can possibly send need to be defined within the handler as they were defined in the handheld:

 // The commands the handheld can send us.
private const int CMD_SEARCH_ARTICLES = 1;
private const int CMD_GET_ARTICLES_BY_TAG = 2;
private const int CMD_GET_TAG_COUNTS = 3;

The keys identifying each of the request parameters need to be defined as well:

// The request keys.
private const string KEY_COMMAND = "cmd";
private const string KEY_SEARCH_PHRASE = "sp";
private const string KEY_TAG = "tg";

KEY_SEARCH_PHRASE identifies the request parameter carrying the search phrase when a request to search the existing articles is made. KEY_TAG identifies the parameter carrying the tag name when the request is to retrieve the articles for a given tag.

Determining what to do is a matter of inspecting the request parameter marked with the KEY_COMMAND key:

string commandString = request.Form[KEY_COMMAND];
if (!int.TryParse(commandString, out currentCommand)) 
{
    // Bail if we don't receive a numeric command.
    return;
}
articlesServer = Shared.GetArticlesServer(context); 
switch (currentCommand)
{
    case CMD_SEARCH_ARTICLES:
        string searchPhrase = request.Params[KEY_SEARCH_PHRASE];
        responseString = SearchArticles(searchPhrase);
        break;
    case CMD_GET_ARTICLES_BY_TAG:
        string tag = request.Params[KEY_TAG];
        responseString = GetArticlesForTag(tag);
        break;
    case CMD_GET_TAG_COUNTS:
        responseString = GetTagCounts();
        break;
    default:
        return;
}

Consuming the Business Logic Services

I won’t go into the details of the construction of the business logic and data access layers today, since they were covered in my End-to-end ExtJS application series. Something noteworthy, though, is the fact that these layers support storage of the articles in a file or in a SQL Server database. The code download for today’s article defaults to file-based storage, but you can run the included SQL script to install the database and point the business layer to it by changing the web application’s configuration file.

In the HTTP Handler, SearchArticles(), GetArticlesForTag(), and GetTagCounts() simply forward the requests to the business logic layer:

private string SearchArticles(string searchPhrase)
{
    Debug.Assert(searchPhrase != null);
    if (null == searchPhrase)
    {
        ExceptionPolicy.HandleException(
                new ArgumentNullException("searchPhrase"), 
                Shared.KB_EXCEPTION_PLCY);
    }
    string result = string.Empty;
    try
    {
        List<IArticle> articles = 
          articlesServer.GetArticlesForSearchPhrase(searchPhrase);
        if (null == articles) return string.Empty;
        result = SerializeArticlesList(articles);
    }
    catch (Exception ex)
    {
        ExceptionPolicy.HandleException(ex, Shared.KB_EXCEPTION_PLCY);
    }
    return result;
}
private string GetArticlesForTag(string tag)
{
    Debug.Assert(tag != null);
    if (null == tag)
    {
        ExceptionPolicy.HandleException(
            new ArgumentNullException("tag"),Shared.KB_EXCEPTION_PLCY);
    }
 
    string result = string.Empty; 
    try
    {
        List<IArticle> articles = articlesServer.GetArticlesForTag(tag);
        if (null == articles) return string.Empty;
        result = SerializeArticlesList(articles);
    }
    catch (Exception ex)
    {
        ExceptionPolicy.HandleException(ex, Shared.KB_EXCEPTION_PLCY);
    }
    return result;
}
private string GetTagCounts()
{
    StringBuilder sb = new StringBuilder(""); 
    try
    {  
        Dictionary<string, int> tagCounts = articlesServer.GetTagCounts();
        if (null != tagCounts && tagCounts.Count > 0)
        {
            foreach (KeyValuePair<string, int> tagStat in tagCounts)
            {
                sb.Append(string.Format("{0}^~^{1}~^~", 
                          tagStat.Key, tagStat.Value));  
            }
        }
    }
    catch (Exception ex)
    {
        ExceptionPolicy.HandleException(ex, Shared.KB_EXCEPTION_PLCY);
    }
    return sb.ToString();
}

After the business logic results are delivered to the handler, I need to serialize the results according to the formatting convention I had established when I wrote the handheld code. For example, this is the routine that converts a list of articles into a string that will be sent to the handheld as part of the HTTP response:

private string SerializeArticlesList(List<IArticle> articles)
{
    Debug.Assert(articles != null);
    if (null == articles)
    {
        ExceptionPolicy.HandleException(
            new ArgumentNullException("articles"), 
                                      Shared.KB_EXCEPTION_PLCY);
    }
    StringBuilder sb = new StringBuilder("");
    string body; 
    foreach (IArticle article in articles)
    {
        // Decode the html characters in the body of the article.
        body = HttpUtility.HtmlDecode(HttpUtility.UrlDecode(article.Body));
        // Strip the html characters
        // (We're using a RichTextField on the handheld,
        // which isn't capable yet of displaying html.
        body = Regex.Replace(body, @"<(.|\n)*?>", string.Empty); 
        sb.Append(string.Format("{0}^~^{1}^~^{2}^~^{3}^~^", 
                  article.Id.ToString(), article.Title, 
                  article.DateCreated.ToShortDateString(), article.Author));
        sb.Append(string.Format("{0}^~^{1}~^~", article.Tags, body));
    }
    return sb.ToString();
}

Did you notice that in the code above I’m also removing the HTML characters from the body of the article? I have to do this because the field I’m using to display the body of the article on the handheld is not capable of rendering HTML.

All that’s left now is to send the data to the handheld:

response.ContentType = "text/plain";
int contentLength = response.Output.Encoding.GetByteCount(responseString);
response.AppendHeader("content-length", contentLength.ToString());
response.Write(responseString);
response.End();

Well, I know the walk through of the server-side code went pretty fast. I encourage you to download the code for and check it out to see all the details. Also, reading the End-to-end ExtJS application post can give you more insight on the business logic and data access layers.

Making Requests from the Handheld Application and Receiving Data

Let’s return to the device-side code and ready it to connect to the HTTP Handler. The first thing I will do is stop using the MockHTTPTransport instance and start using KbHTTPTransport. While MockHTTPTransport simply simulates an HTTP request to allow for testing of all the rendering logic on the device, KbHTTPTransport is the real deal. This is how I use it from the Articles Screen or the Tags Screen:

private void sendHttpRequest(String[] keys, String[] values) {   
   articlesList.set(null);  // Show "No Articles" while we download.
   String url = DataStore.getAppServerUrl();
   // Make sure we can create an http request.
   // If the app. server URL has not been set, we cannot make any http requests.
    if (null == url || url.length() == 0) {
        Dialog.alert(resources.getString(
           KnowledgeBaseResource.ERR_INVALID_APP_SERVER_URL));
        return;
    }

    statusDlg.show();
    byte[] requestContents = TransportUtils.createPostData(keys, values);
    KbHTTPTransport transport = new KbHTTPTransport();
    transport.setHTTPTransportListener(this);
    transport.send(KbHTTPTransport.REQ_METHOD_POST, url, requestContents);
}

At this point, all the pieces are in place, and I’m going to use the BlackBerry simulator and MDS simulator to test the application with real data. After firing up both simulators, I will check the Options Screen and make sure that I’m pointing to the right URL for my HTTP Handler:

Back in the Main Screen, I choose Browse Tags:

And here, I am getting real data from the handler:

Selecting a tag should bring back some articles:

And, selecting an article should display its contents:

Conclusion

I hope you’ve found this series of posts helpful. I think the application is at a reasonable quality level where you can use its blocks as a foundation for your own projects. Although I’ll move on into other topics, I’m willing to come back to work on or talk more about any areas of your interest. Please let me know your thoughts.

History

Here are the links to the previous articles of this series:

End-to-End Real World BlackBerry Application, Part 1
End-to-End Real World BlackBerry Application, Part 2
End-to-End Real World BlackBerry Application, Part 3
End-to-End Real World BlackBerry Application, Part 4
End-to-End Real World BlackBerry Application, Part 5

End-to-End Real World BlackBerry Application, Part 6