JavaScript has an interesting feature called hoisting. Basically, it takes your vars and function definitions and moves them to the top of the scope. So this:

var string = "some global var";

function example(changeGlobal) {
    if (changeGlobal) {
        string = "modifying the global?";
    } else {
        var string = "definitely modifying a local";
    }
}

is the same as this:

var string = "some global var";

function example(changeGlobal) {
    var string;
    if (changeGlobal) {
        string = "modifying the global?";
    } else {
        string = "definitely modifying a local";
    }
}

Of course the second example makes it obvious we’re not changing the value of the global and why experts recommend defining vars at the top of a function.

For the most part hoisting doesn’t rear it’s head in day to day development, but tonight I came across an interesting problem. I was taking the most intense JS quiz in the world and wanted a custom alert function to override the built-in alert but still be able to call the original.

Why would I want this? The built-in alert was showing me the same message for alert(undefined) and alert(“undefined”), which were two distinct answers in the quiz. I tried overriding alert so it would wrap quotes around strings.

Sounds simple enough, right?

If we pretend hoisting doesn’t exist, we may write code like this:

var oldAlert = alert;

function alert(text) {
    if (typeof text === 'string') {
        oldAlert('"' + text + '"');
    } else {
        oldAlert(text);
    }
}

Because hosting raises the function definition, oldAlert actually points to my custom alert function, and we get infinite recursion.

Interesting.

What happens if we use a var instead of a function definition?

var oldAlert = alert;

var alert = function(text) {
    if (typeof text === 'string') {
        oldAlert('"' + text + '"');
    } else {
        oldAlert(text);
    }
};

This fails* because it’s just the same as writing:

var oldAlert;
var alert;
oldAlert = alert;

Which obviously won’t work.

* Note: this always fails in IE and Firefox, but Chrome and Safari fail only when wrapped in a parent function.

So hoisting actually makes this seemingly trivial problem more difficult. No matter what we do, if we declare a function named alert or a var named alert, it hides the built-in alert function.

However, we can get tricky with the global window object. The below code works and does exactly what we want it to:

var oldAlert = alert;

window.alert = function(text) {
    if (typeof text === 'string') {
        oldAlert('"' + text + '"');
    } else {
        oldAlert(text);
    }
};

Since we didn’t define a var or a function we circumvent hoisting and can cache off the old alert before it’s hidden.

This isn’t the type of problem you come across every day in JavaScript, but if you know the nuances you may come to agree it’s the world’s most misunderstood programming language.

Selectors

In the Objective C world you frequently use Selectors to interface with Apple’s API. Selectors are basically a way to pass a method (a.k.a. message) around. One of my personal favorites is:

[someObject performSelector:@selector(sayHello)
                 withObject:self
                 afterDelay:1.0f];

The above line sends the ‘sayHello’ message to someObject after a one second delay. I used this recently to simulate a web service call.

A selector is somewhat like C’s function pointers.

So, aside from sending a delayed message, how are selectors useful? Let’s take our web service example, and say we want to design an object which calls the web service, parses the data, and returns another object as the result. If we want to use Apple’s spinning activity indicator though, we can’t tie up the main thread (otherwise our indicator won’t animate). This means we’ll have to make asynchronous calls, which we can do with a selector.

// in Objective C, self == this
[webService invokeServiceWithCallbackObj:self];

Then in our WebService class, we might have a line like this:

// web service finished, so invoke callback
[callbackObj performSelector:
             @selector(webServiceIsDone)
             withObject:outputData];

Which will send the webServiceIsDone message to our original object (the one we passed as a callback).

So it’s actually pretty simple, once you get your head around selectors. If you’re from the Java or C# world, this is very similar to reflection.

But what happens if you want the web service to pass a parameter into your callback method? Well, luckily the super class of all super classes, NSObject, has a performSelector:withObject: method.

And if you want to pass two parameters? NSObject to the rescue again with performSelector:withObject:withObject:

What about three? Well, you’re out of luck there. I guess one of your parameters will have to be a more complex object that contains the rest of your params.

Hrm…I wonder if we can do better though?

Delegates

