Developing IT operations for cloud environment

Lets take a break from developing Virtual Queues in Scala and talk about something else. A while back a friend of mine asked me how an organization should go about handling their IT operations if they decide to move on to the cloud. This got me thinking. Developing a Cloud Operations plan is not an easy task. The challenge is that no two organizations have the exact same operations and so one cannot just follow a standard plan. What this means is that to arrive at a good operations plan on Cloud for a particular organization, one needs a prescriptive process that is generic enough that it could be followed for any organization and helps formulate that particular organization’s cloud operations plan.

I looked for such a process but could not find one. So over a long weekend I took it upon myself to come up with a simple yet comprehensive process that could be followed by any organization/client and in the end will produce a detailed yet tailored Cloud Operations plan taking the Unique IT operations of that organization as well as the capabilities of the cloud provider they have selected into consideration.

In this blog post I am sharing my process to develop IT operations for the cloud environment.

Introduction

With more and more organizations embracing cloud environment as a viable option for their compute, storage and networking needs, it becomes important to address how this new setup will impact the important task of IT operations. Traditionally IT organizations had complete control over all of their IT assets, starting from facilities and bare metal hardware all the way to application software supporting business processes. Cloud environment shifts this paradigm where an IT organization is no longer in complete control of their environment. Regardless of the deployment model of choice (other than a Private Cloud) be it Community Cloud, Hybrid Cloud or a Public Cloud, an organization has to rely on the Cloud Providers offerings to design their IT operations strategy.

A fundamental challenge faced by an organization is the lack of a well defined process to develop such a strategy and plan for its IT operations on the cloud. What makes the task more daunting is the fact that no two organizations have the same IT operations, processes and tasks. So there is no generic strategy that could be blindly adopted.

These challenges make it very important to have a consistently repeatable process that could be followed by any organization that wants to develop a strategy for its IT operations on the cloud. This paper explains one such process. The process is laid out as a series of steps that need to be executed in sequence to arrive at a viable IT operations strategy.

Rest of this paper explains these steps in detail.

STEP 1. Assess current IT operations

The first step towards developing an IT operations strategy for cloud is for an organization to assess its current state of IT operations. Start by identifying all processes performed as part of the current IT operations. A process is simply an activity consisting of related tasks that have a collective aim. In that sense a process can be seen as a collection of tasks. An inventory of all the tasks that forms a process should be documented. This is a very important document and forms the baseline of what needs to be considered when moving the operations to the cloud.

This step can be performed by interviewing the current staff members; it might also help to study what is done in the industry. A book such as Building Operational Excellence, authored by Bruce Allen & Dale Kutnick lists hundreds of processes and their best practices. This book will serve as a good starting point. In interviewing the staff, it will help to share the processes from this book with them and assist them in identifying a process from the industry that closely matches an in-house process. Listing the processes using industry standard terminology will make the discussions with a cloud provider easier. It is imperative to have as comprehensive a list of processes that are moving to the cloud as possible.

For example this table lists a set of processes that a typical organization might have as part of their IT operations. This is by no means a comprehensive list of processes but serves as an example of a typical organization.

• Application optimization • Asset management • Business relationship management • Capacity management • Change management • Configuration management • Contract management • Database administration (Physical) • Disk storage management • Facilities management • Hardware support • Infrastructure planning • Inventory management • Job scheduling • Middleware management • Negotiation management • Network monitoring • Output management • Performance management • Physical database management • Problem management • Production acceptance • Production control • Quality assurance • Security management • Service-level management • Service-level agreement management • Service request management • Software distribution • Software management • Systems monitoring • Tape management • Workload monitoring

Each of these processes is made up of several tasks that are carried by individuals supporting the process. For example, Disk storage management is a process that consists of following tasks:

1. File placement,

2. Archiving,

3. Backup and recovery,

4. Numerous other tasks that often are performed independently of each other.

Another example is Database Administration that might consist of the following tasks

1. Evaluate the Database Server Hardware

2. Install the Database Software

3. Plan the Database

4. Create and Open the Database

5. Back Up the Database

6. Enroll System Users

7. Implement the Database Design

8. Back Up the Fully Functional Database

9. Tune Database Performance

10. Download and Install Patches

For each of the task in the process interview the staff member performing the task and collect all relevant information such as

· How automated is the task currently?

· What are the job skills required by the person doing it?

· Is the task/process monitored using metrics?

· If so, which ones?

· How mature is the process?

Once the task list is sorted and grouped by process, it should be formally documented. This baseline document will be very important in the subsequent work.

STEP 2. Identify which tasks are still relevant in the cloud environment

The assessment in the previous step needs to take into consideration the Cloud Provisioning Model that is being used by the organization. For example, a SaaS provisioning model only needs to concern with the application level operations, e.g. performance monitoring, on the other hand this assessment will be much more elaborate in case of an IaaS provisioning model. Even in case of IaaS some of the tasks are irrelevant in the cloud. For example, facilities management will not be of concern in the cloud.

As part of this step, filter out such tasks and arrive at a list of tasks and processes that are still relevant.

STEP 3. Rank the maturity of the current process

Process maturity is an assessment of how well the process is performed at the firm. Specifically, how disciplined it is and how carefully its results are monitored and improved. Normally, process maturity is graded on a scale of five steps: ad hoc and random, repeatable, defined, managed, and optimized.

Ad hoc and random processes and tasks are performed irregularly based on the needs of the system. There are no documented steps for performing such processes. Need for such processes might arise due to unexpected events e.g. power failure at the data center.

Repeatable processes and tasks usually have a run-book, a manual or hand book of sorts, which clearly states all the steps that are needed to perform those tasks. Any operations person with basic skills should be able to perform such tasks following the run-book. However, such tasks are still random in nature and not scheduled or planned for.

Defined process and tasks are well known tasks in advance, they usually have a set repeatable schedule when they need to be performed and they have all the properties of a repeatable task.

Managed tasks are controlled and monitored tasks that either requires some kind of downtime or approvals from the management before they can be carried out. For example, most of the maintenance tasks such as increasing the disk space might fall in this category. Another example is deploying a new version of an application.

Optimized tasks are the ones that have been well studied and have been improved over a period of time. Such tasks are usually the oldest tasks that an organization has been performing and/or are tasks that are well defined in the industry. For example, database administration is a task that is optimized in most IT organizations. These are the tasks that can also be replicated as-is in the cloud environment.

In order to determine if a process needs to be improved as part of the move to the cloud, classifying existing operations based on their maturity is helpful.

STEP 4. for each process identify if any improvements are required

A move to the cloud environment presents an opportunity where any process or a task that needs to be improved can be improved. In order to identify if a process needs to be improved, one needs to gather information on industry best practices associated with that task. Such best practices are documented in books like Building Operational Excellence, authored by Bruce Allen & Dale Kutnick. To determine what needs to be improved and how, compare each process as performed at the organization with its corresponding best practices and determine the gaps that need filling.

Usually the best practices for a process will capture the following metrics:

1. Automation Balance – On a scale of 1 to 10 how automated a task is? Processes that are highly automated tend to be mature and should be modified with care. They generally are automated because they work well for the IT organization. Modifications to these processes often take the form of slight enhancements, installation of appropriate metrics, and the like. By comparison, manual processes should be examined in the context of finding means of automation.

2. Stability Balance – On a scale of 1 to 10 how stable a process is? A stable process means that the process or a task is mature, optimized and highly efficient. Such a process might not need any improvements.

3. Staffing skills – This capture a list of required/desired skills needed by the staff members supporting that process or task. These skills might have to be reconsidered as part of the move to the cloud.

4. Best Practices – captures all the best practices that are part of that process.

5. Process integration – should list integration points to other processes. Knowing the integration points can be significant when grouping processes. Integration points are also important in identifying which processes are affected by changes in other processes.

At this point one should not make the improvements but just identify what needs to be improved. Such improvements will have to take cloud capabilities into consideration and subsequent steps discuss that in detail.

STEP 5. create a list of minimal capabilities DESIRED from A cloud provider

If this process is followed, at this point the following information is known-

1. A list of all the processes under the aegis of IT operations, and all the tasks that make up those processes

2. Maturity of each of these tasks

3. Any improvements (if any) that are needed for these tasks

From this information it is possible to determine a list of minimal capabilities that a cloud provider needs to support. For example, consider the best practices for disk storage management process – For each of the best practice table 2 lists what capabilities a cloud provider needs to support

Disk Storage Management – Best Practices	Cloud Provider Capability to support the practice
Validate and test backup and recovery concepts	Point in time snapshot of volumes and replication across data centers. E.g. Amazon AWS provides an ability to take a just-in-time snapshot of its elastic block store that is automatically replicated across its S3 storage cluster. From this snapshot a new EBS volume can be created which will be a mirror image of the original.
Make overall storage management approach completely cross-platform	Attach and detach volumes to any virtual machine. Amazon AWS provides such a capability.
Prioritize all applications based on business driven recovery requirements	N/A
List what should be recovered and how long it should take	N/A
Implement an ongoing performance management/optimization process	Statistics such as I/O stat to track performance of the storage volumes

As another example, consider some of the best practices around Asset Management

Asset Management – Best Practices	Cloud Provider Capability to support the practice
Review new Assets	Ability to list and present all of the virtual machines being used, all the storage appliances being used, any networking appliances such as load balancers being used
Review of Asset Utilization	Ability to monitor key statistics such as I/O stats, CPU stats and memory stats
Identification of missing assets	See the first line item
Review risks and license compliance	N/A as most of the hardware assets are provided by the cloud provider
Review asset location	N/A. This is a benefit of moving to the cloud as the facilities are provided by the cloud provider
Review duplicate assets	Ability to see what is running on each of the appliances used from a cloud provider
Update contracts and licenses	This step is no different from hosting an in-house data center vs.. hosting on the cloud.

Yet another example is that of Performance Management. Performance Management can be further divided into performance management of operating system, performance management of applications (e.g. Java) and platforms such as Weblogic and performance management of databases. Table 3 below shows the best practices for O/S performance management (Unix is shown as an example in the table below) and what a cloud provider needs to provide –

O/S Performance Management – Best Practice	Cloud Provider Capability to support the practice
Monitor user mode and system mode CPU Utilization	Tools such as rstat. E.g. Amazon AWS provides cloudwatch service to monitor and manage such controls.
Average load on CPU, Interrupt rate, context switch rate
Process Monitoring – CPU utilization per process, amount of memory consumed, number of threads, user sessions	Tools such as ps, top, proc tools (/usr/proc/pstack, /usr/proc/pfiles), truss etc
Memory Monitoring – percent used, MB free, paging rate etc	Tools such as vmstat
I/O Monitoring	Tools such as iostat
Load balancing	Ability to replicate a machine from a spec (e.g. AMI in AWS) or creating a storage volume from a snapshot. E.g. Amazon AWS extends its cloud watch to automated application scaling by letting customers specify rules.

It is best to create a catalog of all the best practices required for all IT operations processes and what capabilities are available from the cloud provider in support of these process.

STEP 6. create an inventory of capabilities Actually supported by the cloud provider

Once the exercise of step 5 is completed, an organization moving to the cloud should have a comprehensive list of capabilities that the cloud provider needs support. However, a cloud provider will not support everything that is on this list. The next step in this process identifies the capabilities that are actually supported by the cloud provider. One might have to get creative here to see if a capability provided by a cloud provider can be made to work for a particular best practice even it is not the most desired or best fitting for the job. For example, AWS provides a control panel that lists all the EC2 instances that a client has started. Even though this is not the best way to have an inventory for assets, it can serve the purpose.

STEP 7. perform a gap analysis of what cloud provider provides and what is required for each of the process

Once the two lists from step 5 and 6 are available it becomes quite easy to see the gaps between what is desired by an organization to support all the operations in the cloud and what is realistic based on the capabilities provided by the cloud provider. This gap analysis might result in eliminating some of the processes or combining multiple processes into one. The gap analysis will also lead to some work where custom tools might need to be developed to support a particular process.

STEP 8. create a plan to bridge the gap

The next step after the gap analysis will create a plan to bridge the gaps between what a cloud provider supports and what is required to support all the processes. This step might generate some work for the Operations and maintenance team where they might be forced to create some custom tools to support critical processes for which there appears to be no support from the cloud provider. For example, a portal presenting a dashboard showing the performance metrics might have to be designed if the cloud provider lacks this.

This step might also lead to some innovation where an organization might either eliminate some processes or combine some of the processes to accommodate the gaps in cloud provider’s capabilities.

STEP 9. Develop A Set Of Policies And An SLA for The Cloud Provider

The previous steps would have produced a list of IT processes needed on the cloud, how best to utilize a cloud provider’s built in capabilities to support these processes, any custom work that is needed to support some of the processes that are not supported directly by a cloud provider. Step 4, generates a catalog that has all the relevant information about a process, the tasks that make up that process, the best practices around such a process, the key skills that the staff will need to support the process, the frequency at which the process needs to execute and its maturity.

Based on these inputs, a set of policies can be created, staffing needs can also be evaluated and a gap analysis can be performed about the current staff’s skill levels and what is needed for the cloud environment. A plan can be created to train the existing staff or hire new members.

The information collected so far can also be used in developing a clear SLA for the cloud provider stating specific parameters and minimum levels for each element of the service provided. The SLAs must be enforceable and state specific remedies that apply when they are not met. Aspects of cloud computing services where SLAs may be pertinent include:

· Uptime

· Performance and response time

· Error correction time

· Infrastructure/security

How To Use This Process

Developing an IT operations plan for the cloud is not a simple task. The exact nature of IT operations will vary from organization to organization and will be dependent on which cloud provider is used. The plan will also depend on the kind of provisioning model used in the cloud (different provisioning models being, IaaS, PaaS and SaaS). A SaaS might already have a fully baked SLA as well as all the operational tasks already defined by the cloud provider might not be able to modify that except make minor tweaks. An IaaS model on the other hand will require a lot of work to be done by the organization.

This section provides some help on how to use this process to develop a comprehensive IT operations plan.

As mentioned earlier, Step 1 and Step 2 will require input from the current operations staff. Please refer to the step 1 text to see how this step can be accomplished.

For step 3, besides the current operations staff input from the internal customers of the operations team and management might be needed as well. For step 4 senior IT personnel and development staff might have to be consulted. Step 5, 6, 7 and 8 are critical steps and will require discussions with the cloud provider. These steps need to be carefully documented. Someone who is knowledgeable about the cloud environment along with the senior staff from the operations team will have to be involved in developing these steps. Finally for developing step 9, some help from the legal department might be needed.

