<CharlieDigital/> Programming, Politics, and uhh…pineapples

29Jul/141

Defining a “Release Lead”

Posted by Charles Chen

Came across a great definition while reading up on release 4.0 of WordPress:

A release lead, if anyone is curious, determines all important parameters for a release, like schedule, deadlines, which feature plugins are merged, and more generally, scope and goals. They take point when it comes to meetings, shepherding contributions, announcement posts, and updates. A release lead is a connector and facilitator, identifying bottlenecks and friction wherever they may be and at the service of the developers and plugin teams that are aiming to have something in a given release, and be in frequent communication with them.

The release lead should should follow what’s being committed, and set the tone for prioritizing and gardening the milestone on Trac. Given the constraint of time in hitting a date, help with prioritization and ensuring good communication lines are two of the most valuable things a lead can contribute.

The last five release leads were lead developers, but that’s not a requirement, nor is being a committer. I always thought of my “code reviewer” and “committer” hats as being separate, additional responsibilities. (Helen, of course, also wears these same hats.) Regardless: the release lead has the final call on all important decisions related to the release.

I particularly like the term "gardening the milestone" as this is a very suitable analogy to what the responsibilities of a release lead involves as it's very much an art like pruning a rose bush or a hedge and keeping a garden looking sharp.

Filed under: Dev 1 Comment
21Jul/140

Adventures in Poorly Written APIs

Posted by Charles Chen

I'm working with a library that I have been fighting with for the better part of three days now to try to get it to work.

The previous version of this library was actually very well written from an API perspective and well documented.  The new version?  Not so much.

But from this, I take away two lessons in API design.

Lesson 1: Don't Use Dictionaries in Public APIs -- ESPECIALLY for Required Data

The first mistake the API designers made in this case was exposing a "dictionary" in the public API.

This itself may not be all bad if the API is highly flexible and can accept many forms of requests, but if a public dictionary interface is required, then at least have the good judgement to provide a wrapper to populate those dictionaries.

But even the lack of usability is not as bad was having required data inputs passed to your service as dictionary entries.  In other words, the service call won't succeed without some sort of magical recipe of just the right metadata keys and values.  If it's a required piece of metadata, why not surface it as an actual parameter to the function?

Exposing dictionaries in public APIs is a terrible design idea which is as bad as APIs that require you to pass in XML strings (understood if it's a must, but have the courtesy to provide downstream callers an API to serialize objects into that XML and don't put required data into open ended inputs).  They should be used infrequently and preferably wrapped by an abstraction layer.

Lesson 2: Don't Require Your Caller to Keep Passing You Data You Handed Back

In this particular API, there is an initialization handshake with the server whereby large bits of system data are passed back to the caller.