On the other hand, if we want a stronger contract between our web service caller and callee, we may choose a different paradigm: delegates.

Delegates are implemented with Objective C’s protocols (which are exactly like Java and C#’s interfaces). They define a contract that the implementor fulfills.

Maybe our web service class wants to be fancy and accept a delegate that implements this protocol:

@protocol WebServiceDelegate
- (void) failedWithError:(WebService*)webService;

- (void) success:(WebService*)webService
        response:(NSString*)response
      statusCode:(int)statusCode;
@end

Here our protocol defines two methods: one for when the web service fails, and one for when it succeeds (and success has 3 parameters, wow!).

In our web-service-calling-class, we just implement that protocol and then define the two methods. If we forget one of the methods or get the signature wrong, the compiler will let us know.

Now when we call the web service, we just pass ourselves in the same way we did in the selector example:

[webService invokeServiceWithDelegate:self];

This approach works great, and is very common in the Cocoa world. But what happens if we want to call two different web services? Our object can only implement the WebServiceDelegate once, so the same method gets called for both responses.

Typically in this situation the protocol method’s first parameter is the web service object. So our code that calls the web service could do something like this:

- (void) success:(WebService*)webService
        response:(NSString*)response
      statusCode:(int)statusCode {
    if (webService == self.firstWebService) {
        // response from 1st
    } else {
        // response from 2nd
    }
}

Hrm…I wonder if we can do better though?

Blocks

iOS 4 introduced a new feature to Objective C: blocks. Blocks are full closures that basically let you pass chunks of code around as if they were an object. Our trusty web service example:

[webService invokeServiceWithBlock:^{
    // write normal code here
}];

The carrot (^) and squiggly brackets ({}) are the new syntax. In between those brackets is a block of code that we literally pass as an input parameter.

Inside the webService object, things look like this:

typedef (void)(^Block)(void);

- (void) invokeServiceWithBlock:(Block)block {
    block();
}

(The above example isn’t exactly asynchronous, nor does it invoke the web service, but you get the idea).

I used a typedef on the block, simply because it makes the syntax more readable. Basically, I declared a type named Block that takes no parameters and returns no parameters.

You can also pass multiple blocks as arguments:

[webService invokeServiceWithSuccessBlock:^{
    // handle success
} failureBlock:^{
    // sound the alarm!
}];

So, how is this better than selectors and delegates?

Well, there’s a few advantages. First, what if I want to do a one-liner? For example: dismissing a modal dialog when the web service finishes. With the selector and delegates examples, I have to write individual methods. With the block example, I can just do it inline:

[webService invokeServiceWithBlock:^{
   [self dismissModalViewControllerAnimated:YES];
}];

Another advantage is that I can pass any number of arguments that I want:

[example threeArgBlock:^(int a, int b, int c) {
    // use those crazy args!
}];

You can also send different messages to yourself, depending on the web service:

[slowWebService invokeServiceWithBlock:^{
    [self slowWebServiceDone];
}];

[fastWebService invokeServiceWithBlock:^{
    [self fastWebServiceDone];
}];

Finally, my favorite advantage of blocks is when you want to pass a parameter to your own method. We’ll have to step outside our web service example for this one. Suppose I have a Button class that takes a block to be run when the button is tapped. Here, I’m setting up several buttons in a loop:

for (int i = 0; i < self.buttons.count; i++) {
    button.onTap = ^{
        [self tappedIndex:i];
    };
}

(note: the onTap property must ‘copy’ the block for it to work properly)

To do the same with delegates and selectors, you’d have to pass in an extra parameter and the receiver will have to pass that same parameter back to your callback. So that adds an extra param to two methods: the receiver and the callback.

With the block version, you can refactor your code without having to change the Button object at all. Let’s say we want to call our method when the button is tapped, but instead of taking a button index, we actually want to receive the Button itself:

for (Button *button in self.buttons) {
    button.onTap = ^{
        [self tappedButton:button];
    };
}

We only change the calling code, and no changes to the button object.

No More Selectors / Delegates Now?

Selectors definitely took a hard hit with the introduction of blocks, but there’s still at least one great use case for them. When you need to invoke a method but you don’t know its name at compile time, selectors are perfect. In that case, you wouldn’t use @selector, but NSSelectorFromString instead.

Delegates, on the other hand, are still great when you have several methods, especially if some of those methods are optional. When you need the power of a full object then you want to go with Delegates, but if all you need is one method or a few lines of code, blocks are wonderful.

References

http://pragmaticstudio.com/blog/2010/7/28/ios4-blocks-1

I just finished a great project with modern tech, gave the client more than they originally asked for, and got to learn something new.

In this post I’ll cover details about the project and how things worked. Along the way I’ll also give my personal opinions and I won’t back them up with pesky facts either, because, you know, that’s what you get to do in a project overview!

I ♥ REST

“Web services for a major entertainment industry player” sounds pretty good, but it’s even better. The client opted for REST web services with a JSON response; a very modern choice.

We’ve heard horror stories of making SOAP services work cross-platform, data type mismatches, etc. With REST, if your environment can make an http request and parse text, you’re good to go.

JSON is also super easy. You don’t have to write a DTD or XSD schema; instead you just create your objects and use a JSON serializer. For this project we used Jackson.

Tech Stack

The other parts of our tech stack were: Java, Spring, Hibernate, Tomcat, Maven, JUnit, Joda-Time, and Eclipse. All of these technologies are open source. In fact, the only part that wasn’t open source was the Oracle JDBC driver.

The Force is Strong With This One

One of our requirements involved subtracting dates to get the number of days in between. Leap years and daylight savings time (and the different dates for daylight savings time over the years) combine to make this a hairy task.

The built-in Java date and time API couldn’t do this easily, but we were pleasantly surprised to see that Joda-Time could. Using the Joda-Time date object, it was just one line to get the number of days between two dates.

Java 8 is scheduled to get a new date/time API and the man writing it is also the Joda-Time author, so expect some similarities.

Security

If your service runs in your own private network and the clients are also written by you, it’s tempting not to worry about security. Additionally, with REST it’s nice to avoid https when you can as responses can then be cached by a caching proxy server.

On the other hand, it’s nice to know your requests can only come from ‘approved’ clients. To do that, we could use BASIC AUTH (username/password), or we could go the https route and use client certificates. BASIC AUTH sends the password over clear text, which seems dangerous, and client certificates can be a pain to setup (plus you have SSL overhead and don’t get any benefit out of a caching proxy server anymore).

Our client chose to go another route and use a relatively new standard: OAuth. OAuth has been in the news recently because of Twitter and Facebook, but for locking down simple web services, we actually use a variant called “2-legged OAuth”.

The gist: clients have an ID and a secret. For each request several parameters are combined and run through a one-way hash. Those parameters include: the URL, the query string, the HTTP method, some OAuth values, the current time, the ID, and the secret. That hash, and the parameters used to create it (but NOT the secret), are sent plain text in the request. Since the server knows the secret, it can recompute the hash and make sure your hash matches its hash. It also verifies the request wasn’t made too long ago.

This adds very little overhead to the request: just computing a hash and sending the OAuth values. Plus, it ensures the request URL and query string weren’t modified (if they were, the hashes won’t match), and it works with or without https. Finally, the server can also use it for authorization, for example: one ID may only have GET permission while another has GET, PUT, and POST permissions.

Unit Testing

We used JUnit to test our business logic and Hibernate queries. We also had tests ensure our objects serialized to JSON correctly. For example: if a developer changed something in the code that also changed our JSON output, we would break our client’s code. If this happened, we wanted a test to fail, but that posed a problem as JSON fields can be in any order. If we compare two JSON strings and the order differs, the data may be equivalent, but our test would fail.

To work around this issue we wrote a custom assert method to serialize an object to JSON and then deserialize the JSON to a Java Map (in Python, a dictionary; in Ruby, a hash). Now we can compare our maps with each rather than comparing two strings, and the test works just fine since maps don’t care about order!

Testing Metrics

We needed to meet a few metrics, one of which was code coverage. Code coverage measures how much of your code is executed by the tests. If your tests finish running and only exercise 53% of the lines, then you have 53% code coverage.

This shows you holes in your unit testing, but be careful. Just as a passing test doesn’t guarantee bug-free code, 100% test coverage doesn’t mean all your logic is tested. Case in point: our data access objects had something like 65% – 75% code coverage even though we hadn’t written a single test for them! Code at a higher level was calling the getters and setters, ratcheting up the code coverage. So code coverage has some value, but you still must analyze what’s going on.

The code coverage tool we used (Cobertura) also provided another metric called branch coverage. Branch coverage measures the conditions in an if-statement or a loop. Take this example:

if (isWeekday && hasDiscount)

The above line must be executed three times to get 100% branch coverage: once when isWeekday is false, once when isWeekday is true but hasDiscount is false, and once when both are true.

Both code coverage and branch coverage helped us find holes in our testing, but we particularly liked branch coverage. There are occasional false positives with code coverage, but branch coverage always seemed to flag something worth looking at.

Integration Testing

One of the best things about a web service is how testable they are. You have very predictable output based on the input, so you can automate your testing.

In addition to our unit tests we also used SoapUI. Despite its name, it can test REST services too. SoapUI is a standalone GUI for testing web services, and we had it run 164 different tests.

We also used SoapUI to run our load tests (many users at once) and soak tests (few users for many hours).

However, getting SoapUI to provide the OAuth values for each test was challenging. Luckily, SoapUI has a scripting API to customize each request.

In the Groove

SoapUI’s scripting library lets you use Groovy, a dynamically typed language for the Java virtual machine. Just about any line of Java will work in Groovy, but Groovy also has its own syntax which was extremely nice to work with.

Groovy adds methods to built-in Java classes, and supports closures, which can make code more readable and terser than Java. For example: converting a List to a Map is 3 – 4 lines of Java, but it can be done in 1 line of Groovy.

Building

Maven was our build tool, and once you understand it you can get a build up and running very quickly.

Additionally, our client imposed a few restrictions such as minimum code coverage, maximum cyclomatic complexity per method, and they also required a particular header for each source file. We enforced all of these rules as part of our Maven build process.

The maven Cobertura plugin can be configured with a minimum line coverage and minimum branch coverage (we set both to 90%).

The McCabe Cyclomatic Complexity Number (CCN) determines how complex a method is, and the JavaNCSS maven plugin can determine the CCN for each of your methods. We set the CCN to a maximum of 10.

Finally, the Checkstyle maven plugin and some rules from our client ensured each source file had the appropriate header documentation.

If any of these metrics failed, or if the code didn’t compile, or the tests failed, then the entire build would fail. This meant we couldn’t deploy a new build to our test server until we fixed the issues. This nicely ensures you don’t ship some bad code on delivery day.

Summary

Overall the project went extremely well. Everyone on the team learned something new, we delivered on time, and we even met some additional client requests. It can be fun to use the knowledge you already have, but more fun to learn something new and cool. On this project I got to do both.

I moved to a different city, started a new job, got to learn some new things and reuse some old ones. Things were pretty good, than all of a sudden, bam! My boss says they aren’t renewing the lease. We’re going to start working from home.

Yikes!

A few years ago I took the morning off for my daughter’s birthday party. I’m pretty cheap when it comes to vacation time, so I decided to work the second half of the day from home. I had some motivational challenges, and the earth’s rotation must have slowed up just for that day since time was passing so much slower than usual. I thought working from home was just hard.

Now, a few weeks have passed since my boss made the announcement. I’ve been doing it for about 2 weeks, and I must say, I have a different take.

First, some of the things I love about working from home:

• No commute! (saves time, gas, and toll charges)
• Casual dress
• Talking to my boss or reading documentation on my bed
• Corner office with windows

I may actually be more productive now, as I don’t get in long conversations with co-workers. On the other hand, those long conversations with co-workers are pretty vital. That’s your social life, and when you work from home, it’s gone.

One tactic I’ve unofficially used is going out to lunch about once a week. It doesn’t matter who it’s with, just so long as you get out of the house, away from the computer, and get to talk to people.

There are, however, a few lessons to be learned:

• You need a quiet place. With a door. That can be closed.
• Don’t stop until you’re done for the day.

Regarding that last point: one night I took a break to eat dinner. I ended up playing quite a bit before getting started with work again, which was around 8:30. Yuck.

In general, working from home makes me want to start early, so I can be done before things start getting crazy at home.

All in all, it’s been a wonderful experience. It’s almost worth it just for the commute savings, but I also get extra benefits like casual dress. I’m not sure I’ll ever want to go back to the office!

In part 1 I covered the basics of REST: the URLs and verbs. In part 2 we’ll cover responses.

Response

A REST web service can return anything, though typically they return either XML or JSON. JSON stands for JavaScript Object Notation, and is pronounced just like the name “Jason”.

It’s JavaScript’s shortcut notation for creating objects, but it’s just a data format and doesn’t require JavaScript at all (just as XML also works in any programming language). JSON is typically terser than XML, and thus uses less bandwidth.

Here’s an example:

{
    "id" : 1234,
    "firstName" : "Bill",
    "lastName" : "Billford",
    "hours" : [
        { "day" : "Monday",    "start" : "8:00", "end" : "17:00" },
        { "day" : "Tuesday",   "start" : "9:00", "end" : "17:00" },
        { "day" : "Wednesday", "start" : "8:00", "end" : "17:00" },
        { "day" : "Thursday",  "start" : "8:00", "end" : "17:00" },
        { "day" : "Friday",    "start" : "8:00", "end" : "17:00" }
    ]
}

The curly braces { and } represent an object, which is basically key/value pairs. To the left of the colon is the key, and to the right is the value. When enclosed in quotes the value is a string, or, when quotes are omitted, the value is a number, a boolean, or null.

Key/value pairs can be in any order, as order is only relevant in arrays. Arrays are represented by square braces [ and ], and can contain values or even nested objects.

A typical JSON response is unformatted, so whitespace isn’t transmitted in the response, thus conserving bandwidth:

{"id":1234,"firstName":"Bill","lastName":"Billford","hours":
[{"day":"Monday","start":"8:00","end":"17:00"},{"day":
"Tuesday","start":"9:00","end":"17:00"},{"day":"Wednesday",
"start":"8:00","end":"17:00"},{"day":"Thursday","start":"8:00",
"end":"17:00"},{"day":"Friday","start":"8:00","end":"17:00"}]}

Third-party JSON formatters add the whitespace back, making the second example much easier to read. I recommend one that works offline, such as this one.

Summary

There’s more to REST than we’ve covered in these two posts, but this should be a good introduction. REST is simple, and, as an architectural philosophy, there aren’t many hard-and-fast rules. Something just feels RESTful or it doesn’t. When you get it right, it’s typically much easier for others to determine how your service works, since so many of us are already familiar with the web.

Further Reading and Source Material Used

• http://en.wikipedia.org/wiki/Representational_State_Transfer
• http://jcalcote.wordpress.com/2008/10/16/put-or-post-the-rest-of-the-story/
• http://stackoverflow.com/questions/630453/
• http://www.elharo.com/blog/software-development/web-development/2005/12/08/post-vs-put/
• http://www.markbaker.ca/2002/08/HowContainersWork/
• http://www.artima.com/lejava/articles/why_put_and_delete.html
• http://json.org/

REST stands for Representational State Transfer, and REST web services can be thought of as a competitor to SOAP. By their very nature, REST services are simple and follow the design of the web.

Why Learn REST?

You may already know REST since it’s the way the web works. REST uses URLs and HTTP verbs (like GET and POST), HTTP status codes, and headers to construct requests and responses. The body of a REST response can be anything including XML, HTML, or even plain text.

REST also works well on any platform. You don’t have to worry about data type mismatches from one vendor to another. If your programming language can make an HTTP request and parse text, you can call a REST web service.

Since REST is the same principles the web was built on, caching-proxy servers can be utilized for REST web services.

What about SOAP?

Technically SOAP is a technology or a protocol where REST is an architectural style. Comparing SOAP to REST is comparing apples to oranges, but nonetheless, most web services can be divided into either the SOAP or the REST flavors.

SOAP appears to be waning in popularity. Amazon’s web services supported both REST and SOAP and Amazon reported 85% of their web service traffic was via REST. Google abandoned their SOAP API in favor of an Ajax API (which has REST behind the scenes).

What is REST?

In REST, everything is treated as if it were a resource. URLs are nouns, and HTTP verbs like GET and POST are the actions. The verbs mean different things when the URL represents an individual resource or a collection of resources. Let’s look at the most common verbs.

GET

The GET verb is the easiest to understand: it retrieves a resource or a list of resources in a collection. GETs are safe to run multiple times in a row, as they don’t change anything on the server side.

Example GET URLs:

• http://some.webservice.com/employees/

List all the employees.

• http://some.webservice.com/employees/1234

Show details for the employee with ID 1234.

• http://some.webservice.com/employees?first-name=Bill&last-name=Billford

Search for an employee whose first name is Bill and last name is Billford.

• http://some.webservice.com/employees?results-per-page=10&page=2

Show all the employees, but start at page 2 and only show 10 employees per page.

As you can see, we don’t use the query string (the name=value pairs following the question mark) to identify the resource. Instead, we use the URL itself, as in /employees/1234. The query string is useful for searches, filtering, or paging, however.

HEAD

HEAD is very similar to GET, but the response only includes the HTTP headers and does not include the body. This is useful when determining whether a resource has changed (perhaps via the Last-Modified header), but without sending the entire contents of that resource. For example: if the resource hasn’t changed, a cached copy could instead be used.

POST and PUT

Most web developers are familiar with POST as it’s used for any request that’s not a GET. That’s partially because browsers don’t support PUT and DELETE (which will change in HTML 5), but in a REST architecture POST means something a little less broad.

Both POST and PUT can be used to create resources, but they do so in different ways. POST creates a resource in a collection. For example, a POST to this URL

http://some.webservice.com/employees/

might create a new resource, let the server generate an ID for that resource, and then return the ID. So, the server could generate resource 5678 and return “/employees/5678”, so the client knows the URL that was created. Future GETs to “/employees/5678” would work as expected.

On the other hand, a PUT to this URL:

http://some.webservice.com/employees/1234

may create a new resource at that exact location, or update the existing resource if it already exists.

Perhaps the most important difference between PUT and POST is that PUT is idempotent, meaning, PUT can safely be called multiple times and have the same result, whereas POST can be unsafe.

If your web service creates a new credit card resource and then immediately charges that card, you probably should use POST. If you were to use a PUT instead, the client may think it’s safe to repeat the operation (since PUTs are safe) and then get charged twice.

It then follows that a PUT must contain the entire contents of the resource, whether creating or updating the resource. This is the only way to guarantee the operation can be safely repeated. A POST on the other hand can contain partial content, or instructions to the server how it should process a resource.

Example URLs:

• http://some.webservice.com/employees/

A POST here could create a new resource and return the ID of the newly created resource.

A PUT here may replace the entire collection of employees with another entire collection of employees.

• http://some.webservice.com/employees/1234

A POST here may perform an update to the employee, perhaps only sending part of the data. 

A PUT could create a resource at this location. To maintain idempotence, the server could replace the resource if it already exists. In either case, a PUT contains the entire contents of the resource.

DELETE

DELETE is pretty straightforward: it deletes the resource or collection. DELETEs, just like GETs and PUTs, are idempotent and can be run multiple times. It’s safe to DELETE a resource that has already been deleted.

Example DELETE URLs:

• http://some.webservice.com/employees/1234

DELETE the employee with ID 1234

• http://some.webservice.com/employees/

DELETE all employees.

More on Verbs

Notice how the example URLs were all the same, yet the behavior differed depending on the HTTP verb. This is a common occurrence and keeps things uniform.

When a verb isn’t supported, an HTTP Status Code of 405 (Method Not Allowed) is returned. For example, if your service supports only GET and HEAD, you would return a 405 for POSTs, PUTs, and DELETEs.

Continue with part 2.