Conclusion

This paper presents a process for coming up with a plan and strategy for IT operations for an organization that is moving its operations to a cloud provider. The process consists of nine prescriptive steps and starts by identifying an organizations current IT operations. All the processes and the tasks in each of the process are clearly documented. The next step whittles the list down to only those operations that are relevant in the cloud environment. Moving along the next step investigates and documents the maturity of each of the process. Based on the outcome of this step, the next step will determine if any improvements to the existing process is needed. A list of desired feature from a cloud provider is then compiled and compared against the actual capabilities supported by the cloud provider. Based on the importance of the task, this gap analysis will lead to creation of some custom tools. Finally, a policy and SLA can be created for the cloud provider after reaching a mutual agreement with the cloud provider.

… and Android

As promised in the last blog we are not going to leave Android devices from accessing and getting on our virtual queues. After all Android powered smart phones/tablets are gaining popularity and  market share. So without further ado lets get right to it.

Creating the UI

As with the iOS devices, we are going to start by creating our simple UI for Android that mimics the web interface. Here is how the UI will appear on an Android emulator.

This looks awfully similar to the iOS interface and we have purposely designed it that way. Android UI screen is defined in a layout XML file. By convention (as in Ruby and Lift), the layout XML along with the rest of the resources used in an Android application, resides in a subdirectory of the “res” directory. This fact is important because, the code behind all resource XML is automatically generated. So for example, all the static strings used in the app are defined in strings.xml, colors are defined in colors.xml so on and so forth. The plug ins for Eclipse or intelliJ IDEA automatically generates some Java classes based on the contents of these XML files which we will see in a minute.

So back to the GUI. I was not able to find a UI builder as sophisticated as the iOS Interface Builder but I did use DroidDraw; downloadable from http://DroifDraw.org. This tool provides rudimentary capabilities for laying out the interface for an Android device. In our simple UI we have a few labels and a button. These UI widgets are arranged in a container of sorts that has the ability to arrange its child widgets. A container of widgets can also contain other container widgets. In this case, the container widget being used is a LinearLayout and it spreads its child widgets linearly (we ask it to arrange the widgets vertically by specifying the android:orientation as vertical).  The top container is asked to fill the entire screen by defining android:layout_width and android:layout_height  to fill the parent using the directive fill_parent. For the top most container this ends up filling the entire screen of the Android device.

The top container has two labels one for the main title “Welcome Queue” and the second for the sub title. These labels are TextView widgets and they are arranged one below the other, they are directed to wrap their contents tightly, show the contents in dark gray color, and are aligned in the center of the parent widget which was the  LinearLayout widget.

Below the two title labels are widgets that display the next available token number and the number of the token that the user of this application is currently holding, respectively, These are composed of two LinearLayouts, arranged one below the other and each layout containing two text labels. One being the static text telling the user what the number next to it means and the second label a dynamic string that will be updated based on a user action (the user action could be from the holder of the device, when s/he pushes the button to request the server to dispense a token, or it could be in reaction to some other user of another such device or the web site requesting for a token in which case our Android will display the updated number for the next available token).

Since the two labels (the static text label and the dynamic number label) appear next to each other horizontally, we  advise the two LinerLayouts to have an android:orientation as horizontal. The last widget in this UI is a button that is used to request a token from the server.

The layout XML for this GUI looks like this –

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation="vertical"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    android:background="@color/white"
    >
    <TextView
            android:id="@+id/widget51"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:text="Virtual Queue"
            android:textSize="36sp"
            android:typeface="sans"
            android:textStyle="bold|italic"
            android:textColor="@color/darkgray"
            android:gravity="center"
            android:layout_gravity="center_horizontal"
            >
    </TextView>
    <TextView
            android:id="@+id/widget52"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:layout_marginTop="40px"
            android:text="Welcome to Virtual Queue!"
            android:textSize="18sp"
            android:textColor="@color/darkgray"
            android:gravity="center"
            android:layout_gravity="center_horizontal"
            >
    </TextView>
    <LinearLayout
            android:id="@+id/widget35"
            android:layout_width="fill_parent"
            android:layout_height="wrap_content"
            android:layout_marginTop="20px"
            android:orientation="vertical"
            >
        <LinearLayout
                android:id="@+id/widget41"
                android:layout_width="fill_parent"
                android:layout_height="wrap_content"
                android:layout_marginTop="10px"
                android:layout_marginBottom="10px"
                android:gravity="center"
                android:orientation="horizontal"
                >
            <TextView
                    android:id="@+id/widget44"
                    android:layout_width="wrap_content"
                    android:layout_height="wrap_content"
                    android:layout_marginLeft="10px"
                    android:text="Next Available Number is:"
                    android:textColor="@color/darkgray"
                    >
            </TextView>
            <TextView
                    android:id="@+id/nextAvailableToken"
                    android:layout_width="wrap_content"
                    android:layout_height="wrap_content"
                    android:layout_marginLeft="15px"
                    android:text="0"
                    android:textColor="@color/darkgray"
                    >
            </TextView>
        </LinearLayout>
        <LinearLayout
                android:id="@+id/widget42"
                android:layout_width="fill_parent"
                android:layout_height="wrap_content"
                android:layout_marginTop="10px"
                android:layout_marginBottom="10px"
                android:gravity="center"
                android:orientation="horizontal"
                >
            <TextView
                    android:id="@+id/widget46"
                    android:layout_width="wrap_content"
                    android:layout_height="wrap_content"
                    android:layout_marginLeft="20px"
                    android:text="Your Token Number is:"
                    android:textColor="@color/darkgray"
                    >
            </TextView>
            <TextView
                    android:id="@+id/myTokenNumber"
                    android:layout_width="wrap_content"
                    android:layout_height="wrap_content"
                    android:layout_marginLeft="15px"
                    android:text="0"
                    android:textColor="@color/darkgray"
                    >
            </TextView>
        </LinearLayout>
        <Button
                android:id="@+id/getNextToken"
                android:layout_width="wrap_content"
                android:layout_height="wrap_content"
                android:layout_marginTop="30px"
                android:text="Get the next Token"
                android:layout_gravity="center_horizontal"
                >
        </Button>
    </LinearLayout>

</LinearLayout>

Generated Class

We alluded to the Generated Java class before when we laid out the GUI for our app as an XML file. The generated code is an important concept in Android apps so let us investigate it little more. The Android plug ins for the IDE  used to develop Android apps, be it Eclipse or intelliJ IDEA have the ability to generate the glue code from the resource XML files that we define. By default they generate the code in a R.java class that sits in the root package for your application. So each of the layout xml class will end up in a a generated View class (this happens automatically and a developer does not have to worry about it). The glue code for accessing the widgets of a layout is generated in  R.java in the root package. Lets look R.java for a minute:

package com.scoovyfoo;

public final class R {
    public static final class attr {
    }
    public static final class color {
        public static final int darkgray=0x7f040000;
        public static final int white=0x7f040001;
    }
    public static final class drawable {
        public static final int ic_launcher=0x7f020000;
    }
    public static final class id {
        public static final int getNextToken=0x7f070009;
        public static final int myTokenNumber=0x7f070008;
        public static final int nextAvailableToken=0x7f070005;
        public static final int widget35=0x7f070002;
        public static final int widget41=0x7f070003;
        public static final int widget42=0x7f070006;
        public static final int widget44=0x7f070004;
        public static final int widget46=0x7f070007;
        public static final int widget51=0x7f070000;
        public static final int widget52=0x7f070001;
    }
    public static final class integer {
        public static final int next_token_port=0x7f060000;
    }
    public static final class layout {
        public static final int main=0x7f030000;
    }
    public static final class string {
        public static final int app_name=0x7f050000;
        public static final int get_token_error=0x7f050001;
        public static final int get_token_url=0x7f050004;
        public static final int queue_server_dns=0x7f050002;
        public static final int queue_server_port=0x7f050003;
    }
}

This class contains a lot of static final classes. Each of these static class represents a “type” of resource that will be used in our application. For example, the string class contains constant values for all the strings that are used in the application; except instead of the actual strings, their integer id is stored here. Similarly all the layouts (or pages) that make up our application have an entry in the “layout” type. These “resources” are automatically generated from the XML files that one creates in one of the subdirectories of “res” folder. Again, like most modern frameworks, convention triumphs over customization. So is the case here as well. The directory structure follows a convention where every resource is expected to be in a “res” folder. Inside the res folder there are sub folders for different types of resources; all value resources can be found in the “values” folder, all layouts are in the “layout” folder and so on and so forth.

What gets generated in R.java is an entry for each type of resource with a unique integer id. Each of the key Android framework class provides a mechanism to get to these resources using the static variables in R.java e.g. to use the String “queue_server_dns”, one would invoke getString(R.string.queue_server_dns), similarly a widget can be fetched as findViewById(R.id.nextAvailableToken).

Android Activities

Moving along lets look at how the GUI that we defined in our layout xml is integrated with the application code that implements the core logic of our App. In android platform, a layout screen is backed up by an activity class (akin to the Controller class in iOS). In our case, the Activity class is the GetTokenActivity which extends the Android Activity class.

public class GetTokenActivity extends Activity implements TokenListener {
// Tag to be used for Logging messages
private static final String TAG = "GetTokenActivity";

// Handle to the GUI components that we are going to manipulate in this
// class
private TextView mNextAvailableToken; // Label to display the next available token number
private TextView mMyTokenNumber; // Label to display the number of the current token I am holding

In this class we declare the data members that are needed by the application. For example, since we need to update the two labels that show the next available token number and the number of the latest token that we are holding, we declare two class instance members of type TextView. Besides the data members, an activity class has to override certain callback methods that the Android OS will invoke as the application goes through its lifecycle

OnCreate is one such callback method that needs overriding. This is called after Android has finished creating the class. This method is similar to the awakeFromNib method of the iOS Controller class. As in the Controller class where we defined the UI elements of interest in the header file (Controller.h) by annotating them with the macro IBOutlet and IBAction, in Android we have to explicitly bind the UI elements of interest by calling the method findByViewID and passing the ID of the widget that was generated in R.java.

    /**
     * Called when the activity is first created.
     */
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        Log.i(TAG, "Entered OnCreate");
        setContentView(R.layout.main);

        // Obtain handles to GUI objects
        mNextAvailableToken = (TextView) findViewById(R.id.nextAvailableToken);
        mMyTokenNumber = (TextView) findViewById(R.id.myTokenNumber);
        Button lGetNextToken = (Button) findViewById(R.id.getNextToken);

        // Set the callback for the button
        lGetNextToken.setOnClickListener(new View.OnClickListener() {
            public void onClick(View v) {
                getNextToken();
            }
        });

        // Bind to the service that will listen on a socket for the next available token number
        Intent intent = new Intent(this, QueueServerSocketConnection.class);
        bindService(intent, mConnection, Context.BIND_AUTO_CREATE);
        // Now start the service
        startService(intent);
    }

This method associates the screen layout that this Activity is backing in this case R.layout.main by calling setContentView. Next, it associates the two data members it has with the actual widgets that Android creates in the View class (generated class). It does so by again using the IDs of the widgets defined in R.java and invoking findViewByID method. Once the widgets are located, they would be bound to the respective data members and they will become available from anywhere to use with in the class.

Get Me A Token

The activity class goes on and associates a call back with the only button present in the GUI. The callback method is similar to the one in iOS Controller class and call the getNextToken method which will use the web service exposed by the Queue Server to get the next token. The callback in the case of iOS is registered by using the Interface Builder controls. However in case of Android, we have to explicitly code it by implementing the interface View.OnClickListener and registering our implementation with the button using the setOnClickListener method of the Button class. This takes care of requesting a new token,  but what about updating the GUI with the number of the next token.

Update Next Available Token

For updating the next available token, our Queue server offers a Socket. Any interested client can listen on this Socket (which is opened on port 7201). When ever a new token is dispensed to any interested clients all the other clients registered on this socket are notified of the next available token number. The challenge, as it was in the case of the web interface, or the iOS is that we cannot tie our main thread of execution waiting for the next token to arrive on the socket. In case of the web interface we used Comet support in Lift along with the Actor based threading model to achieve not having to engage the main thread. In the case of iOS we created a new class called QueueServerSocketConnection  that utilized the CFStream framework and registered the read stream with the main run loop of the program. By registering the CFStream with the main run loop, we avoid blocking the main thread. The CFStream framework allows for us to register a listener which will be called by the run loop as and when events of our interest arrive.

In case of Android we will use a similar approach where by the gory details of connecting to a socket, listening for data on the socket etc. are abstracted in the QueueServerSocketConnection class. However, instead of delegating the actual socket related stuff to something like a CFStream, we will make this class in Android a Service class. As defined in Android documentation, a Service is  a component that can perform long running operations in the background and does not provide a user interface. This fits best for our case where we need a component to listen to the socket in the background and does not provide a user interface.

Once a service is created it needs to be started. Also, if a client needs to get some information from the service as the service executes, it needs to bind itself with the service. The last bit of code in the onCreate method does just that. We first bind the Activity with the Service using the bindService method and then start the service using the startService method.

Binding to a Service

In order to bind to a service,  we need to provide an implementation of the ServiceConnection interface. This ServiceConnection interface is used by the service class to notify its client once they are connected or disconnected from the service. The Service class passes back an instance of IBinder object that the client can use to hook into the service. In this case the IBinder object is of type QueueServerBinder that allows our Activity class to register a Handler with the Service class.

    /**
     * Defines callbacks for service binding, passed to bindService()
     */
    private ServiceConnection mConnection = new ServiceConnection() {
        public void onServiceConnected(ComponentName className,
                                       IBinder service) {
            Log.i(TAG, "Socket Service Connected");
            // We've bound to LocalService, cast the IBinder and get LocalService instance
            QueueServerSocketConnection.QueueServerBinder binder =
                    (QueueServerSocketConnection.QueueServerBinder) service;
            binder.setHandler(mHandler);
        }

        public void onServiceDisconnected(ComponentName arg0) {
        }
    };

So why do we need a Handler class?

Our ultimate goal here is to be able to update the GUI widget to show the next available token number. However, Android puts a hard constraint where a widget can only be updated by a thread that created it. This poses a problem for us because we had to create a new thread to run the QueueServerSocketConnection service in the background to avoid blocking the GUIs main thread. So when the Socket gets the new token it needs to update the TextView that shows the next available token. But since the thread for this socket listener service is not the same as the thread that owns the UI widgets, we will not be able to update the widget.