For whatever reason, instead of simply handing a token back to the server, all (or part?? -- again, it's a magical incantation of sorts) of this metadata must be exchanged with the server to complete a request!

Why not provide a session key?  A caller token?  Something that the caller can use to represent this collection of system data instead of the full set of system data?

More to come, I'm sure of it, but this has been an interesting adventure in poorly written APIs.

Filed under: Dev, Rants No Comments
2Mar/14Off

Programmatically Add SharePoint Lists with Schemas

Posted by Charles Chen

So you want to add a custom list with a schema, eh?

In SharePoint, this is "easily" (lol) done by adding a custom list with a Schema.xml file and a list template XML file.

But what if you don't want to add a custom list template and you want to do it programmatically?  You'd want to do this, of course, if you wanted to define custom views on the list.  I've seen this done programmatically (as in verbose, custom code to build lists, add content types, build views, etc.), but SharePoint already offers you a mechanism for defining custom views using the list schema XML file.  Why duplicate what SharePoint already gives you for free?

In looking through the API, it seems that there is an API call that would support it, but it's quite cryptic in how it's actually invoked.

After a bit of testing, I found that it's actually quite easy.

Here is the API definition from Microsoft:

public virtual Guid Add(
   string title,
   string description,
   string url,
   string featureId,
   int templateType,
   string docTemplateType,
   string customSchemaXml,
   SPFeatureDefinition listInstanceFeatureDefintion,
   SPListTemplate.QuickLaunchOptions quickLaunchOptions
)

Here is the invocation in PowerShell:

$listId = $web.Lists.Add("Test List", "Test", "TestList2", 
    "00BFEA71-DE22-43B2-A848-C05709900100", 100, "100", $xml, $feature, 0)

A little explanation is in order here.  The first three parameters are very straight forward.  The fourth one is where it starts to get "funny".  Here, you will want to search in your 14\TEMPLATE\FEATURES\ directory for the feature that contains the template that you want to use.  In this case, I am creating a list based on the generic custom list type so the feature is located in 14\TEMPLATE\FEATURES\CustomList.  You need the GUID of the feature in the Feature.xml file here and not your own custom feature GUID.

The fifth and sixth parameters are straight forward.

We'll skip the seventh parameter for now.

The eight parameter here is the feature definition which contains the template that your list will be based on.  Because we are using an out-of-the-box list template, we simply need to load the feature definition for the GUID in parameter 4:

$features = [Microsoft.SharePoint.Administration.SPFarm]::Local

$id = [Guid]("00BFEA71-DE22-43B2-A848-C05709900100") 

$feature = $features[$id]

Again, because we are using the out-of-the-box template, we need to use the out-of-the-box feature definition that contains the template.

The ninth parameter is, again, straight forward.

Now back to that seventh parameter.  This parameter is simply the XML that would be generated by adding a new list in Visual Studio.  I've added a simple example here:

<?xml version='1.0' encoding='utf-8'?>
<List xmlns:ows='Microsoft SharePoint' Title='List1' FolderCreation='FALSE' Direction='$Resources:Direction;' Url='Lists/List1' BaseType='0' EnableContentTypes='True' xmlns='http://schemas.microsoft.com/sharepoint/'>
    <MetaData>
        <ContentTypes>
            <ContentTypeRef ID='0x01'>
                <Folder TargetName='Item' />
            </ContentTypeRef>
            <ContentTypeRef ID='0x0120' />
            <ContentTypeRef ID='0x010800B66F73F12643464793530152868EEE87'/>
        </ContentTypes>
        <Fields>
            <Field ID='{fa564e0f-0c70-4ab9-b863-0177e6ddd247}' Type='Text' Name='Title' DisplayName='$Resources:core,Title;' Required='TRUE' SourceID='http://schemas.microsoft.com/sharepoint/v3' StaticName='Title' MaxLength='255' />
        </Fields>
        <Views>
            <View BaseViewID='0' Type='HTML' MobileView='TRUE' TabularView='FALSE'>
                <Toolbar Type='Standard' />
                <XslLink Default='TRUE'>main.xsl</XslLink>
                <RowLimit Paged='TRUE'>30</RowLimit>
                <ViewFields>
                    <FieldRef Name='LinkTitleNoMenu'></FieldRef>
                </ViewFields>
                <Query>
                    <OrderBy>
                        <FieldRef Name='Modified' Ascending='FALSE'></FieldRef>
                    </OrderBy>
                </Query>
                <ParameterBindings>
                    <ParameterBinding Name='AddNewAnnouncement' Location='Resource(wss,addnewitem)' />
                    <ParameterBinding Name='NoAnnouncements' Location='Resource(wss,noXinviewofY_LIST)' />
                    <ParameterBinding Name='NoAnnouncementsHowTo' Location='Resource(wss,noXinviewofY_ONET_HOME)' />
                </ParameterBindings>
            </View>
            <View BaseViewID='1' Type='HTML' WebPartZoneID='Main' DisplayName='Hello, World' DefaultView='TRUE' MobileView='TRUE' MobileDefaultView='TRUE' SetupPath='pages\viewpage.aspx' ImageUrl='/_layouts/images/generic.png' Url='AllItems.aspx'>
                <Toolbar Type='Standard' />
                <XslLink Default='TRUE'>main.xsl</XslLink>
                <RowLimit Paged='TRUE'>30</RowLimit>
                <ViewFields>
                    <FieldRef Name='Attachments'></FieldRef>
                    <FieldRef Name='LinkTitle'></FieldRef>
                    <FieldRef Name='IntegrationID'></FieldRef>
                </ViewFields>
                <Query>
                    <OrderBy>
                        <FieldRef Name='ID'></FieldRef>
                    </OrderBy>
                </Query>
                <ParameterBindings>
                    <ParameterBinding Name='NoAnnouncements' Location='Resource(wss,noXinviewofY_LIST)' />
                    <ParameterBinding Name='NoAnnouncementsHowTo' Location='Resource(wss,noXinviewofY_DEFAULT)' />
                </ParameterBindings>
            </View>
        </Views>
        <Forms>
            <Form Type='DisplayForm' Url='DispForm.aspx' SetupPath='pages\form.aspx' WebPartZoneID='Main' />
            <Form Type='EditForm' Url='EditForm.aspx' SetupPath='pages\form.aspx' WebPartZoneID='Main' />
            <Form Type='NewForm' Url='NewForm.aspx' SetupPath='pages\form.aspx' WebPartZoneID='Main' />
        </Forms>
    </MetaData>
</List>

It is easily customized with additional custom views, specification of the fields on those views, and even specification of content types to associate to the list!

So why would you want to do this?  If you want a custom list with content types and custom views and all of that jazz, you can get it without writing a lot of custom code to build lists and without the hassle of custom templates (a pain in the butt); you can just write the schema XML (or maybe better yet, configure and export the list) and let SharePoint do its magic!

Filed under: Dev, SharePoint No Comments
23Feb/14Off

Why I Always Brace Everything

Posted by Charles Chen

Everything.

Braces

Filed under: Dev No Comments
30Jan/14Off

Stateless vs. Appccelerate.StateMachine

Posted by Charles Chen

I've been investigating workflow engines lately (specifically, state machine libraries) and it's come down to Stateless vs. Appcelerate.StateMachine.

First, a digression on why I'm avoiding Windows Workflow Foundation (WF).  It's true that there's tons of documentation, support from Microsoft, perhaps lots of experienced developers, but I count myself as one among many who feel burned by our experience with WF.  I've used the first release of WF on FirstPoint and mostly ended up regretting it for the poor performance and complexity (making it hard for new developers to pick it up).  I've also used the first release on various other SharePoint projects since then on top of Nintex and, again, it's been dogged by hard to trace bugs, poor performance, and stuff that's generally cumbersome (like deployment, for instance).

Microsoft seems to have addressed a lot of these issues by totally rewriting WF in .NET 4.0, but this in and of itself raises a serious question: how stable is the framework?  Sure, Microsoft provided a migration path from legacy WFs to new WFs, but it's still a headache.  Aside from that, even just looking at the APIs, it's clear that it's extremely heavy and does nothing to alleviate the poor practices which are possible with WF.

Thus enters my search for alternatives including Amazon Simple Workflow.  In the end, I've narrowed it down to Stateless and Appccelerate.StateMachine.

To test the intuitiveness, ease of use, and performance, I wrote a simple example with both of them.  I modeled the phone example from the Stateless documentation and ran it in a loop of 1,000,000.

The loop looks like so:

internal class Program
{
    private static void Main(string[] args)
    {
        var stopwatch = new Stopwatch();

        stopwatch.Start();

        for (int i = 0; i < 1000000; i++)
        {
            var phone = new Phone();

            phone.CallDialed();
            phone.CallConnected();
            phone.PlacedOnHold();
            phone.TakenOffHold();
            phone.HungUp();
        }

        stopwatch.Stop();

        Console.Out.WriteLine(stopwatch.ElapsedMilliseconds);
    }
}

The implementation of the phone in Stateless looks like so (common parts omitted for brevity):

namespace StatelessTest
{
    public class Phone
    {
        private readonly StateMachine<State, Trigger> _phone = new StateMachine<State, Trigger>(State.OffHook);

        private readonly Stopwatch _stopwatch = new Stopwatch();

        public Phone()
        {
            _phone.Configure(State.OffHook)
                  .Permit(Trigger.CallDialed, State.Ringing);

            _phone.Configure(State.Ringing)
                  .Permit(Trigger.HungUp, State.OffHook)
                  .Permit(Trigger.CallConnected, State.Connected);

            _phone.Configure(State.Connected)
                  .OnEntry(StartCallTimer)
                  .OnExit(StopCallTimer)
                  .Permit(Trigger.LeftMessage, State.OffHook)
                  .Permit(Trigger.HungUp, State.OffHook)
                  .Permit(Trigger.PlacedOnHold, State.OnHold);

            _phone.Configure(State.OnHold)
                  .SubstateOf(State.Connected)
                  .Permit(Trigger.TakenOffHold, State.Connected)
                  .Permit(Trigger.HungUp, State.OffHook)
                  .Permit(Trigger.PhoneHurledAgainstWall, State.PhoneDestroyed);
        }

        private void StartCallTimer()
        {
            _stopwatch.Start();
        }

        private void StopCallTimer()
        {
            _stopwatch.Stop();
        }

        public void CallDialed()
        {
            _phone.Fire(Trigger.CallDialed);

            //Console.Out.WriteLine("Dialed");
        }

        public void CallConnected()
        {
            _phone.Fire(Trigger.CallConnected);

            //Console.Out.WriteLine("Connected");
        }

        public void PlacedOnHold()
        {
            _phone.Fire(Trigger.PlacedOnHold);

            //Console.Out.WriteLine("On Hold");
        }

        public void TakenOffHold()
        {
            _phone.Fire(Trigger.TakenOffHold);

            //Console.Out.WriteLine("Off Hold");
        }

        public void HungUp()
        {
            _phone.Fire(Trigger.HungUp);

            //Console.Out.WriteLine("Hung Up");
        }
    }

    // Define enums here
}

The implementation of the phone in Appccelerate.StateMachine looks like so:

namespace StateMachineTest
{
    public class Phone
    {
        private readonly PassiveStateMachine<State, Trigger> _phone = new PassiveStateMachine<State, Trigger>();

        private readonly Stopwatch _stopwatch = new Stopwatch();

        public Phone()
        {
            _phone.In(State.OffHook)
                  .On(Trigger.CallDialed).Goto(State.Ringing);

            _phone.In(State.Ringing)
                  .On(Trigger.HungUp).Goto(State.OffHook)
                  .On(Trigger.CallConnected).Goto(State.Connected);

            _phone.In(State.Connected)
                  .ExecuteOnEntry(StartCallTimer)
                  .ExecuteOnExit(StopCallTimer)
                  .On(Trigger.LeftMessage).Goto(State.OffHook)
                  .On(Trigger.HungUp).Goto(State.OffHook)
                  .On(Trigger.PlacedOnHold).Goto(State.OnHold);

            _phone.DefineHierarchyOn(State.Connected)
                  .WithHistoryType(HistoryType.None)
                  .WithInitialSubState(State.OnHold);

            _phone.In(State.OnHold)
                  .On(Trigger.TakenOffHold).Goto(State.Connected)
                  .On(Trigger.HungUp).Goto(State.OffHook)
                  .On(Trigger.PhoneHurledAgainstWall).Goto(State.PhoneDestroyed);
        }

        private void StartCallTimer()
        {
            _stopwatch.Start();
        }

        private void StopCallTimer()
        {
            _stopwatch.Stop();
        }

        public void CallDialed()
        {
            _phone.Fire(Trigger.CallDialed);

            //Console.Out.WriteLine("Dialed");
        }

        public void CallConnected()
        {
            _phone.Fire(Trigger.CallConnected);

            //Console.Out.WriteLine("Connected");
        }

        public void PlacedOnHold()
        {
            _phone.Fire(Trigger.PlacedOnHold);

            //Console.Out.WriteLine("On Hold");
        }

        public void TakenOffHold()
        {
            _phone.Fire(Trigger.TakenOffHold);

            //Console.Out.WriteLine("Off Hold");
        }

        public void HungUp()
        {
            _phone.Fire(Trigger.HungUp);

            //Console.Out.WriteLine("Hung Up");
        }
    }

    // Define enums here
}

And here are the results:

2014-01-30_095250

Here are my observations:

  1. Stateless is about 4x faster than Appccelerate.StateMachine
  2. Stateless syntax is a little bit more intuitive for creating hierarchies
  3. Appccelerate.StateMachine documentation is much more thorough and much more complete than Stateless
  4. But Stateless has more downloads (thus more users) and more presence on StackOverflow (should you need it)
  5. Appccelerate.StateMachine has some cool features around logging and extensibility, but quite honestly, I don't think they are needed given that if you use a composite pattern around your state machine, you can really manage that yourself much more concisely.
  6. The external persistence infrastructure of Stateless is simple, but not very intuitive or well documented
  7. The Appccelerate.StateMachine Nuget package did not work with the package manager console and Visual Studio 2012, requiring me to manually download and compile the source (which I don't mind, but raises some doubt)

All said and done, I think we will use Stateless as it is a very barebones and highly performant state machine, which is perfect for our needs.  Look for more Stateless posts in the future!

Attached is the sample code: StateMachineTest

Filed under: Dev, Uncategorized, WF No Comments
26Dec/13Off

Setting Batch Variables Dynamically

Posted by Charles Chen

One of the challenges of managing builds and deployments of source on multiple developer machines is that it can be complicated to contain and manage different variations in developer environments.

For example, often times, it is useful to know the server name or the connection string information so that local settings don't make it into source control.

How I've often tackled this is to add a batch file that every developer executes when getting the source for the first time.  This batch file asks for various settings and then saves the results to a text file which is then read back when executing other batch files.

Here is an example of such a batch file:

@ECHO OFF

ECHO ================================================================
ECHO Creates the developer specific local configuration for builds
ECHO that will allow developers to use local settings for specifc
ECHO aspects of the deployment.
ECHO ================================================================

:SPURL
SET SPURL=
SET /P SPURL=Enter SharePoint site URL (ex. http://mymachine:2345/): %=%
IF "%SPURL%"=="" GOTO SPURL

ECHO ----------------------------------------------------------------

:SQLCONN
SET SQLCONN=
ECHO Enter SQL connection string to the IC membership database 
ECHO (ex. Server=VM1;Database=IPDB;User ID=membershipUser;Password=P@ssw0rd;Application Name=HeCoreServices):
SET /P SQLCONN=
IF "%SQLCONN%"=="" GOTO SQLCONN

ECHO ----------------------------------------------------------------

ECHO SPURL=%SPURL% > build-configuration.txt
ECHO SQLCONN=%SQLCONN% >> build-configuration.txt

ECHO Completed; created file build-configuration.txt

PAUSE

This batch file will prompt the developer for two settings: the URL of a site and the connection string that the developer is using locally (which can vary by the database name, login, etc.).  The contents get written to a file called build-configuration.txt that looks like this:

SPURL=http://mymachine:2345
SQLCONN=Server=VM1;Database=IPDB;User ID=membershipUser;Password=P@ssw0rd;Application Name=HeCoreServices

This file is excluded from source control and developers can, of course, manually edit this file as well to create local settings.

Now when I'm ready to use these settings in another batch file, I can invoke it like so:

@ECHO OFF

SETLOCAL ENABLEDELAYEDEXPANSION

FOR /F "tokens=*" %%n IN (build-configuration.txt) DO (	
	ECHO %%n

	SET %%n
)

ECHO %SPURL%
ECHO %SQLCONN%

PAUSE

There are other ways to do this as well, but the downside to most approaches is that you have to know how many parameters you have or use less meaningful names.  This approach will let you set variables to your heart's content and read them in dynamically at execution.

Filed under: Awesome, Dev, Self Note No Comments
26Oct/13Off

More Thoughts on Object Oriented Code

Posted by Charles Chen

I've talked about writing object-oriented and domain-driven design before.

In talking with another dev this week, I think I have my simplest summary of object-oriented code yet: when  you are writing well written object oriented code, you'll know it by the questions being asked by your code.

So what does this mean?

A good example is the following:

FormData formData = GetFormData();

// Object-oriented? Not really:
bool isValid = FormDataUtil.IsValid(formData);

// Object-oriented:
bool isValid = formData.IsValid();

It's very subtle, but it's very easy to observe because you simply need to ask yourself if you are asking the questions to the right objects.  We don't ask FormDataUtil if the formData is valid, we ask the formData directly.

Primarily, what this will reflect is the principle of encapsulation.

When you are asking the right questions to the right objects, you'll find that the code is easier to read, easier to maintain, less fragile, and more natural to reuse.

If the code is well written, as first time users, we don't have to know that there is a class explicitly designed to validate the form data; we can find it easily on the class itself.

I don't think it gets any simpler than that and yet it is, to me, the very essence of what it means to write object-oriented code.

20Sep/13Off

Step by Step Android Development with Cordova and IntelliJ

Posted by Charles Chen

There are other guides that cover this, but I found them lacking a bit in the step-by-step department for a beginner like myself.

Why IntelliJ?  Well first, Google has chosen it as the basis of their Android Studio IDE.  And second, Eclipse sucks :-D

Okay, so let's get started.

Download Pre-Requisites

  1. Download the Java SDK from here: http://www.oracle.com/technetwork/java/javase/downloads/index.html
  2. Download IntelliJ IDEA Community Edition from here: http://www.jetbrains.com/idea/download/
  3. Download and unzip the Android SDK or ADT Bundle from here: http://developer.android.com/sdk/index.html
  4. Download and unzip the PhoneGap package from here: http://phonegap.com/install/

If you download the Cordova package directly from the Apache site, you'll have to deal with the build process since it comes as source.  It's just all around easier to get started with the PhoneGap binaries.

Install Java

Follow the standard installation for the SDK, but after you finish, you will want to update your environment settings.

First, add the path to the Java binaries to your Path variable (right click on Computer -> Properties -> Advanced system settings -> Environment Variables).

Find the Path variable and add the path to the bin directory under where you installed the SDK:

path-var

Then click on New and add a variable called JAVA_HOME pointing to the directory where the SDK is installed:

java-home

If you open a command window and run javac, you should see the following:

javac-command

If not, you need to double check your settings.

Install IntelliJ

Not much to see here as the install is straight forward.  The installer will prompt you to run IntelliJ after it completes.

Create a New Project

Now we can create a new project and select Application Module under Android and then enter a project name and location:

new-project

Next, we need to select the Project SDK.  Click on the New button to create a new SDK mapping.  On your first run, it will prompt you to configure a Java SDK:

new-sdk

Click OK and select the location where the Java SDK was installed (C:\Program Files\Java\jdk1.7.0_04 for me).

Once you select that, you will be prompted to select the location of the Android SDK (E:\Experimental\android\adt-bundle-windows-x86_64-20130911\sdk for me).

It's the same dialog, so pay attention to the title.

Finally, you will see a dialog prompting you to Created New Android SDK:

create-android-sdk

When you are all done, it should look like so:

selected-android-sdk

Click Next and click Finish on the final screen:

finish-project-creation

Set Up Cordova

Now that we have our project set up, we need to hook Cordova into it.

Find the location where you unzipped the PhoneGap binaries and go to lib\android; you will find cordova.js and cordova-2.9.0.jar here.

Under the assets directory in the project, create a directory called www and paste the cordova.js file here.

Under the libs directory, paste the cordova-2.9.0.jar file here.

You need to right click on this file and select Add as Library.

Finally, under the res directory, paste the xml directory from the PhoneGap SDK and your directory should look like this:

project-setup

Create Content Files

Now we're ready to create our content files!  In the assets\www directory, add an HTML file called index.html:

create-html-file

Now update the HTML file with the following:

<!DOCTYPE html>
<html>
<head>
    <title>Demo Phonegap</title>
    <script type="text/javascript" charset="utf-8" src="cordova.js">
    </script>
</head>
<body>
<h2>Hello Android</h2>
</body>
</html>

Locate the file MyActivity.java and paste the following:

package com.example.CordovaExample;

import android.os.Bundle;
import org.apache.cordova.DroidGap;

public class MyActivity extends DroidGap {
    /**
     * Called when the activity is first created.
     */
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        super.loadUrl("file:///android_asset/www/index.html");
    }
}

You'll noticed that even though the directory is assets\www, it must be androd_asset/www for the code to work.

According to the official Cordova docs, you need to update the file AndroidManifest.xml file (however, I didn't need to add it to run it at this stage).  You need to paste the following into your AndroidManifest.xml file:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          package="com.example.CordovaExample"
          android:versionCode="1"
          android:versionName="1.0">
    <uses-sdk android:minSdkVersion="18"/>
    <supports-screens
            android:largeScreens="true"
            android:normalScreens="true"
            android:smallScreens="true"
            android:resizeable="true"
            android:anyDensity="true"/>
    <uses-permission android:name="android.permission.VIBRATE"/>
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
    <uses-permission android:name="android.permission.ACCESS_LOCATION_EXTRA_COMMANDS"/>
    <uses-permission android:name="android.permission.READ_PHONE_STATE"/>
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.RECEIVE_SMS"/>
    <uses-permission android:name="android.permission.RECORD_AUDIO"/>
    <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS"/>
    <uses-permission android:name="android.permission.READ_CONTACTS"/>
    <uses-permission android:name="android.permission.WRITE_CONTACTS"/>
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    <uses-permission android:name="android.permission.GET_ACCOUNTS"/>
    <uses-permission android:name="android.permission.BROADCAST_STICKY"/>
    <application android:label="@string/app_name" android:icon="@drawable/ic_launcher">
        <activity android:name="MyActivity"
                  android:label="@string/app_name"
                  android:screenOrientation="sensor"
                  android:configChanges="orientation|keyboardHidden|screenSize">
            <intent-filter>
                <action android:name="android.intent.action.MAIN"/>
                <category android:name="android.intent.category.LAUNCHER"/>
            </intent-filter>
        </activity>
    </application>
</manifest>

Set Up Virtual Device

Now you're ready to run!  You'll need to set up an Android Virtual Device (AVD) by selecting Tools -> Android -> AVD Manager:

create-avd

In this dialog, click on the Device Definitions tab and select Nexus S by Google and then click Create AVD:

selected-avd

Accept the defaults and enter 10 in the SD Card Size.  Now you're ready to build and run.

Build and Run

From the Build menu, select Make Project.  Once this completes successfully, click on Run -> Run 'CordovaExample'.

You should see your virtual device boot up now :-D (it could take a while...)

The cool thing is that as you update your code and build, IntelliJ will automatically push the changes to the virtual device.

Filed under: Android, Dev, DevTools No Comments
30Mar/12Off

Procedural vs. Structural Code

Posted by Charles Chen

In working with my development team, one of the things I've been working on is to figure out how to get them to be more object oriented. I've written about this topic before and I continue to evolve my expression of this idea to other developers that I work with.

To me, beyond the simple textbook definition of object oriented programming, at the level of construction, what it really boils down to is expressing logic structurally as opposed to procedurally. That is the very basis of what I've been trying to communicate and trying to understand how to impart that on other developers.

As a basic example, let's consider a user management API that has three operations for add, update, and delete.  Suppose I want to send a sequence of actions to this API.  We see this type of pattern of interaction all the time.  Assume we have a repository class:

public class UserRespitory
{
    public void Add(User user)
    {
        Console.Out.WriteLine("Added!");
    }

    public void Delete(User user)
    {
        Console.Out.WriteLine("Deleted!");
    }

    public void Update(User user)
    {
        Console.Out.WriteLine("Updated!");
    }
}

I've left the implementation of the actions intentionally simple.  Now assume that we have an operation and a user class like so:

public class Operation
{
    private readonly string _type;
    private readonly User _user;

    public Operation(string type, User user)
    {
        _type = type;
        _user = user;
    }

    public string Type
    {
        get { return _type; }
    }

    public User User
    {
        get { return _user; }
    }
}

public class User
{
    private string _username;

    public User(string username)
    {
        _username = username;
    }
}

Consider a use case where we must build an API to support bulk operations.  The typical implementation pattern that I will encounter will look more or less like this:

private static void Main(string[] args)
{
    List<Operation> inputs = new List<Operation>
    {
        new Operation("Add", new User("Charles")),
        new Operation("Update", new User("Steve")),
        new Operation("Delete", new User("John"))
    };

    UserRespitory repository = new UserRespitory();

    foreach (Operation operation in inputs)
    {
        switch (operation.Type)
        {
            case "Add":
                repository.Add(operation.User);
                break;
            case "Update":
                repository.Update(operation.User);
                break;
            case "Delete":
                repository.Delete(operation.User);
                break;
            default:
                throw new InvalidOperationException();
        }
    }
}

This is pretty much textbook procedural code and, as a consultant, this is pretty much the code I expect to see (and have seen countless times) on projects.  Of course, this is a pretty harmless case; in measuring the cyclomatic complexity and maintainability index of this code using Visual Studio's built-in analysis tools, I get values of 7 and 67 for each respectively.

Already a 7 with just a basic implementation.

Cyclomatic complexity is a good tool because it gives us a quantitative metric of code quality that is indifferent to "style" or any qualitative prejudices that individual developers might have -- it's a pretty good starting point for determining where to focus your time in terms of code reviews and refactoring.  With that said, a value of 7 is certainly not bad (the NIST guidelines recommend a limit of 10 for methods), however, I think we've all encountered this before: if-else's nested under switch's nested under if-else's nested under for-loops and so on.  When I see this pattern, I usually encounter it in the 20-30 range (and I've seen it in the 100+ range, sadly (an extract from a 1078 line method with cyclomatic complexity of 136 in production code -- I couldn't zoom out far enough to capture the whole thing)) for cyclomatic complexity simply because the developer doesn't know when to stop the madness.

Well, let me correct that last statement: when a developer starts down this path and once they've gone deep enough, there is simply no way that they can recover from the madness without structurally refactoring the code; the switch-case traps you into a cycle of cancerous code unless you can find a different way of representing the same logic in a more modular, orthogonal manner.  To me, this is really the heart of understanding object oriented programming.  How we achieve this -- in this case -- is quite simple, really.  For starters, we make the operation abstract:

public abstract class Operation
{
    private readonly User _user;

    public Operation(User user)
    {
        _user = user;
    }

    public User User
    {
        get { return _user; }
    }

    public abstract void Execute(UserRepository repository);
}

We also add an abstract method called Execute which every inheriting class must implement -- it's here that we've captured the essence of the switch-case in a much more structural, object-oriented manner.  Instead of a switch statement, we build the same logic structurally into the code by using three classes:

public class DeleteOperation : Operation
{
    public DeleteOperation(User user) : base(user) {}

    public override void Execute(UserRepository repository)
    {
        repository.Delete();
    }
}

public class AddOperation : Operation
{
    public AddOperation(User user) : base(user) {}

    public override void Execute(UserRepository repository)
    {
        repository.Add();
    }
}

public class UpdateOperation : Operation
{
    public UpdateOperation(User user) : base(user) {}

    public override void Execute(UserRepository repository)
    {
        repository.Update();
    }
}

The abstract method now gives us a way of specifying a different action for each "case" by creating another class.  Now our main code can be updated:

private static void Main(string[] args)
{
    // Structural representation of the logic
    List<Operation> inputs = new List<Operation>
    {
        new AddOperation(new User("Charles")),
        new UpdateOperation(new User("Steve")),
        new DeleteOperation(new User("John"))
    };

    UserRepository repository = new UserRepository();

    inputs.ForEach(i => i.Execute(repository));
}

What is our end result?

Improvements in maintainability and cyclomatic complexity

The change in the code itself was very minor; we performed a slight-of-hand and simply moved the three logical branches in the switch into three separate classes instead with each class inherently representing one of the switch cases.  In doing so, however, the cyclomatic complexity for the main program halved to 3 and the the maintainability index increased 6 points, even with such a barebones change.

The overall maintainability index of the entire solution increased 6 points.  Our cyclomatic complexity for the solution did increase, but that's because we've added three new classes which adds to the sum.

There are several other advantages that are easy to extend from this point:

  1. It's easier to add new operations.  Instead of adding another case, we simply add another operation class and inherit from the abstract base class.  The logic for that particular operation -- for example, business logic or setup before the operation is invoked -- can be encapsulated in the new class instead of in the case.
  2. It's easier to add more logic around the operations.  Because we've removed the invocation from the switch, we can avoid a giant if with deeply nested code as the logic around the operations change.  With a class for each operation, we can add operation specific logic to the class instead.  If we need to add common logic, we can use the base class.
  3. It's easier to read.  I think the code is easier to read simply because the level of nesting is now greatly reduced.  McConnell writes in Code Completed, 2nd Edition:

    "The smaller part of the job of programming is writing a program so that the computer can read it; the larger part is writing it so that other humans can read it." (McConnell, 733)

  4. It's less prone to user error.  By removing the switch and getting away from a string comparison, we've made the solution more resilient to input errors.

Overall, it's a very minor change in the structure of the code (check it out, even the LoC is the same), but even in this most basic of scenarios, it yields clear objective and subjective improvements.  While this is a very basic example of a very specific case, the underlying idea here -- structural representation of logic and flow -- is the real essence of object oriented programming.  The intentionally simplistic example is meant to (hopefully) help surface this concept, but the general idea of refactoring to structural representations is applicable to many different use cases, scenarios, and coding patterns.

Code samples: SampleProcedural.zip and SampleStructuralCode.zip

Filed under: Dev No Comments
23Jan/12Off

Browser MapReduce + Charting

Posted by Charles Chen

Having dabbled in Mongo a bit, I was curious if there was an analog for MapReduce style functionality in browser JavaScript.

I found a small script as a starting point, but made some minor modifications to support array inputs:

// mapper should return an array of [{key:'somekey', value:'somevalue'}]
// reducer should return a single {key:'somekey', value:'somevalue'}
function mapReduce(i, mapper, reducer, property) {
    var intermediate = [];
    var output = [];

    if(i && i.constructor == Array)
    {
        for(var x = 0; x < i.length; x++)
        {
            var value = i[x][property];
            var key = property;

            intermediate = intermediate.concat(mapper(key, value));
        }
    }
    else
    {
        for (var key in i)
        {
            var value = i[key];

            intermediate = intermediate.concat(mapper(key, value));
        }
    }

    var groups = groupBy(intermediate);

    for (var key in groups)
    {
        var values = groups[key];
        output.push(reducer(key, values));
    }

    return output;
}

// list should be [{key:k, value:v}, ....] where key may be repeated.
// returns [{key, [v1, v2, v3...]}, ...] where key is *not* repeated.
function groupBy(list) {
    var ret = {};
    for (var i = 0; i < list.length; i++) {
        var key = list[i].key;
        var value = list[i].value;
        if (!ret[key]) {
            ret[key] = [];
        }

        ret[key].push(value);
    }
    return ret;
}

I then  plugged in my custom map/reduce functions:

// Random data set -- could come from anywhere.
var data = [
    {Country: "US", Type:"B", ProductCode: "001"},
    {Country: "US", Type:"B",  ProductCode: "001.A"},
    {Country: "US", Type:"Z",  ProductCode: "001.B"},
    {Country: "UK", Type:"A",  ProductCode: "002"},
    {Country: "US", Type:"Z",  ProductCode: "003"},
    {Country: "FR", Type:"B",  ProductCode: "003.A"},
    {Country: "DE", Type:"B",  ProductCode: "003.C"},
    {Country: "DE", Type:"T",  ProductCode: "004"},
    {Country: "UK", Type:"R",  ProductCode: "004.R"},
    {Country: "UK", Type:"B",  ProductCode: "005"}
];

// Custom mapper
function _map(key, value)
{
    var result = [];

    result.push({key:value, value:1});

    return result;
}

// Custom reducer
function _reduce(key, values)
{
    var sum = 0;

    for(var i = 0; i < values.length; i++)
    {
        sum += values[i];
    }

    return {key: key, value: sum};
}

Now can I call it like so:

// Basic "group by - count"
var out = mapReduce(data, _map, _reduce, "Country");

This yields the following result:

[{"key":"US","value":4},
{"key":"UK","value":3},
{"key":"FR","value":1},
{"key":"DE","value":2}]

Pretty nifty!  And this data can then be fed into flot for charting purposes.

Sample (with flot example) is attached: MapReduce.zip

Filed under: Dev No Comments