This is where a Handler class comes to the rescue. As stated in the reference documentation at the Android developer site – A Handler allows you to send and process Message and Runnable objects associated with a thread’s MessageQueue. Each Handler instance is associated with a single thread and that thread’s message queue. When you create a new Handler, it is bound to the thread / message queue of the thread that is creating it — from that point on, it will deliver messages and runnables to that message queue and execute them as they come out of the message queue.

So in a way a Handler class is similar to the Actor model in lift where messages can be passed to the Handler class and it keeps the messages in a queue only to be delivered to the thread that created the Handler class. In our case, we create the Handler class in the same thread that also creates GUI widgets, however as part of binding the activity to our Service class we register the handler object with the Service class. When the Service class receives a token, it will send a message to the Handler object. The Handler class defines a handleMessage method which is executed by the same thread as the one that created the Handler  object and the GUI widgets. Using this mechanism, inside the handleMessage method we can modify the UI widget to show the next available token’s number.

    // Define the Handler that receives messages from the thread and update the nextAvailableToken
    private final Handler mHandler = new Handler() {
        @Override
        public void handleMessage(Message msg) {
            Integer token = (Integer) msg.obj;
            receiveNewToken(token);
        }
    };

Requesting a token Using RESTful Web Services

So now we can update the GUI whenever a new token arrives on the socket. The only thing remaining at this point for our Activity class is to use the web service exposed by our server for requesting a token. This is done in the callback for the button click, As with the iOS, we want to invoke this web service asynchronously, so that we do not tie our application waiting for the service to complete. In case of iOS we used the NSURLConnection objects initWithRequest:delegate method in order to invoke the web service asynchronously. We registered the Controller object as the delegate that was called by the connection object as the request was completed.

In case of an Android app, the approach is slightly different. Android platform provides an AsyncTask which allows to perform background tasks and publish results on the UI thread. As mentioned before only the UI thread that owns the widgets is allowed to modify the widgets. An AsyncTask needs to be created on the UI thread. It is started by calling its execute method.  Once invoked the AsyncTask runs the background operation in a separate thread. As he task progresses, it invokes callback methods on the UI thread which will then update the widgets accordingly.

AsyncTask is a parameterized class and it is defined by 3 types called Params, Progress and Results and 4 steps, onPreExecute, doInBackground, onProgressUpdate and onPostExecute. The doInBackground method is invoked in a separate thread.

In our case we are interested only in doInBackground and onPostExecute where we make the web services call inside the doInBackground method and update the TextView widget in the onPostExecute method.

Here is the code for this class which is declared as a private class inside the GetTokenActivity class.

    private class GetMeAToken extends AsyncTask {
        private final HttpClient client = new DefaultHttpClient();
        private String token;
        private boolean error = false;

        protected void onPreExecute() {
        }

        protected String doInBackground(String... urls) {
            try {
                HttpGet httpget = new HttpGet(urls[0]);
                ResponseHandler responseHandler = new BasicResponseHandler();
                JSONObject jsonResponse = new JSONObject(client.execute(httpget, responseHandler));
                token = jsonResponse.getString("number");
            }  catch (IOException e) {
                Log.d(TAG,"IOException while getting json response",e);
                error = true;
                cancel(true);
            } catch (JSONException e) {
                Log.d(TAG,"JSONException while getting json response",e);
                error = true;
                cancel(true);
            }
            return token;
        }

        protected void onPostExecute(String token) {
            if (error) {
                Toast toast = Toast.makeText(GetTokenActivity.this, getString(R.string.get_token_error), Toast.LENGTH_LONG);
                toast.setGravity(Gravity.TOP, 0, 75);
                toast.show();
            } else {
                GetTokenActivity.this.displayToken(token);
            }
        }
    }

As you can see inside the doInBackground task we use the HttpClient to invoke the JSON web service. The response is then parsed as a JSONObect and we extract the token out of the JSON response. When doInBackground returns, the onPostExecute is invoked on the UI thread, The result is passed to this method which will update the myTokenNumber TextView.

This brings us to the end of everything that is interesting about the GetTokenActivity. Next we will consider the only Service we had to create in order to have our app listen on the Socket for the token number of the next available token.

Socket Connection to the Server for Live Updates – using Android Services

As mentioned earlier the live update of next available token is possible only because our queue server publishes that number on an open Socket. As was the case of iOS, we will accomplish the task of listening on this socket, waiting to hear about the next token and then notifying the GetTokenActivity to a class called QueueServerSocketConnection. Let us look at the code for this class’

public class QueueServerSocketConnection extends IntentService {
    // Logging
    private static final String TAG = "QueueServerSocketConnection";
    private static final int SOCKET_TIMEOUT = 500000;

    // Binder given to clients
    private final IBinder mBinder = new QueueServerBinder();

    // TokenListener
    private Handler mHandler = null;

    private Socket mSocket = null;
    private DataInputStream mDataInputStream = null;

The QueueServerSocketConnection is a specialized IntentService class that runs its service in a background worker thread separate from the main UI thread and is ideal in our case where we do not have a need to execute multiple tasks simultaneously. All that is required of the IntentService is to provide an implementation for the onHandleEvent method like this –

    @Override
    protected void onHandleIntent(Intent intent) {
        Log.d(TAG, "Inside onHandleIntent");
        do {
            try {
                Integer tokenNum = mDataInputStream.readInt();
                Log.d(TAG, "Got a new token " + tokenNum);
                if (mHandler != null) {
                    Log.d(TAG, "Sending token to handler " + tokenNum);
                    Message msg = mHandler.obtainMessage();
                    msg.obj = tokenNum;
                    mHandler.sendMessage(msg);
                }
            } catch (IOException e) {
                e.printStackTrace();  //To change body of catch statement use File | Settings | File Templates.
                throw new RuntimeException(e);
            }
        } while (true);
    }

This method is invoked on the worker thread with a request to process. It takes an Intent as an argument which is nothing but an abstract description of an operation to be performed. Only one Intent is processed at a time, but the processing happens on a worker thread that runs independently from other application logic. So, if this code takes a long time, it will hold up other requests to the same IntentService, but it will not hold up anything else. When all requests have been handled, the IntentService stops itself.

It is in this method that we create an infinite loop which will just sit and listen on the input data stream of the Socket waiting for an integer to arrive. When it gets an integer, it reads the number and it will use the message Handler that was registered by the GetTokenActivity class as described earlier to inform the client of this service of the next available token number. We will visit binding to a service once again to explain what a Service needs to do in order to allow a client to bind to it. For now lets concentrate on the Handler mechanism for communicating the next token number. We explained earlier that a Handler class allows you to send a Message. And that is exactly this method will accomplish. It will obtain the Message object from the Handler class and use that object for setting the token number. The sendMessage method will be used to then send the Message to the Activity class and will arrive on the queue of the thread that created this Handler object. Eventually, the handleMessage method of the Handler class is invoked but on the thread that created the Handler object.

Binding to a Service – Revisited

Earlier we saw binding to a Service from a Client’s perspective, now lets see what a Service needs to provide in order to let a client connect to it.

The first thing a Service needs to provide is an implementation for the IBinder interface. An IBinder is what is passed to the client when a connection to a service is established. In our case we create a QueueServerBinder class and all it needs to do is extend an abstract Binder class and provide a method that will be used by this Service’s client to register a Handler object with the Service. The Handler will be used later by the Service class to communicate the next available token number with the Client.

    /**
     * Class used for the client Binder.  Because we know this service always
     * runs in the same process as its clients, we don't need to deal with IPC.
     */
    public class QueueServerBinder extends Binder {
        public void setHandler(Handler aHandler) {
            Log.d(TAG, "Binding handler");
            QueueServerSocketConnection.this.mHandler = aHandler;
        }
    }

    @Override
    public IBinder onBind(Intent intent) {
        return mBinder;
    }

The onBind method is invoked when the client calls the bindService method. As part of the bindService, the client provides a ServiceConnection object. Once this Service is connected with the Client, the onServiceConnected method of the ServiceConnection class is invoked and the IBinder is passed to the ServiceConnection object which will then use the Binder to register the Handler class.

The only interesting thing remaining in this class is the onCreate method which is where the Socket connection is established and the data stream is opened.

    @Override
    public void onCreate() {
        Log.i(TAG, "inside onCreate - Creating Socket");
        super.onCreate();
        if (mSocket == null || mSocket.isClosed()) {
            try {
                //mSocket = new Socket(InetAddress.getByName("localhost"), 7201);
                mSocket = new Socket();
                Log.d(TAG, "Opening client socket - ");
                mSocket.bind(null);

                mSocket.connect((new InetSocketAddress(getString(R.string.queue_server_dns),
                        getResources().getInteger(R.integer.next_token_port))), SOCKET_TIMEOUT);

                Log.d(TAG, "Client socket - " + mSocket.isConnected());
                assert mSocket != null;
                mDataInputStream = new DataInputStream(mSocket.getInputStream());
                Log.i(TAG, "Socket Created, Stream Opened");
            } catch (UnknownHostException e) {
                e.printStackTrace();  //To change body of catch statement use File | Settings | File Templates.
            } catch (IOException e) {
                e.printStackTrace();  //To change body of catch statement use File | Settings | File Templates.
            }
        }
    }

Conclusion

So there we have it, with this we can get to our virtual queue through a web interface, an iOS app and an Android app. Next we will create an actual queue and see how to make the queue discoverable.

On to iDevices

Happy New  Year everyone! Hope you all had wonderful Holidays!

We are going to begin this new year by finally putting the iOS interface together. To recap, we have the building blocks for our Virtual Queues in place. We have a web service that can be used to request tokens, we also have an open Socket that we can  listen on to get real time updates about the next available token number. We are going to use both of these capabilities in putting together an iOS app that will look similar to the web application. We will be able to request tokens using this app and we can get real time updates about the next available token.

Creating the UI

Let’s begin by creating a simple UI that mimics the same capabilities as the Web interface. We are not going to explain how to create a GUI for iOS. There are plenty of good tutorials out there for this. We will only go over the relevant code for our application. Our UI will have two updateable labels and one button. One of the labels will show the next available token number, the other one will show the number of the token that we requested by pressing the button. Of course just as in the web interface we can request as many tokens as we wish. Each time anyone requests a token, all the clients connected to the server will be updated simultaneously with the number of the next available token.

The GUI will look like this.

Backing this GUI is a controller class. This controller class is used to manipulate the labels as well as  handling a touch action from the button.

#import <Foundation/Foundation.h>
#import "QueueServerSocketConnection.h"

@interface Controller : NSObject  {
	IBOutlet UILabel *nextAvailableToken; // Label to show the next available token number
	IBOutlet UILabel *myTokenNumber; // Label to show the our latest token number
	QueueServerSocketConnection* connection; // Socket Connection
	NSMutableData* myTokenBuffer; // Buffer to hold tokens returned by the server
}

- (IBAction)getNextToken:sender;

@end

The interface file for our Controller has an entry for each of the labels, one for the next available token and the other for the token that was requested by the user. It also has a pointer to a QueueServerSocketConnection class. This class abstracts the socket connection to the Queue Server. Finally, there is a pointer to a buffer that will be used to hold the token returned by the server when the UI button is pressed. To handle the event of a user pressing the UI button, our Controller class declares an action getNextToken. This action will generate the Rest Web Service request to the server to get the next token.

Socket Connection to the Server for Live Updates

In order to get live updates from the Queue Server about the next available token, we will create a class to abstract the gory details from the GUI Controller. Our GUI Controller will simply register with this class to get the number of the next token when and if it becomes available.

The QueueServerSocketConnection class will hide the details of opening a Socket Connection to the server, managing the data streams, patiently listening on the input data stream and then collecting the bytes as they arrive and composing a number out of the raw data taking into consideration all the details such as the endianess. Here is the interface for this class.

#import <Foundation/Foundation.h>
#import <CFNetwork/CFSocketStream.h>
#import "TokenListener.h"

@interface QueueServerSocketConnection : NSObject {
	id<TokenListener> listener;

	// Host and Port to connect to...
	NSString* host;
	int port;

	// Stream to read
	CFReadStreamRef inputDataStream;
	bool inputDataStreamOpen;
	NSMutableData* inputDataBuffer;
}

@property(nonatomic,assign) id listener;

// Initialize
- (id)init:(NSString*)host andPort:(int)port;

// Connect to the server
- (BOOL)connect;

// Close connection
- (void)disconnect;

@end

This class contains all the data elements needed to establish a successful socket connection. It has the information about the host and the port that it needs to connect to, for reading data it has a CFReadStreamRef object, it also has a data buffer that will be used to collect the token number of the next available token as it arrives on our input stream. This class also has a listener that is registered with it. This listener is the one interested in getting the token number of the next available token. So when a number arrives on the input stream this class will read it off and invoke the appropriate method of the TokenListener. Since any class can be interested in a token, instead of making TokenListener a concrete class, we will make it a protocol and then let any class interested in a token conform to the protocol.

A protocol in objective-c is similar to a java interface, it declares set of methods and any concrete class can conform to the protocol by declaring it in its interface and then by implementing all the protocols methods. Our TokenListener protocol looks like this –

@class QueueServerSocketConnection;

@protocol TokenListener
- (void) connectionAttemptFailed:(QueueServerSocketConnection*)connection;
- (void) connectionTerminated:(QueueServerSocketConnection*)connection;
- (void) receiveNewToken:(int)token;
@end

This is a simple protocol that will handle receiving a new token and any socket connection failures. For now, we will make our Controller class conform to this protocol and register the Controller object with the QueueServerSocketConnection as its TokenListener.

Ok so its time to see how our QueueServerSocketConnection will be implemented. (please note that some of this code is influenced by the excellent tutorial found at – http://mobileorchard.com/tutorial-networking-and-bonjour-on-iphone/, for a better understanding of network programming I would highly recommend reading this).

We will start with opening a connection to the host on a particular port and attaching an input stream to it.

- (BOOL)connect {
	if ( self.host != nil ) {
		// Bind read/write streams to a new socket
		CFStreamCreatePairWithSocketToHost(kCFAllocatorDefault, (CFStringRef)self.host,
										   self.port, &inputDataStream, NULL);

		return [self setupInputDataStream];
	}

	// No host - cannot connect
	return NO;
}

The CFStreamCreatePairWithSocketToHost creates a readable stream (but no writeable stream, since we pass NULL for write stream). Next we will set up the input stream –

- (BOOL)setupInputDataStream {
	// Make sure streams were created correctly
	if ( inputDataStream == nil ) {
		[self disconnect];
		return NO;
	}

	// Create buffer for reading data
	inputDataBuffer = [[NSMutableData alloc] init];

	// Sockets should close when streams close
	CFReadStreamSetProperty(inputDataStream, kCFStreamPropertyShouldCloseNativeSocket,
							kCFBooleanTrue);

	// Handle following stream events
	CFOptionFlags registeredEvents =
	kCFStreamEventOpenCompleted |
	kCFStreamEventHasBytesAvailable |
	kCFStreamEventCanAcceptBytes |
	kCFStreamEventEndEncountered |
	kCFStreamEventErrorOccurred;

	// Setup stream context - reference to 'self' will be passed to stream event handling callbacks
	CFStreamClientContext ctx = {0, self, NULL, NULL, NULL};

	// Specify callbacks that will be handling stream events
	CFReadStreamSetClient(inputDataStream, registeredEvents, inputDataStreamEventHandler, &ctx);

	// Schedule streams with current run loop
	CFReadStreamScheduleWithRunLoop(inputDataStream, CFRunLoopGetCurrent(),
									kCFRunLoopCommonModes);

	// Open input stream
	if ( ! CFReadStreamOpen(inputDataStream)) {
		[self disconnect];
		return NO;
	}

	return YES;
}

During the set up of the input stream, we first allocate a buffer that we will use to collect data as it comes on the stream. We then tell the stream to close the socket when the stream is closed. Next we setup all the events that we are interested on this stream. Next we set the current object as the listener for the events we are interested in by setting the method inputDataStreamEventHandler as a callback method. Whenever, an event of our interest happens on the input stream, this callback will be invoked. Since listening on the stream for events is blocking, we do not want to tie our thread of execution to wait for an event to arrive. Instead, we will  register our stream with the run loop. Since we have already registered a callback with the stream, the run loop will invoke the callback if an when an event of interest arrives.  We achieve this by calling CFReadStreamScheduleWithRunLoop. Once the input stream has been properly setup, we will open it using CFReadStreamOpen. This method will return true, if the stream can be opened in background without blocking.

Next we will look at how events from this stream are handled. The code for handling the events is registered as a callback inputDataStreamEventHandler. This callback and its helper function inputDataStreamHandleEvent are explained next.

void inputDataStreamEventHandler(CFReadStreamRef stream, CFStreamEventType eventType,
							void *info) {
	QueueServerSocketConnection* connection = (QueueServerSocketConnection*)info;
	[connection inputDataStreamHandleEvent:eventType];
}

// Handle events from the input stream
- (void)inputDataStreamHandleEvent:(CFStreamEventType)event {
	// Stream opened
	if ( event == kCFStreamEventOpenCompleted ) {
		inputDataStreamOpen = YES;
	}
	// Data available for reading
	else if ( event == kCFStreamEventHasBytesAvailable ) {
		// Read as many bytes from the stream as possible; extract a token
		[self inputDataStreamToInputDataBuffer];
	}
	// Connection has been terminated or error encountered (we treat them the same way)
	else if ( event == kCFStreamEventEndEncountered || event == kCFStreamEventErrorOccurred ) {
		// Clean everything up
		[self disconnect];

		// If we haven't connected yet then our connection attempt has failed
		if ( !inputDataStreamOpen) {
			[listener connectionAttemptFailed:self];
		}
		else {
			[listener connectionTerminated:self];
		}
	}
}

The inputDataStreamHandleEvent has is a big if-then-else case statement that deals with all the events that we have shown interest in handling. The key events that needs further discussion is inputDataStreamToInputDataBuffer which will be invoked when kCFStreamEventHasBytesAvailable event is triggered. This event will be triggered when some data arrives on the input stream.

- (void)inputDataStreamToInputDataBuffer {
	// Temporary buffer to read data into
	UInt8 buf[1024];
	int tokenNumber;

	// Try reading while there is data
	while( CFReadStreamHasBytesAvailable(inputDataStream) ) {
		CFIndex len = CFReadStreamRead(inputDataStream, buf, sizeof(buf));
		if ( len <= 0 ) {
			// Either stream was closed or error occurred. Close everything up and treat this as "connection terminated"
			[self disconnect];
			[listener connectionTerminated:self];
			return;
		}

		[inputDataBuffer appendBytes:buf length:len];
	}

	// Try to extract token number from the buffer.
	// We might have more than one token in the buffer - that's why we'll be reading it inside the while loop
	while( YES ) {
		// If we got a complete integer, treat it as the next token number
		if ( [inputDataBuffer length] >= sizeof(int) ) {
			// extract token number
			memcpy(&tokenNumber, [inputDataBuffer bytes], sizeof(int));

			// Send the token number to the listener
			//
			if (CFByteOrderGetCurrent() == CFByteOrderLittleEndian){
				[listener receiveNewToken:CFSwapInt32BigToHost(tokenNumber)];
			}
			else {
				[listener receiveNewToken:tokenNumber];
			}

			// remove that chunk from buffer
			NSRange rangeToDelete = {0, sizeof(int)};
			[inputDataBuffer replaceBytesInRange:rangeToDelete withBytes:NULL length:0];
		}
		else {
			// We don't have enough yet. Will wait for more data.
			break;
		}

	}
}

There are a few things that we need to consider in the function that is used for collecting bytes as they arrive on the input stream

1. There could be more than one integer that might arrive at the same time. The first loop reads all the available bytes on the stream without blocking. It reads these bytes in 1K chunk and collects them in the inputDataBuffer.
2. Big Endian vs Little Endian. – The network byte order is big endian which means that the most significant byte is stored an transmitted first, however, the iOS is little endian which means that it expects the most significant byte to be stored last. This causes an issue because the bytes are now flipped. In order to fix this we have to first make sure the endian ness of the iOS system and then swap the integer from Big Endian to the host format. Luckily objective C provides CFSwapInt32BigToHost for doing just that.
3. Once we have the token number read, we can call the registered TokenListener and hand the token number to it. This is all there is to opening a socket and listening for next available token numbers. Next we will see what TokenListener will do with these numbers.

Handling new token numbers

As mentioned before the TokenListener protocol is implemented by our Controller class. Besides handling the new token numbers, the Controller class also requests a token from the server using the web service that the server exposes. Let us see the Controller code for handling the next token number handed to it by the QueueServerSocketConnection.

NSString * const hostDNS = @"ec2-174-129-160-102.compute-1.amazonaws.com";

// Called after all the GUI items have been instantiated
- (void) awakeFromNib{
	connection = [[QueueServerSocketConnection alloc] init:hostDNS andPort:7201];
	connection.listener = self;
	[connection connect];
}

- (void) receiveNewToken:(int)token {
	nextAvailableToken.text = [NSString stringWithFormat:@"%d", token];
}

This code is extremely simple, in the awakeFromNib callback we create an instance of the QueueServerSocketConnection and make it connect to our server running on the Amazon Cloud, we also register the Controller class which is a TokenListener with the socket connection. When a new token number is published by the server, the QueueServerSocketConnetion object will invoke the receiveNewToken method as we saw earlier and all that we need to do here is to display the token number in the label on the GUI.

Requesting a token using RESTful web service

The web service exposed by our server is one way to request a token from the server. Next we will make our iOS app use this web service and get the token as a JSON. It will then parse the JSON and extract the number that was dispensed by the server and display that number in the right  label on the GUI. We will make an asynchronous web service request and register our Controller class as a delegate for the connection. As a delegate for the URL connection we will have to provide several functions that the connection can invoke as the request loads. Let’s look at each of these delegate methods.

- (IBAction)getNextToken:sender {
	NSURLRequest *request = [NSURLRequest requestWithURL:[NSURL URLWithString:[NSString stringWithFormat:@"http://%@:8080/Lift-1.0/dispense/token.json", hostDNS]]];
	myTokenBuffer =[[NSMutableData alloc] init];
	[[NSURLConnection alloc] initWithRequest:request delegate:self];
}

- (void)connection:(NSURLConnection *)connection didReceiveResponse:(NSURLResponse *)response {
	[myTokenBuffer setLength:0];
}

- (void)connection:(NSURLConnection *)connection didReceiveData:(NSData *)data {
	[myTokenBuffer appendData:data];
}

- (void)connection:(NSURLConnection *)connection didFailWithError:(NSError *)error {
	myTokenNumber.text = [NSString stringWithFormat:@"Connection failed: %@", [error description]];
}

- (void)connectionDidFinishLoading:(NSURLConnection *)conn {
	[conn release];

	NSString *responseString = [[NSString alloc] initWithData:myTokenBuffer encoding:NSUTF8StringEncoding];
	[myTokenBuffer release];

	NSDictionary *dictionary = [responseString JSONValue];
	myTokenNumber.text = [NSString stringWithFormat:@"%@", [dictionary objectForKey:@"number"]];
}

The request for a token is initiated when a user presses the “Get the next Token” button on the GUI. Associated with the button is a callback action coded in the Controller class named “getNextToken”. It is in this action method that we will initiate the web request to our server. As mentioned earlier our server is running on Amazon’s EC2 cloud and we create the URL with the public DNS of our EC2 instance. Also remember from one of the previous blogs that the web service for JSON request is located at <CONTEXT-PATH>/dispense/token.json. We will use this fully qualified string to create a URL and then we will create the request object using this URL.Next we will create a URL connection object using the request object and we will list our controller as the delegate. This will immediately start the request.

To fulfill the delegates contract we will provide all the callback methods that will be called as the request loads – as soon as the response arrives connection:didReceiveResponse message is received, we  will reset our data collection buffer here. As data arrives, connection:didReceiveData message is received repeatedly, we will start collecting the data in this request. However, we cannot be sure when all the data has arrived until we get the connectionDidFinishLoading message. This is where we will parse the JSON and extract the token that was dispensed by the server and display it in the right label.

Parsing JSON

We are using the SBJSON parser created by Stig Brautaset and available at git://github.com/stig/json-framework.git  This parser is simple and we use it to generate a NSDictionary object that will parse the JSON request and it will create key:value  pairs where key is the JSON tag and value is the token number that was returned by the server. Next we will lookup the key “number” and display its value in the myTokenNumberlLabel.

Conclusion

So there we have it. We now have multiple channels to getting in-line. We can use the web interface if we so desire. More useful will be the mobile app for looking up a queue and getting on it. In the next blog we will port this interface to Android platform.

The entire code base is here

Preparing for the Mobile World – Part II

Continuing with our effort to open up queues for mobile devices, we need to make one more modification to the server before we code the actual mobile interface either on the iOS or on Android. We have a Socket open on the server already that will be used for real time queue status updates to the mobile devices; but we also need a web service for dispensing tokens to the mobile devices. The web interface used Ajax to get a new token, for the mobile  world the same functionality will be made available via a web service. In today’s blog we will see how easy it is to add a basic web service using Scala.

Dispensing tokens via a RESTful Web Service

We will add a web service that will dispense tokens from our solitary queue on the server – the AQueue. Lift makes it extremely easy to add a web service using a trait called RestHelper. This trait makes heavy use of pattern matching, implicit conversions, and extractors in Scala. The RestHelper trait supports both XML and JSON requests. It makes heavy use of extractors in Scala to break down a HTTP request into its constituent parts, separating not only the path of the request but also determining the verb of the HTTP request – raw GET or a GET for JSON or a GET for XML, a raw POST request, PUT request or a DELETE request. It determines the type of HTTP request by looking at the Accept header of the request as well as the suffix of the path (.xml, .json etc). Extractors in Scala are objects that can match a value and then break it apart into its constituents. An extractor object needs to provide an “unapply” method that is used to match a value and then break it apart. The RestHelper object provides such extractors.

The way RestHelper intercepts our HTTP request (in order to break it apart), is to hook itself into the custom request dispatch mechanism supported by Lift. A custom dispatch bypasses the Lift’s normal mechanism of going through a template matching and can pass the request directly to a custom method that you define. Custom dispatch in Lift is realized by a PartialFunction that takes a request and returns a function that returns the final response. The type of RestHelper is such a PartialFunction.

Once our RestHelper is hooked into the custom dispatch mechanism of Lift any HTTP request that matches the pattern that our RestHelper can handle will be forwarded to our RestHelper. We define the pattern of requests that we can handle by calling the “serve” method provided by RestHelper (as part of its constructor when the instance of our RestHelper is instantiated by the custom dispatch mechanism of Lift). This method expects a partial function that can take a http request and converts it into another function of a type that takes nothing but returns a Box of LiftResponse.

Here the code of our RestHelper which we have named WebSvcTokenDispenser.

package Lift.lib

import net.liftweb.http.rest.RestHelper
import Lift.model.AQueue
import Lift.model.AQueue._
import net.liftweb.json.JsonAST.JValue
import xml.Node
import net.liftweb.http.PlainTextResponse

/**
 *
 * User: Anupam Chandra
 */

object WebSvcTokenDispenser extends RestHelper {
  serve {
    case "dispense" :: "token" :: Nil JsonGet _ => AQueue.dispenseAToken: JValue
    case "dispense" :: "token" :: Nil XmlGet _ => AQueue.dispenseAToken: Node
    case "dispense" :: "token" :: Nil Get _ => AQueue.dispenseAToken : PlainTextResponse
  }
}

This code is very simple. It states that our WebSvcTokenDispenser is a RestHelper which means that we get all the extractors, and dispatch mechanism for free. All we define is what kind of request we can handle and the response that we will generate for that request. We do that by calling the “serve” method when our RestHelper is created. The serve method registers a partial function with the RestHelper class. When a request comes in, Lift will match the request against all the dispatchers it has. The first one that has a Partial Function that has the request pattern defined will be invoked.

The way we hook our RestHelper into the custom dispatch mechanism of Lift is by configuring it in LiftRules inside the Boot.scala class like this –

    LiftRules.statelessDispatchTable.append(WebSvcTokenDispenser)

Once we have our dispatch partial function WebSvcTokenDispenser, registered in the statelessdispatchTable, the dispatch mechanism will give our function an opportunity to service a request that it can.

Now let’s look at what request pattern we are registering. The partial function that we are passing to the Serve method of RestHelper class can handle three types of GET requests, a raw GET determined  by the pattern

case "dispense" :: "token" :: Nil Get _ => PlainTextResponse(AQueue.dispenseAToken.toString)

Which basically says that it the URI contains a path (after the context) dispense/token or dispense/token.htm, we can handle it. A JSON GET determined by the pattern

case "dispense" :: "token" :: Nil JsonGet _ => AQueue.dispenseAToken: JValue

and an XML GET determined by the pattern

case "dispense" :: "token" :: Nil XmlGet _ => AQueue.dispenseAToken: Node

Lift parses the http request by taking the URI between the context path and the query string and creates a List of strings (List[String]) where each path element of the URI after the context is inserted into the List, So in this case, a request

http://localhost:8080/dispense/token.htm will result in a List with two entries “dispense” and “token”. The suffix of the URI determines the type of HTTP request, GET, JSON GET or XML GET.

So http://localhost:8080/dispense/token.json will result in a JSON request and http://localhost:8080/dispense/token.xml will result in an XML request. We can use cURL to test this

[anupamchandra@FCOH1W-3P6TKM1: ~]> curl http://localhost:8080/dispense/token.json
{
  "$outer":{

  },
  "number":101
}
[anupamchandra@FCOH1W-3P6TKM1: ~]> curl http://localhost:8080/dispense/token.xml
<?xml version="1.0" encoding="UTF-8"?>
<$outer></$OUTER>105

[anupamchandra@FCOH1W-3P6TKM1: ~]> curl http://localhost:8080/dispense/token.htm
Token(106)
[anupamchandra@FCOH1W-3P6TKM1: ~]>

When the request type matches one of the entries defined in the argument to the serve method, the partial function associated with that request is invoked. So in case of raw Get, the function  that will be invoked will return a PlainTextResponse that will look like Token(100). In case of JSON or XML get request, the function will convert the Token dispensed by the queue into a JValue or a xml Node.

The appropriate type of response is created by using the implicit conversion mechanism of Scala. These implicit conversions will take one type and convert it into another type implicitly (the compiler interjects the implicit functions). We define these conversions in the AQueue class like this

package Lift.model

import com.scoovyfoo.domobj.TokenDispenser
import Lift.comet.TokenRefresher
import net.liftweb.json.JsonAST.JValue
import xml.Node
import net.liftweb.json.{Xml, Extraction}
import net.liftweb.http.PlainTextResponse

/**
 *
 * User: Anupam Chandra
 */

object AQueue {
  val tokenDispenser = new TokenDispenser(100)

  def dispenseAToken = {
    val token = tokenDispenser.dispense
    TokenRefresher ! "R"
    token
  }

  private implicit val formats = net.liftweb.json.DefaultFormats
  implicit def toPlainText(token: tokenDispenser.Token): PlainTextResponse = PlainTextResponse(token.toString)
  implicit def toJson(token: tokenDispenser.Token): JValue = Extraction.decompose(token)
  implicit def toXml(token: tokenDispenser.Token): Node = {Xml.toXml(token)}
}

Here we see that there are three implicit conversion defined one each for plain text, JSON and XML. Our WebSvcTokenDispenser class will use these implicit converters as a response to a HTTP request that matches the one it can service.

Conclusion

That is all there is to it. In less than 25 lines of code (ignoring comments and empty lines)  we have added a fully functional web service for our Virtual Queues that can serve not only plain text tokens but also XML and JSON based tokens. Now we are fully ready to put up a mobile interface for our virtual. This is what we will do in our next blog.

Preparing for the Mobile World

So we have a web interface for our Virtual Queues. That’s a good start, but to make the queues really useful, they need to be available from anywhere. With the flooding of smart phone and tablets in the market, we need to open our queues up for use from these devices. If you are in a grocery store, chances are that you have your smart phone with you, Using the mobile app, one can locate a queue for the deli section or a queue for the pharmacy and can get on the queue using their mobile device.

In order to achieve this, we will have to open our application for the mobile platform. The main challenge is the same as for the web interface; we need an ability to update all the devices and web interfaces that are on the same queue as soon as the state of the queue changes. We still do not have the Queues coded yet but we will add them soon, however, we have the beginnings of a queue – our TokenDispenser. On the web front we were able to achieve this capability of real time client updates using long-polling mechanism and Comet support in Lift. Things are not so simple when it comes to mobile devices. In today’s blog we will discuss the modifications we need to make in preparation of the mobile platform.

Opening another channel to our server – using Sockets

To support instant client updates for the mobile devices, we will open a socket on the server. The server will use this socket for sending updates to all the clients registered and listening on the socket. As part of the boot process we will open a Socket to listen on  a port. As soon as a connection is established on that socket, we will immediately spawn out a new thread (Actor) to handle the client. Here is the code for opening and listening on a socket.

  private val socketServer = actor {
    val port = Props.getInt("socketBasedTokenObserver.port", 7777)
    try {
      val listener = new ServerSocket(port)
      while (true) SocketBasedTokenObserver(listener.accept())
      listener.close()
    }
    catch {
      case e: IOException => System.err.println("Could not connect to port: " + port)
    }
  }

This code is part of the Boot class. Notice how we have made socketServer an actor. As soon as the system boots up the actor starts in its own thread. It gets the port number for opening a socket from default.props file under the resources directory. This actor will then create a new ServerSocket and will wait on the socket to see if anyone attempts to connect. When a client connects to this socket, the server will spawn a new actor “SocketBasedTokenObserver”, it will hand the newly created Socket connection to this observer and will get back to waiting for more connections. The SocketBasedTokenObserver is itself an Actor and so it will run in its own thread. Here is the code for SocketBasedTokenObserver –

package Lift.comet

import net.liftweb.actor.LiftActor
import java.net.{SocketException, Socket}
import java.io.DataOutputStream
import net.liftweb.http.{RemoveAListener, AddAListener}

/**
 *
 * User: Anupam Chandra
 */
case class SocketBasedTokenObserver (socket: Socket) extends LiftActor{
  TokenRefresher ! AddAListener(this)
  val out = new DataOutputStream(socket.getOutputStream())

  def messageHandler = {
    case x: Int => {
      out.writeInt(x)
    }
  }

  override def exceptionHandler = {
    case e: SocketException => TokenRefresher ! RemoveAListener(this)
    case _ => {
      if (socket.isConnected){
        if (!socket.isOutputShutdown) out.close()
        socket.close()
      }
      TokenRefresher ! RemoveAListener(this)
      super.exceptionHandler
    }
  }
}

The SocketBasedTokenObserver is a Lift Actor. Since it’s a LiftActor, we can directly register it with our TokenRefresher, the singleton ListenerManager that we discussed in the previous blog entry. The TokenRefresher not only register the Comet observers that update web sites but now it also registers the Socket based listeners that can update the mobile devices listening on a socket. It registers with the TokenRefresher by sending it a message of type AddAListener. Inside the AddAListener message is a self reference.

When the TokenRefreshes updates all its listeners, the messageHandler method provided by this class will be invoked. This method will then write the next token number out on to the DataOutputStream attached to the socket. That is how the mobile devices listening on the Socket will be updated.

Conclusion

Adding a Socket is the first step towards putting up a mobile interface. In my next blog entry I will discuss the next change we need to make to enable mobile devices – exposing a web service that the device could use to order the system to dispense it a token.

Lift it to the web

We have the beginnings for our Virtual Queues. We have the concept of a Token and a Dispenser of tokens. We have made these thread safe so we are guaranteed that everyone requesting a token gets a unique one. At this point we can create a simple web interface on top of the token dispenser just so we can see how the whole system will evolve incrementally, After the web interface we will put a mobile interface on top of our Token Dispenser and then we will add persistence to it.

For now we will keep these interfaces  very simple. We will display the number of the next token that the dispenser will hand out. We will also provide a button that the user of the interface can press to dispense a token for them at which point we will display the token number that the user got from the token dispenser. We will also update the next available token number from the dispenser. The challenging part about this interface is that multiple clients might be using the same token dispenser. They will have to be updated simultaneously as soon as any one requests the next token. For example, lets say that there are two separate users interested in getting token from the same dispenser. If the number of the next token that the dispenser can hand out is 100, as soon as any one of the user requests the token, both the users should be updated to show that the next token that can be dispensed is 101.

In this blog we will see how to create this simple web interface and then how to achieve the simultaneous update of all the browsers with the next token number as soon as one of them requests a token.

In the spirit of learning Scala we will create our web interface using Lift, a web framework developed in Scala. Lift fits naturally with the Scala Middle tier that we have been coding up until now.

A Little Lift

Unlike other traditional web frameworks e.g. JSF, Struts, Grails etc. Lift framework is NOT based on the MVC design pattern. Where as in a traditional MVC framework, the user actions from the web browsers are handed first  to a controller which converts those into actions on the model class and then select the right views to form the responses, Lift loads the views first and builds the output page from the view. In case of Lift, the view is a fully qualified HTML file. It is sprinkled with a lot of components. These components are backed by Scala classes called Snippets. The logic in the Snippet class provides the dynamic content for the web page.

Lift prescribes the following steps to get dynamic content of a page rendered correctly –

1. Define a Sitemap entry for the page.
2. Create the View. A view is nothing but a HTML page sprinkled with directives where dynamic contents should be inserted.
3. Create the logic in a Snippet, a Scala class or object that will transform the view HTML into a dynamically generated HTML which is what is sent back as HTTP response.

Like rails, Lift works on convention as opposed to customization. It expects certain things in pre defined locations. For example, the View HTML files are expected in the webapp folder under the src tree, Convention over customization makes it easier to develop applications. The best way to get started with Lift is to use one of the pre-defined templates to create the directory for your project. Alternately, if you are using Maven, another way to get started is to use a Maven archetype (e.g. lift-archetype-basic).

Once the directory structure is created, we will start by defining the sitemap for our web application. For this simple interface we will have only one page. This page will become the “Home” page for the application. We will make an entry for the home page in the sitemap. Every Lift application calls a Boot class when it starts the Boot class is defined in the bootstrap.liftweb package and its called Boot.scala. Here is the code for Boot.scala –

package bootstrap.liftweb

import _root_.net.liftweb.common._
import _root_.net.liftweb.http._
import _root_.net.liftweb.http.provider._
import _root_.net.liftweb.sitemap._
import _root_.Lift.model._

/**
 * A class that's instantiated early and run.  It allows the application
 * to modify lift's environment
 */
class Boot {
  def boot {
    // where to search snippet
    LiftRules.addToPackages("Lift")

    // Build SiteMap
    def sitemap() = SiteMap(
      Menu("Home") / "index"
    )

    LiftRules.setSiteMapFunc(() => sitemap())
    /*
     * Show the spinny image when an Ajax call starts
     */
    LiftRules.ajaxStart =
      Full(() => LiftRules.jsArtifacts.show("ajax-loader").cmd)

    /*
     * Make the spinny image go away when it ends
     */
    LiftRules.ajaxEnd =
      Full(() => LiftRules.jsArtifacts.hide("ajax-loader").cmd)

    LiftRules.early.append(makeUtf8)
  }

  /**
   * Force the request to be UTF-8
   */
  private def makeUtf8(req: HTTPRequest) {
    req.setCharacterEncoding("UTF-8")
  }
}

Boot class provides an entry point into our web application. This is where all the configuration that is needed for the web application is done. Lift provides a LiftRules Singleton for holding the rules for the web application.  In this example, we define a sitemap function and register the function with the LiftRules Singleton. The Sitemap function will be invoked as needed. This function will return a Sitemap object that could be made up of several Menu items. A menu item  has a Loc (pronounced as “loke”) object, that specifies the location of the menu (the link that will be hit on the server side) and a list of sub menus. In the case above, the only menu item is the “Home” Page, which links to index.html file  specified by the Loc. We also define a ”spinning” image that will show up when an Ajax command starts. The image disappears upon the completion of the Ajax command.

That is pretty much it for the sitemap and the boot process.

Next we will look at the View class which is nothing but a HTML template that feeds into a Snippet class to get converted into the final HTML page for rendering on the browser. Here is the code for the index.html.

<div class="lift:surround?with=default;at=content">
    <h2>Welcome to Virtual Queue!</h2>
    <div class="lift:comet?type=TokenObserver">
        Next available Number is <span id="token">The next token</span>
    </div>
    <form class="lift:form.ajax">
        <div class="lift:TokenDispenser">
            <span class="lift:Msg?id=myToken">Token Number</span><br/>
            <span id="hidden"></span>
            <input type="submit" value="Get the next Token"/>
        </div>
    </form>
</div>

This looks like a regular HTML page and it is one; except if you notice the page has several <div> tags with class attributes whose value starts with the string “lift:”. This is where Lift will inject the Scala code in order to get the dynamic content for the web page.
The first such Snippet that is listed on the page is “lift:surround?with=default;at=content”. What this is telling Lift is to surround this element with a template called default.html; that is, by convention, located in the templates-hidden folder. The directive for the snippet is to wrap this element with the default.html by inserting the contents of this element at the element with id “content” in default,html. This allows us to wrap a common template around our pages. However, Lift is flexible and also allows us to select different templates for surrounding our code. A template can further be decorated by other templates.
The next class that calls a Snippet is “lift:comet?type=TokenObserver”, we will come to this in a minute. But first lets consider the form that is part of this view. The form is an Ajax form, the class “lift:form.ajax” is a built in snippet that comes with Lift and it converts a form into an Ajax form so that the entire page is not loaded when the submit button is pressed. In Lift a form is backed up by a function value that is associated with a unique ID that is assigned to the form. What does this mean? Well in Scala, functions are first class citizens and like an imperative language such as Java where, for example, class members are first class citizens, in Scala functions have the same power. Which means that we can take a function and pass it along just like we pass arguments to a method.
In case of forms, what ends up happening is that each rendered form is given a unique ID (called GUID). Associated with this ID is a function which gets invoked by the Lift Framework when the form is submitted back. Lift maintains the association between the form’s GUID and the function value. So when the form is submitted back to the server, it knows which function to invoke to fulfill the request. What this also implies is that once a page is rendered by an instance of a server, the session needs to stick to that server instance only. In a traditional MVC web framework this could lead to scaling issues, however, since Lift uses the light weight Actor model, it is claimed that scaling is not an issue. You can read more about this on the net.  So, if there are 100 forms opened on 100 different web browsers, each will have a different ID associated with it and each will invoke its instance of the function on the server when it is submitted back.
So the form.ajax snippet does the following, it takes the index.html and puts a unique ID on that form. The rendered HTML ends up looking something like this:
</pre>
<form id="F6959200839461HR513" action="javascript://" onsubmit="liftAjax.lift_ajaxHandler(jQuery('#'+&quot;F6959200839461HR513&quot;).serialize(), null, null, &quot;javascript&quot;);return false;">
 <div>
 <span id="myToken"></span><br />
 <input id="hidden" value="true" name="F695920083947LKXWTQ" type="hidden" />
 <input value="Get the next Token" type="submit" />
 </div>
 </form>
<pre>
The id=”F6959200839461HR513″ is what Lift adds to the form. When the form is submitted to the server, a new ID is assigned to the form. This is cool because once a form is served, its no longer valid and a form with new ID is rendered back. This is the key mechanism how Lift can prevent against CSRF attacks.
As part of building out the page, our snippet that was added as <div class=”lift:TokenDispenser”> will be invoked. The code for this snippet is as follows.
package Lift.snippet

import Lift.model.AQueue
import net.liftweb._
import http._
import util.Helpers._
import js._
import JsCmds._
import Lift.comet.TokenRefresher

object TokenDispenser {
    def render = {

    // our process method returns a
    // JsCmd which will be sent back to the browser
    // as part of the response
    def process() : JsCmd= {
      S.notice("myToken", "Your token Number is: "+AQueue.tokenDispenser.dispense.toString)
      TokenRefresher ! "R"
      Noop
    }

    // binding looks normal
    "#hidden" #> SHtml.hidden(process)
  }
}

This code is simple and all it does is it calls the CSS selector transform on a field whose id is “hidden”. We had to add a hidden field to our form because the submit button is not serialized over Ajax, and we need a mechanism to invoke the underlying function when the form is submitted. The function that we attach to the hidden element (which will get a unique ID as well, each time it is rendered), is called “process”. We attach this process via SHtml.hidden method. The SHtml.hidden method does two things, one it transforms the <span> element with id “hidden” in the source HTML template into a input field of type “hidden”. It also assigns a unique ID to this hidden input field and associates the process method with this ID. When the form is submitted back, the process method associated with this ID is invoked and it does the following, it gets the ONLY token dispenser we have in the system so far to dispense the next token. It then sets the NOTICE notice on the current response noting the next token number that was dispensed. This method then sends a message to the TokenRefresher object which we will see in a minute notifying it that a new token was dispensed. It returns a Noop Java Script command to the browser which basically does nothing.
How to simultaneously update all the browsers with the next available token number
OK now lets see how we will be able to update all the browsers that are watching the same token dispenser. This is a classic problem that can be solved in one of these ways,

We put an ajax periodical updater that periodically polls the server for the latest token number that can be dispensed from our dispenser. The problem with this approach is that there might be a little lag between when a token gets dispensed and when all the web pages get updated. It might lead to confusion for the user requesting a token as they might get a different token number from what they were expecting.
Or we can use a long polling mechanism such as comet where a long-held HTTP request lets the web server push out data to the browsers without the browser explicitly requesting it.
Use HTML 5 push notification technology.

For now we will see how to achieve this using the comet support along with the Actors threading model that comes built in with the Lift framework. If time permits we will delve into the HTML 5 solution later. We have already seen the power of the Actors model in our previous blog. Lets now see the Comet support in Lift using this model.
Let us go back to the view definition one more time and consider the <div> with the following class – <div class=”lift:comet?type=TokenObserver”>. The built in “comet” snippet will be invoked when Lift encounters this class. The Comet Snippet will look for an Actor called TokenObserver. This needs to be a special kind  of actor – a CometActor. Whenever the state of the CometActor changes it will push those changes out to the browsers. Here is the code for TokenObserver.
package Lift.comet

import Lift.model.AQueue
import net.liftweb.http.{CometListener, CometActor}

/**
 *
 * User: Anupam Chandra
 */

class  TokenObserver extends CometActor with CometListener {
  private var nextTokenNumberToBeDisplayed = AQueue.tokenDispenser.peek

  // Register with TokenRefresher
  def registerWith = TokenRefresher

  override def lowPriority = {
    case i: Int => nextTokenNumberToBeDisplayed = i;reRender()
  }

  def render = {
    "#token *" #> nextTokenNumberToBeDisplayed
  }
}

Since TokenObserver is a CometActor, it needs to provide mechanism for handling messages. The lowPriority method provided by this class does exactly that – it does a pattern match on the integer that comes in as a message, takes that integer as the next available token number, updates its state and calls the reRender method. The reRender method uses CSS transformation to modify the Element with id “token”.
So who sends out messages to the TokenObserver? The TokenObserver is also a CometListener and it registers itself with a TokenRefresher object. TokenRefresher is a Singleton object for now that will notify all its listeners whenever someone requests a token. The code for TokenRefresher is as follows:
package Lift.comet

import net.liftweb.actor.LiftActor
import net.liftweb.http.ListenerManager
import Lift.model.AQueue

/**
 *
 * User: Anupam Chandra
 */

object TokenRefresher extends LiftActor with ListenerManager {

  /* When we update the listeners we send the next available token
   */
  def createUpdate = AQueue.tokenDispenser.peek

  override def lowPriority = {
    case "R" => updateListeners()
  }
}

The code is very simple. Our TokenRefresher is an Actor, a LiftActor that we can send messages to. For now its a Singleton Object since we have only one TokenDispenser in our system. It’s also a ListenerManager so all the TokenObservers can register themselves with it. When ever someone requests for a new Token, the method registered as part of the TokenDispenser render method, the “process” method is invoked. This method does two things as we have seen before, it will dispense a token and it ALSO sends a message to the TokenRefresher. For now it just sends a simple string “R” as a message. This is sufficient to inform the TokenRefresher that someone just got a new token and that the TokenRefresher should update all its registered listener TokenObservers; which it does by calling updateListeners method. The updateListener method in turn uses the createUpdate method to create the actual update it will send to its observers. Remember that the TokenObservers are themselves actors and so they can accept messages, which is what the TokenRefresher does. It sends all its observers the createUpdate message. We have already seen how the lowPriority method of TokenObserver class will handle this message. This way whenever anyone requests a token all the other interested parties will get automatically updated with the next token number that will be dispensed next.
Conclusion
That about does it for today’s blog. We created a fully functional, multi-threaded, full duplex communication based web interface that takes care of all the top OWASP security threats such as XSS, CSRF etc. in about 60 lines of code. Next we will develop a mobile interface for our TokenDispenser.
			

Tokens and TokenDispenser

The NumberDispenser developed so far is a generic object that dispenses numbers. In and of itself, it does not relate directly to the problem at hand. We need to encapsulate it as part of domain objects that are more natural for the Virtual Queuing application that we are developing.

In today’s blog we will introduce two such domain objects that make more sense in our domain. We will show how to create relationships between these objects and how to use fine grained access modifiers to control the visibility and ownership of these objects.

A Token is something that you take when you get in a queue. A Token usually has a number that is used to call out which token is being served. The TokenDispenser dispenses tokens. Let’s see the modified class –

package com.scoovyfoo.domobj

import actors.Actor
import actors.Actor.self

class TokenDispenser(startingNumber: Int) {
  NumberDispenser.start()

  private object NumberDispenser extends Actor {
    private def numberStream(num: Int): Stream[Int] = num #:: numberStream(num + 1)

    private var nextNumberStream = numberStream(startingNumber)

    def act() {
      loop {
        react {
          case ("DISPENSE", actor: Actor) => {
            actor ! nextNumberStream.head
            nextNumberStream = nextNumberStream.tail
          }
          case ("RESET", resetTo: Int) => nextNumberStream = numberStream(resetTo)
          case ("PEEK", actor: Actor) => actor ! nextNumberStream.head
        }
      }
    }
  }

  case class Token private[TokenDispenser](number: Int) {
    private[TokenDispenser] def copy: Token = throw new Error
  }

  def reset(resetTo: Int) = {
    NumberDispenser !("RESET", resetTo)
    this
  }

  def dispense: Token = {
    NumberDispenser !("DISPENSE", self)
    self.receive {
      case nextNum: Int => Token(nextNum)
    }
  }

  // Just peeks at the next number without getting it
  def peek: Int = {
    NumberDispenser !("PEEK", self)
    self.receive {
      case nextNum: Int => nextNum
    }
  }

}

Our NumberDispenser class has no use outside of the TokenDispenser class. So the first thing we will do is to make the NumberDispenser class a private inner (or nested class) of TokenDispenser. Since the class is a private class of the TokenDispenser class, it can only be used by the TokenDispenser class.

Next we create a Token class as an inner class of TokenDispenser. We make Token a case class. A case class in scala is a special type of class for which the compiler produces a lot of supporting code under the hood. An important piece of this generated code allows us to do pattern matching on objects of case classes without having to write any boiler plate code to compare two tokens. We will need token comparison later in the system so it makes sense for Token to be a case class. Besides enabling pattern matching the Scala compiler also generates code that makes it very convenient to use case classes

1. It generates a factory method with the name of the class. So we can use Token(5) for creating a token object instead of the slightly longer new Token(5). So in the dispense method we create the Tokens by using just its compiler generated factory method.

     def dispense: Token = {
       NumberDispenser !("DISPENSE", self)
       self.receive {
         case nextNum: Int => Token(nextNum)
       }
     }
   	

2. The compiler also makes all the class parameters listed with the Token class as fields of the class. So they are available for us to consume later. For example, number automatically becomes a val numberfield and we can easily access it later. In the code snippet below from our test case, we are accessing the number field directly.

    test("dispense") {
       assert(1304 == tokenDispenser.dispense.number)
       assert(1305 == tokenDispenser.dispense.number)
       assert(1306 == tokenDispenser.dispense.number)
   
       for (i <- 1307 to 101307)
         assert(i == tokenDispenser.dispense.number)
     }
   

3. The compiler adds an natural implementation of the toString, hashCode and equals method. This is convenient if we want to print, hash and compare two objects of a case class.
4. Finally the compiler also adds a copy method for the class. This method is convenient if we need to make a copy of the object that looks exactly same as the original object but differs in one or two fields.

Now lets discuss the reason for making the case class an inner class of TokenDispenser. We do not want Tokens to be created anywhere else in the system but by only a TokenDispenser. Such restriction is possible only by restricting the access to the primary constructor for our Token class to its dispenser. This is achieved by making the Token class an inner class of TokenDispenser AND by modifying the primary constructor to be private with access up to its enclosing class “TokenDispenser”. Scala allows the access modifiers to be qualified by putting the qualifiers in square brackets and that is what we are doing when we make the primary constructor for the Token class private up to the TokenDIspenser class by listing it as private[TokenDispenser]. Also note that since Scala’s compiler automatically generates the primary constructor, the only way to specify this restriction is by adding it to the definition of the Token class as can be seen below. Now if any code outside of the TokenDispenser class tries to instantiate a Token object they will get a compilation error.

  case class Token private[TokenDispenser](number: Int) {
    private[TokenDispenser] def copy: Token = throw new Error
  }

For example if we add the following code to our test class:

val t = tokenDispenser.Token(5)

We will get this error

TokenDispenserTest.scala:94: error: constructor Token in class Token cannot be accessed in class TokenDispenserTest
[INFO]     val t = tokenDispenser.Token(5)

The only other item of interest in this Token class is the copy method. Remember a case class automatically generates a copy method and makes it public. So even though we went through all the trouble to make the constructor private, any one can call the copy method and get a fresh new copy of the the Token class. In order to prevent that, we are explicitly providing a copy method that is both private up to the TokenDispenser class and not only that it throws an Error. So if we were to add the following code to our test case –

val t2 = t.copy (number = 4)

We will get the following error –

[ERROR]TokenDispenserTest.scala:101: error: value copy is not a member of TokenDispenserTest.this.tokenDispenser.Token
[INFO]     val t2 = t.copy (number = 4)

Testing

Here is the modified test case to test our TokenDispenser and Token class. It is similar to the NumberDispenser test class except we have modified the multithreaded test case to asset that we do not have duplicated numbers in any Token even though multiple threads might be requesting tokens from the same dispenser at the same time.

package Scala.com.scoovyfoo.domobj

import org.scalatest.{BeforeAndAfter, FunSuite}
import org.scalatest.junit.JUnitRunner
import org.junit.runner.RunWith
import actors.Actor._
import actors.Actor.self
import actors.Actor
import com.scoovyfoo.domobj.TokenDispenser

/**
 *
 * User: Anupam Chandra
 */

@RunWith(classOf[JUnitRunner])
class TokenDispenserTest extends FunSuite with BeforeAndAfter {
  private val tokenDispenser = new TokenDispenser(100)

  before {
    tokenDispenser.reset(1304)
  }

  test("dispense") {
    assert(1304 == tokenDispenser.dispense.number)
    assert(1305 == tokenDispenser.dispense.number)
    assert(1306 == tokenDispenser.dispense.number)

    for (i <- 1307 to 101307)
      assert(i == tokenDispenser.dispense.number)
  }

  test("reset") {
    assert(1 == tokenDispenser.reset(1).dispense.number)
    assert(2 == tokenDispenser.dispense.number)
    assert(3 == tokenDispenser.dispense.number)
  }

  test("MultiThreaded") {
    import collection.mutable.Map

    val aMap: Map[tokenDispenser.Token, String] = Map()
    // Create the first thread and make it start by sending a message of type tuple that has the "START" string and
    // the requesting thread
    val actorOne = actor {
      react {
        case ("START", requester: Actor) => {
          //
          for (i <- 1 to 100) {
            requester ! (tokenDispenser.dispense, "ActorOne" )
          }
          requester ! "EXIT"
        }
      }
    }
    // Create the second thread and start it just like the first thread
    val actorTwo = actor {
      react {
        case ("START", requester: Actor) =>{
          for (i <- 1 to 100) {
            requester ! (tokenDispenser.dispense, "ActorTwo")
          }
          requester ! "EXIT"
        }
      }
    }

    actorOne ! ("START", self)
    actorTwo ! ("START", self)
    var numActorsRunning = 2

    do {
      receive {
        case "EXIT" => numActorsRunning -= 1
        case (t: tokenDispenser.Token, s: String) => {
          intercept[NoSuchElementException] {
            try{aMap(t)} catch {case ex:NoSuchElementException => {aMap += (t -> s); throw ex} }
          }
        }
      }
    } while (numActorsRunning > 0)

    assert(200 == aMap.size)

  }

  test("Peek") {
    assert(1304 == tokenDispenser.peek)
    assert(1304 == tokenDispenser.peek)
    assert(1304 == tokenDispenser.peek)
    assert(tokenDispenser.dispense != tokenDispenser.dispense)
    assert(1306 == tokenDispenser.peek)
    val actorTwo = actor {
      tokenDispenser.dispense
      tokenDispenser.dispense
      tokenDispenser.dispense

    }
    // Let the other thread finish so sleep for a while.
    Thread.sleep(100)
    assert(1309 == tokenDispenser.peek)
  }

}

Consider the “multi threaded” test case. In previous blogs we were just printing out the numbers from multiple threads and then manually validating that no two numbers were duplicates. In this modified test case, we are using another Scala provided collections data structure called Map. A Map correlates a key to a value. We will use the token  as the key and a made up thread name as the value.  We start multiple threads, each taking a token from the same token dispenser and passing it back to us. Once we get the token from either of the thread, we look in our Map to see if that token exists in the map or not. It should not if our TokenDispenser is thread safe. So in every case, when we check for existence of a token in the map class, we expect a NoSuchElementException. When we do get that exception, we catch it and add the token along with the thread name  to the map a re-throw the exception. ScalaTest provides a convenient mechanism of listing that we are expecting an exception. It does that by providing an intercept method that we create by parameterizing it on the NoSuchElementException and passing a function value as its argument. The intercept method will ensure that the exception is thrown, if not it will fail the test case.

Our previous version of this test case, simply started the two actors and all they did was request a number from the number dispenser and printed that number out. However, this modified version of the test case, actually passes the token back to the thread that started it; in this case, the thread that is running the test case. The way this communication happens is via passing messages between the originating test thread and the actor threads. The originating thread after creating the actors sends a “START” message to them. It also sends a self reference to them which is then used by the worker threads to pass back the token that they got. Once the worker threads are done with their loop, they send an “EXIT” message back to the originating thread. When the originating thread gets all EXITS, it comes out of its reveive loop ending the test case.

There are two types of messages that the originating thread can handle, an EXIT message and a message that passes the token along with the thread name back. We match the correct message and if the message is of latter type we check in the map to see it the token that we received exists in the map, it should not and so we insert it. Since our Token class is a case class it makes it easy to do pattern matching and equality check in the map.

Note that we are using a mutable map. By default Scala provides an immutable map, but that is of limited value for us since we are going to request hundreds of token and we need to add them to the map as they arrive. A mutable map allows us to do just that.

Conclusion

In this blog we introduced domain objects that are more meaningful for the problem we are solving and provide the correct abstraction. We saw how to restrict the scope of a class and how to use correct access modifiers to restrict the use of these classes.

At this point we are ready to put an interface on to our Token Dispenser. We will start with a simple web interface and then add other interfaces such as mobile interfaces for both iOs and Androis.

Thread Safe Number Dispenser

The NumberDispenser class that we introduced in the previous blogs works fine for a single thread. However, if multiple threads start requesting for numbers, there is a possibility that two threads might get the same number. The problem is that while a thread is in the dispense method it might be preempted  right after it figures out what is the next number to be dispensed.

  def dispense: Int = {
    val nextNum = nextNumberStream.head
    // Thread might be preempted right here ...
    nextNumberStream = nextNumberStream.tail
    nextNum
  }

To illustrate the problem, lets make the thread sleep right where we suspect that the thread might be preempted.

  def dispense: Int = {
    val nextNum = nextNumberStream.head
    Thread.sleep(10)
    nextNumberStream = nextNumberStream.tail
    nextNum
  }

In order to test out our theory, we will add another test case to our ScalaTest test suite and run multiple threads in that test case, each thread asking the same NumberDispenser to dispense a number. In the spirit of this blog we will use Scala’s Actors model to achieve this. Actors are thread-like entities that can be viewed as concurrent processes that communicate with each other exchanging messages. Each actor runs in its own thread. For this test case, we do not have a need for the threads to communicate with each other just the need for them to run concurrently sharing the same NumberDispenser and asking it to dispense a number. We are going to see that since we have introduces a sleep, in the dispense method, the likelihood of one of the actor thread getting preempted increases. We will see that the two threads will  get the same number in this case. Clearly this is not desirable.

The new test case looks like this –

  import actors.Actor
  test("multithreaded") {
    val a = new NumberDispenser(100)
    object actorOne extends Actor {
      def act() {
        for (i <- 1 to 100)
          println("ActorOne => " + a.dispense)
      }
    }
    object actorTwo extends Actor {
      def act() {
        for (i <- 1 to 100) {
          println("ActorTwo => " + a.dispense)
        }
      }
    }
    actorOne.start();
    actorTwo.start();
  }

This test case is simple. We create a single NumberDispense as “val a”. A val in Scala stands for value (I guess) and is similar to a final variable in Java. Once a value is assigned to a val, it cannot be changed. We create two actors in this test case. These actors are standalone objects that extend a trait called Actor. An object in Scala is a singleton. Meaning that only one instance exists. In the above example, there is a single actorOne and a single actorTwo instance. That is all we need in this case.  An Actor’s behavior is specified by defining its <em>act</em> method as we are doing above. The code inside the <em>act</em> is simple. Each thread will loop 100 times asking for a number from the shared NumberDispenser. For simplicity we just print out the number along with the name of the thread. We start the thread for the actor by calling its “<em>start</em>” method. The output looks like this –

ActorTwo => 100
ActorOne => 100
ActorOne => 102
ActorTwo => 102
ActorTwo => 103
ActorOne => 103
ActorTwo => 104
ActorOne => 104
ActorTwo => 105
ActorOne => 105
ActorTwo => 107
ActorOne => 107
ActorTwo => 109
ActorOne => 109
ActorOne => 110
ActorTwo => 110
ActorOne => 111
ActorTwo => 111
ActorOne => 112
ActorTwo => 112
ActorTwo => 113
ActorOne => 113
ActorOne => 114
ActorTwo => 114
ActorTwo => 115
ActorOne => 115
ActorTwo => 116
ActorOne => 116
ActorTwo => 117
ActorOne => 117
ActorOne => 118
ActorTwo => 118
...

As we can see that the threads get the same number. This needs to be fixed.

One way of fixing this problem and making the NumberDispense thread safe is to use the typical Java threading model based on shared data and locks. Basically we will synchronize the access to the code that dispense a number and that will fix this issue. Here is the modified code.

  def dispense: Int = synchronized {
    val nextNum = nextNumberStream.head
    Thread.sleep(10)
    nextNumberStream = nextNumberStream.tail
    nextNum
  }

Now the threads don’t get same number.

ActorOne => 100
ActorTwo => 101
ActorOne => 102
ActorTwo => 103
ActorOne => 104
ActorTwo => 105
ActorOne => 106
ActorTwo => 107
ActorOne => 108
ActorTwo => 109
ActorOne => 110
ActorTwo => 111
ActorOne => 112
ActorTwo => 113
ActorOne => 114
ActorTwo => 115
ActorOne => 116
ActorTwo => 117
ActorOne => 118
ActorTwo => 119
ActorOne => 120
...

The shared data and lock approach has several documented issues such as possibility of causing a deadlock or getting into a race condition. It makes it harder for developers to develop working thread safe code using the shared data and lock strategy.

Scala provides the Actor model that makes it easy to develop thread safe applications that makes it easier to develop a multi threaded application. Let us see how to go about converting our simple NumberDispenser to make it into an actor. Here is the modified source code.

import actors.Actor

class NumberDispenser(startingNumber: Int) extends Actor {
  private def numberStream(num: Int): Stream[Int] = num #:: numberStream(num + 1)

  private var nextNumberStream = numberStream(startingNumber)

  // Methods of this class
  def act() {
    loop {
      react {
        case ("DISPENSE", requester: Actor) => {
          requester ! nextNumberStream.head;
          nextNumberStream = nextNumberStream.tail
        }
        case ("RESET", resetTo: Int) => nextNumberStream = numberStream(resetTo)

        case ("PEEK", requester: Actor) => requester ! nextNumberStream.head
      }
    }
  }
}

First thing that we do is to mix in the Actor trait into our NumberDispenser class. This is similar to what we did for the test case earlier when we extended it to create a multi threaded test case. We saw that we have to define the act method to make our actor behave. Actors communicate with each other using messages. An actor never blocks when it is sending a message and it cannot be interrupted while it is servicing a message. When a message arrives the actor can either receive the message by calling the receive method or can react to it by calling the react method. The difference between the two is that receive method returns from the call (possibly returning a value), react does not return after the call. Its return type in Scala is Nothing which indicates that a method will return abnormally and there is no need to maintain the stack trace of the thread. This implies that the same thread can potentially be used for the next actor that wakes up making this approach very effective.

So we are using the react method to react to the messages that will arrive at the NumberDispenser actor’s “mailbox”. The react and receive methods expect what are called partial functions as its argument. A partial function is the one that provides implementation for only some of the cases. In the example above of all the possible messages that can arrive at the door of our NumberDispenser Actor, its react method can only handle three kinds of messages. If a different type of message shows up in NumberDispenser’s mailbox, it will be ignored  and the next invocation of react method will handle the next message in the  mail boxes queue.

The three kinds of messages that can be handled by our Actor are listed as three case statements. A case statement can pattern match the message that arrives in mailbox and if the message matches its argument, it calls the body of code after the => operator.

The three messages that NumberDispenser can handle are

1. A tuple that has 2 elements, a token string “DISPENSE” and the actor that made the request.
2. A tuple that has 2 elements, a token string “RESET” and a number to reset the NumberDispenser to
3. A tuple that has 2 elements, a token string “PEEK” and the actor that made the request.

Why are we passing the thread that made the request as part of the message. Remember that the react method does not return, so the partial function that is passed to it needs to do all the remaining work for the actor. In the case of DISPENSE and PEEK messages, our actor needs to reply back to the requesting thread with an answer and it does that by sending back a message to the requesting thread. That brings us to the interesting question that we have been talking along, how do you send a message to an actor. In Scala you use the ! operator to send a message. So in the example above “requester ! nextNumberStream.head” sends the element sitting at the head of the number stream to the requester. We will see how the requester will use this information next when we write the test case for testing this new thread safe NumberDispenser. For now, let’s just look at the loop that encloses out react method for the actor. Why do we have a loop? Remember that the react method does not return after it services the message, however we want to be in a continuous reactionary mode to service messages as they arrive. For this pattern, Scala provides a coding paradigm where loop method repeatedly executes the block passed to it. This works perfectly in our case because we do want an unending supply of numbers for our virtual queuing system.

So now let us change our test cases to make use of this new thread safe NumberDispenser. Here is the modified code for our test cases.

First, the ScalaTest case

import org.scalatest.{BeforeAndAfter, FunSuite}
import org.scalatest.junit.JUnitRunner
import org.junit.runner.RunWith
import actors.Actor
import actors.Actor.self

@RunWith(classOf[JUnitRunner])
class NumberDispenserSuiteTest extends FunSuite with BeforeAndAfter {
  private val numberDispenser = new NumberDispenser(100)
  numberDispenser.start()

  before {
    numberDispenser ! ("RESET", 200)
  }

  test("dispense") {
    numberDispenser ! ("DISPENSE",self)
    assert(200 == self.receive {case nextNum:Int => nextNum})
    numberDispenser ! ("DISPENSE",self)
    assert(201 == self.receive {case nextNum:Int => nextNum})
    numberDispenser ! ("DISPENSE",self)
    assert(202 == self.receive {case nextNum:Int => nextNum})
  }

  test("peek") {
    numberDispenser ! ("PEEK",self)
    assert(200 == self.receive {case nextNum:Int => nextNum})
    numberDispenser ! ("PEEK",self)
    assert(200 == self.receive {case nextNum:Int => nextNum})
    numberDispenser ! ("DISPENSE",self)
    numberDispenser ! ("DISPENSE",self)
    self.receive {case nextNum:Int => nextNum}
    self.receive {case nextNum:Int => nextNum}
    numberDispenser ! ("PEEK",self)
    assert(202 == self.receive {case nextNum:Int => nextNum})
  }

  test("reset") {
    numberDispenser ! ("PEEK",self)
    assert(200 == self.receive {case nextNum:Int => nextNum})
  }

  test("multithreaded") {
    val a = new NumberDispenser(100)
    val actorOne = actor {
        for (i <- 1 to 100){
          numberDispenser ! ("DISPENSE",self)
          println("ActorOne => " + self.receive {case nextNum:Int => nextNum})
        }
    }
    val actorTwo = actor {
        for (i <- 1 to 100) {
          numberDispenser ! ("DISPENSE",self)
          println("ActorTwo => " + self.receive {case nextNum:Int => nextNum})
        }
    }
  }
}

And next the specs test case

import org.specs._
import actors.Actor._

class NumberDispenserExperimentTest extends SpecificationWithJUnit  {
  private val numberDispenser = new NumberDispenser(200)
  numberDispenser.start()

  "Number Dispenser" should {
    "dispense numbers in a sequential order" in {
      numberDispenser ! ("DISPENSE",self)
      numberDispenser ! ("DISPENSE",self)
      self.receive {case nextNum:Int => nextNum} must_== 200
      self.receive {case nextNum:Int => nextNum} must_== 201
    }

    "allow us to reset it to any number. It should then dispense numbers from that number onwards" in {
      numberDispenser ! ("PEEK",self)
      self.receive {case nextNum:Int => nextNum} must_==200
      numberDispenser ! ("RESET",100)
      numberDispenser ! ("PEEK",self)
      self.receive {case nextNum:Int => nextNum} must_== 100
    }

    "let us peek at the next number without dispensing or advancing to the next number" in {
      numberDispenser ! ("PEEK",self)
      self.receive {case nextNum:Int => nextNum} must_== 200
      numberDispenser ! ("PEEK",self)
      self.receive {case nextNum:Int => nextNum} must_== 200
      numberDispenser ! ("PEEK",self)
      self.receive {case nextNum:Int => nextNum} must_== 200
    }
  }

}

The main change that we had to make in order to use the modified thread safe class was that instead of invoking the methods of the NumberDispenser class directly we will have to send messages to the Actor NumberDispenser. This actor is created inside of the test case and it is started using the start method. The start method will ensure that some thread calls the act method of NumberDispenser. At that point the act method will invoke react method that will wait for a message to arrive. If the message matches the type of messages that the partial function passed into the react method can handle, the react method will schedule the execution of the body of the partial function and it will throw an exception. The thread that called the react method will catch the exception and move on to other things. In the test case we pass the messages that can be handled by our Actor. These being the three tuples.

The NumberDispenser actor will in turn react to the message that are passed by the test thread, if the message requires a return value, the NumberDispenser method will send the return value back to the test thread as a message. Notice that after sending the message to retrieve the next number is sent to the NumberDispenser actor, the test thread immediately calls receive using self reference. It passes the partial function to the receive method of the test thread. The partial function can handle message of just one type – Int; which is what is sent in the message by the NumberDispenser thread.

Conclusion

In today’s blog we converted our simple NumberDispenser into a thread safe version. Next we will introduce another domain object – Token and TokenDispenser and see how a TokenDispenser will use the NumberDispenser class to hand out Tokens. In developing this we will learn about scope and object visibility.

Stream of numbers

In the previous blog we created a NumberDispenser class that dispenses numbers to its clients. It has a counter that keeps track of the next number to dispense. In this blog we will explore an alternate mechanism for handing out these numbers. The idea of this blog is to learn the Scala language and although the precious version of the NumberDispenser serves the purpose, let us investigate if there is any other way to get this functionality implemented in Scala.

Remember the goal of NumberDispenser is to keep handing out the next available number. In a way, it needs to have a steady stream of numbers to hand out.  Scala provides a data structure from its collections library that fits in here perfectly. The data structure is called Stream and it’s a List except that it’s a lazy list which means that all the elements of Stream are not evaluated right away. They are evaluated only when they are needed. This fits our need perfectly since we need to evaluate the next number to hand out only when someone requests that number. Let’s see how this is implemented –

class NumberDispenser(startingNumber: Int) {
  private def numberStream(num: Int): Stream[Int] =
    num #:: numberStream(num + 1)

  private var nextNumberStream = numberStream(startingNumber)

  // Methods of this class
  def dispense: Int = {
    val nextNum = nextNumberStream.head
    nextNumberStream = nextNumberStream.tail
    nextNum
  }

  def reset (resetTo: Int) {nextNumberStream = numberStream(resetTo)}
  def peek = nextNumberStream.head
}

We got rid of the counter from the previous version and replaced it with a number stream instead. This number stream is served by the method numberStream which returns a Stream where only the head of the stream is evaluated, the tail of the stream is not evaluated right away. If we examine the numberStream method it states that our stream is a sequence of numbers starting at num and the rest of the sequence is the stream that starts at num + 1. Such a sequence is created using the #:: operator which works by not evaluating the right hand side of the expression until it is requested. The right hand side is only requested when someone calls the dispense method at which point, the tail of the stream starting at num+1 needs to become the new stream. This cycle will continue as dispense method is called.

Testing

The same test cases from the previous blog will work for this class since we did not modify the behavior of the class we just changed the inner workings. That is the beauty of Scala, it provides the best of both worlds – Object Oriented as well as functional programming. However, lets take this opportunity to introduce “Behavior Driven Design” using Scala specs framework. Here is the source code for the test case. We will discuss the test case in a minute.

import org.specs._
import runner.ScalaTest
import org.junit.runner.RunWith
import org.scalatest.junit.JUnitRunner

@RunWith(classOf[JUnitRunner])
class NumberDispenserExperimentTest extends Specification with ScalaTest {
  private val numberDispenser = new NumberDispenser(200)

  "Number Dispenser" should {

    "dispense numbers in a sequential order" in {
      numberDispenser.dispense must_== 200
      numberDispenser.dispense must_== 201
    }

    "allow us to reset it to any number. It should then dispense numbers from that number onwards" in {
      numberDispenser.peek must_== 200
      numberDispenser.reset(100)
      numberDispenser.peek must_== 100
    }

    "let us peek at the next number without dispensing or advancing to the next number" in {
      numberDispenser.peek must_== 200
      numberDispenser.peek must_== 200
      numberDispenser.peek must_== 200
    }
  }

}

The specs framework allows us to define the specification for our system. You define the specification using a declarative syntax as shown in the above example.  We start by extending the Specification class to create our own specification for the system. Inside our specification class we write the specification as a string and use the keywords, “should”, “can” etc. For example, “Number  Dispenser” should {…}. What is happening in this case is that the string “Number Dispenser” is being converted automatically to a type that supports the  “should” method. The technique used in this case is called implicit conversion. If the Scala compiler comes across something that it cannot resolve on the default object type i.e. it gets a type error, it will look for a user defined implicit conversion from the default type to another type that could be used to resolve the error. In the case above, the specs framework defines an implicit conversion from String to a type that can handle the “should” method.

Once the specification is described for a system, you can define examples of the specification inside the body of should followed by the keyword “in”. Again, specs framework is providing implicit conversions from String type to a type that supports the “in” method. Once the examples have been listed, they can be backed with expectations and that is what is provided inside the curly braces following the “in” keyword. The “expectations” are what the specs framework will use to test if the functionality is correctly implemented by the system.

Executing the tests

Executing the test case is similar to how we executed the ScalaTest in the previous blog. We used the JUnitRunner that comes with ScalaTest framework and we use the RunWith annotation provided by JUnit 4. The only additional thing we need to do here is to mix in the ScalaTest trait along with the Specification trait.

Another way to execute a specs test if we mix in SpecificationWithJUnit trait. instead of just the Specification trait like this.

class NumberDispenserExperimentTest extends SpecificationWithJUnit  {

Conclusion

In today’s blog we discovered another way of serving numbers using a Scala Stream, a lazily evaluated list class that provides a capability of infinite numbers without computing all of them upfront. As the numbers are requested they are handed out.

In the next blog we will see how to make the NumberDispenser thread safe using Scala’s Actor model.

Virtual Queues on Scala, Groovy and Ruby

Polyglot Learning

We are going to learn Scala, Lift, Groovy, Grails, Ruby and Rails, iPhone and Android app development using a simple application.

We will develop a virtual queuing application. When you go to a post office or to DMV, you have to take a number token that places you in a queue. The people providing the service , call out the next number that they can service and the queue moves forward and eventually your turn comes and your number is called out.

We will create a system that will have these queues on the cloud. A service provider can create a queue and the queue is available on the cloud. A queue can be discovered in several ways – the creator of the queue can assign a unique name to the queue, or the queue can be identified based on the physical location where the people waiting in the queue will get the service.

A queue can be accessed either through a mobile device or through a liweb browser. The queue will provide the ability for a customer to get on the queue by drawing out a token. The customer will have the ability to see how fast the queue is moving (based on statistics that the system will collect for the past hour or so). The customer will be given an estimate about how much longer they will have to wait beft ore their turn. They will get an alarm when they get closer to their turn so they can plan and get ready. For example if one is at a grocery store, they can get on the queue but continue shopping. When they are couple of minutes away from their turn they can walk up to the deli counter.

The people servicing the queue will have the ability to select the next person in line. Once they select the next person in line, an announcement will be made calling the token number or the identifier for the next token. The queue will automatically advance to the next number. The administrator of the queue will have the ability to reset the queue to start a fresh cycle of tokens.

A queue can be accessed from any mobile device or from the web. When using a mobile device, the location of the device will provide the clue about the active queues at that location. If there are multiple queues at a given location (for example a grocery store might have a bank, a butcher shop and a deli; each department will have its own queue).

Lets start by designing this application a bit. The goal of this blog is to learn new languages and technologies as we go along. On those lines we will build the system incrementally. We will design a little piece of functionality, code a little, and explore alternative ways of implementing the same functionality. The idea is not to explore all the features of these languages but just those that we come across during the course of developing the application. Hopefully, the application will expose us to enough of the language and technology that it will become easier to pick up the rest as they are needed

In this spirit, lets start with a NumberDispenser class. This class will hold a counter – the next number to be dispensed. It will have methods that will dispense the next number, will let us just peek at the next number without dispensing it and will allow us to reset the counter to a new number.

class NumberDispenser(startingNumber: Int) {
  private var nextNumber = startingNumber;
  // Methods of this class
  def dispense : Int = {nextNumber += 1;nextNumber - 1}
  def peek = nextNumber
  def reset (resetTo : Int) {nextNumber = resetTo}
}

Lets look at this class, scala class is listed just like java with a class keyword. The only interesting thing in this declaration is  that there are parameters that are passed to the definition of the class in parentheses. These are called class parameters and the scala compiler will take these parameters and pass it to  a primary constructor that it will create. So, one does not have to write a constructor by hand. In order to create an object of this class, one would use the new keyword just like in java.

new NumberDispenser(100)

 

what else is interesting in this class? There is a private data member that holds the state of the class – the next number to dispense. Note that in Scala uses type inference to deduce the data type for the variable. It’s able to do that since we initialize the variable using the class parameters which have been declared as Int.

Besides the data variable there are three methods that the class exposes as its behavior. Let’s examine these. A Scala  method is declared with a “def” keyword, which I assume stands for define. Following def is the name of the method separated by a colon and then the return type of the method. The return type is optional and compiler can use type inference to deduce the return type of a function. In the above class this is illustrated by providing an explicit return type for the dispense method but the peek method lets the compiler deduce the return type. Another interesting point to mention here is that there is no need for an explicit return statement. The value of the last expression in a method becomes the return value. In case of dispense method the last expression is nextNumber – 1 and in case of the peek method the last statement is nextNumber. Also notice that if a method has only one statement there is no need to provide curly braces.

Now consider the reset method. This method does not return any value but has a side effect where it changes the next number that will be returned next. The return type of such methods is Unit. A short form of saying that the method does not return anything useful but is invoked just for its side effect is to remove the = sign after the method name and return type declaration. When there is no = sign before a methods body, it ignores the value calculated by the last expression of the method.

Testing

Lets write a test class to test our simple NumberDispenser. In Scala you have multiple choices of test frameworks to use. You can use the ever so popular JUnit framework, but you can also write your test cases in TestNG or in pure scala based testing frameworks like ScalaTest, specs and ScalaCheck.

For today’s blog we will start writing a test case in JUnit and then show how the same test case can be written in ScalaTest.

Here is the JUnit test class and it is self explanatory so we will not go further into it.

import org.junit.Assert.assertEquals
import org.junit.{Before, Test}

class NumberDispenserTest {
  private val numberDispenser = new NumberDispenser(100)

  @Before
  def setup() {
    numberDispenser.reset(200)
  }

  @Test
  def dispense() {
    assertEquals(200, numberDispenser.dispense)
    assertEquals(201, numberDispenser.dispense)
    assertEquals(202, numberDispenser.peek)
  }

  @Test
  def peek() {
    assertEquals(200, numberDispenser.peek)
    assertEquals(200, numberDispenser.peek)
    numberDispenser.dispense
    numberDispenser.dispense
    assertEquals(202, numberDispenser.peek)
  }

  @Test
  def reset() {
    assertEquals(200, numberDispenser.peek)
  }
}

 

And here is the same test case written in ScalaTest.

import org.scalatest.{BeforeAndAfter, FunSuite}
import org.scalatest.junit.JUnitRunner
import org.junit.runner.RunWith

@RunWith(classOf[JUnitRunner])
class NumberDispenserSuiteTest extends FunSuite with BeforeAndAfter {
  private val numberDispenser = new NumberDispenser(100)

  before {
    numberDispenser reset  200
  }

  test("dispense") {
    assert(200 == numberDispenser.dispense)
    assert(201 == numberDispenser.dispense)
    assert(202 == numberDispenser.peek)
  }

  test("peek") {
    assert(200 == numberDispenser.peek)
    assert(200 == numberDispenser.peek)
    numberDispenser.dispense
    numberDispenser.dispense
    assert(202 == numberDispenser.peek)
  }

  test ("reset") {
    assert(200 == numberDispenser.peek)
  }
}

Using ScalaTest’s FunSuite test suite, tests can be defined as function values. Let’s explore this a little more. Our test case “NumberDispenserSuite” extends a ScalaTest Framework construct called FunSuite. The “extends” keyword is similar to the Java extends keyword and defines a subclass-superclass relationship. However, FunSuite is not exactly a class. It is what is called a trait. The easiest way to understand trait is that it is similar to a Java interface but with key differences; such as it allows you to provide concrete implementations for the methods declared in it, they also allow you to declare fields and maintain state. A class is said to mix in one or more traits and in that respect, Scala provides you a mechanism for multiple inheritance. In the example above we are mixing in another trait called BeforeAndAfter which provides similar functionality as the SetUp and TearDown supported by JUnit. So our test class is a FunSuite with facility to support setup before the test is run and tear down after the test completes execution. 

Also notice that we have not written any constructors for our classes (both NumberDispenser as well as its test classes). In Scala one does not have to write a constructor for a class. The compiler generates a primary constructor for a class by collecting all the standalone statements and expression that it finds in the declaration of the body of the class. In this example test class,  the standalone statements such as “before” and “test” are actually method calls. These methods are defined in BeforeAndAfter and in FunSuite respectively. The compiler creates a primary constructor for our test class NumberDispenserSuite and puts these method calls in the constructor.

Each “test” statement  listed above is a call to the “test” method of FunSuite. The test method takes a string that describes the test as its first argument. Following this string, is a series of code statements in curly braces that might appear to a java developer as a function definition. In reality the code in curly braces is another argument to the test method of FunSuite that uses a technique called “currying”. More on currying will come later for now just know that it enables a developer to create new control abstractions that feel like native language support.  In the case of FunSuite, the second argument to the test method is curried and its type is a Function that takes no arguments and does not return anything. This “function value” (and thus the name “FunSuite”), has the actual test code to test our target code. Since all the calls to the test method are part of the primary constructor they are executed when a new object of our class NumberDispenserSuite is created. When these methods execute they register the function value passed as a curried argument to the test method with the Suite class for later execution.

In future blogs we will explore how to use “Behavior Driven Design” using Scala specs and ScalaCheck.

 

Executing ScalaTest

ScalaTest includes a JUnit Runner that knows how to run any ScalaTest Suite. This enables you to provide a JUnit RunWith annotation on any ScalaTest Suite. Once this is done, you can use Maven to execute the test suite.

Conclusion

In today’s blog we saw how to write a simple Scala class along with its test classes written in JUnit and ScalaTest and JUnit.

The NumberDispenser class is simple. In the next blog we  will see an alternate way of generating a stream of numbers using a Scala Collections data structure.  Hope you found this blog useful.