REST: A Tutorial

January 4, 2011

1. What is REST?

REST stands for Representational State Transfer. (It is sometimes spelled “ReST”.) It relies on a stateless, client-server, cacheable communications protocol — and in virtually all cases, the HTTP protocol is used.

REST is an architecture style for designing networked applications. The idea is that, rather than using complex mechanisms such as CORBA, RPC or SOAP to connect between machines, simple HTTP is used to make calls between machines.

In many ways, the World Wide Web itself, based on HTTP, can be viewed as a REST-based architecture.
RESTful applications use HTTP requests to post data (create and/or update), read data (e.g., make queries), and delete data. Thus, REST uses HTTP for all four CRUD (Create/Read/Update/Delete) operations.

REST is a lightweight alternative to mechanisms like RPC (Remote Procedure Calls) and Web Services (SOAP, WSDL, et al.). Later, we will see how much more simple REST is.

Despite being simple, REST is fully-featured; there’s basically nothing you can do in Web Services that can’t be done with a RESTful architecture.
REST is not a “standard”. There will never be a W3C recommendataion for REST, for example. And while there are REST programming frameworks, working with REST is so simple that you can often “roll your own” with standard library features in languages like Perl, Java, or C#.

2. REST as Lightweight Web Services

As a programming approach, REST is a lightweight alternative to Web Services and RPC.

Much like Web Services, a REST service is:

Platform-independent (you don’t care if the server is Unix, the client is a Mac, or anything else),
Language-independent (C# can talk to Java, etc.),
Standards-based (runs on top of HTTP), and
Can easily be used in the presence of firewalls.
Like Web Services, REST offers no built-in security features, encryption, session management, QoS guarantees, etc. But also as with Web Services, these can be added by building on top of HTTP:

For security, username/password tokens are often used.
For encryption, REST can be used on top of HTTPS (secure sockets).
… etc.
One thing that is not part of a good REST design is cookies: The “ST” in “REST” stands for “State Transfer”, and indeed, in a good REST design operations are self-contained, and each request carries with it (transfers) all the information (state) that the server needs in order to complete it.

3. How Simple is REST?

Let’s take a simple web service as an example: querying a phonebook application for the details of a given user. All we have is the user’s ID.

Using Web Services and SOAP, the request would look something like this:

<?xml version=”1.0″?>
<soap:Envelope
xmlns:soap=”http://www.w3.org/2001/12/soap-envelope&#8221;
soap:encodingStyle=”http://www.w3.org/2001/12/soap-encoding”&gt;
 <soap:body pb=”http://www.acme.com/phonebook”&gt;
  <pb:GetUserDetails>
   <pb:UserID>12345</pb:UserID>
  </pb:GetUserDetails>
 </soap:Body>
</soap:Envelope>
(The details are not important; this is just an example.) The entire shebang now has to be sent (using an HTTP POST request) to the server. The result is probably an XML file, but it will be embedded, as the “payload”, inside a SOAP response envelope.

And with REST? The query will probably look like this:

http://www.acme.com/phonebook/UserDetails/12345
Note that this isn’t the request body — it’s just a URL. This URL is sent to the server using a simpler GET request, and the HTTP reply is the raw result data — not embedded inside anything, just the data you need in a way you can directly use.

It’s easy to see why Web Services are often used with libraries that create the SOAP/HTTP request and send it over, and then parse the SOAP response.
With REST, a simple network connection is all you need. You can even test the API directly, using your browser.
Still, REST libraries (for simplifying things) do exist, and we will discuss some of these later.
Note how the URL’s “method” part is not called “GetUserDetails”, but simply “UserDetails”. It is a common convention in REST design to use nouns rather than verbs to denote simple resources.

The letter analogy
A nice analogy for REST vs. SOAP is mailing a letter: with SOAP, you’re using an envelope; with REST, it’s a postcard. Postcards are easier to handle (by the receiver), waste less paper (i.e., consume less bandwidth), and have a short content. (Of course, REST requests aren’t really limited in length, esp. if they use POST rather than GET.)

But don’t carry the analogy too far: unlike letters-vs.-postcards, REST is every bit as secure as SOAP. In particular, REST can be carried over secure sockets (using the HTTPS protocol), and content can be encrypted using any mechanism you see fit. Without encryption, REST and SOAP are both insecure; with proper encryption in place, both are equally secure.

4. More Complex REST Requests

The previous section included a simple example for a REST request — with a single parameter.

REST can easily handle more complex requests, including multiple parameters. In most cases, you’ll just use HTTP GET parameters in the URL.

For example:

http://www.acme.com/phonebook/UserDetails?firstName=John&lastName=Doe
If you need to pass long parameters, or binary ones, you’d normally use HTTP POST requests, and include the parameters in the POST body.

As a rule, GET requests should be for read-only queries; they should not change the state of the server and its data. For creation, updating, and deleting data, use POST requests. (POST can also be used for read-only queries, as noted above, when complex parameters are required.)

In a way, this web page (like most others) can be viewed as offering services via a REST API; you use a GET request to read data, and a POST request to post a comment — where more and longer parameters are required.
While REST services might use XML in their responses (as one way of organizing structured data), REST requests rarely use XML. As shown above, in most cases, request parameters are simple, and there is no need for the overhead of XML.

One advantage of using XML is type safety. However, in a stateless system like REST, you should always verify the validity of your input, XML or otherwise!

5. REST Server Responses

A server response in REST is often an XML file; for exmaple,

<parts-list>
 <part id=”3322″>
  <name>ACME Boomerang</name>
  <desc>
   Used by Coyote in <i>Zoom at the Top</i>, 1962
  </desc>
  <price currency=”usd” quantity=”1″>17.32</price>
  <uri>http://www.acme.com/parts/3322</uri&gt;
 </part>
 <part id=”783″>
  <name>ACME Dehydrated Boulders</name>
  <desc>
   Used by Coyote in <i>Scrambled Aches</i>, 1957
  </desc>
  <price currency=”usd” quantity=”pack”>19.95</price>
  <uri>http://www.acme.com/parts/783</uri&gt;
 </part>
</parts-list>
However, other formats can also be used; unlike SOAP services, REST is not bound to XML in any way. Possible formats include CSV (comma-separated values) and JSON (JavaScript Object Notation).

Each format has its own advantages and disadvantages. XML is easy to expand (clients should ignore unfamiliar fields) and is type-safe; CSV is more compact; and JSON is trivial to parse in JavaScript clients (and easy to parse in other languages, too).

One option is not acceptable as a REST response format, except in very specific cases: HTML, or any other format which is meant for human consumption and is not easily processed by clients. The specific exception is, of course, when the REST service is documented to return a human-readable document; and when viewing the entire WWW as a RESTful application, we find that HTML is in fact the most common REST response format…

6. Real REST Examples

Here’s a very partial list of service providers that use a REST API. Note that some of them also support a WSDL (Web Services) API, in addition, so you can pick which to use; but in most cases, when both alternatives are available, REST calls are easier to create, the results are easier to parse and use, and it’s also less resource-heavy on your system.

So without further ado, some REST services:

The famous Twitter API is all REST.
Yahoo! offer most of their services using REST. This includes
Search API,
Maps,
Photos,
Traffic,
… and just about any other.
Flickr,
Amazon.com offer several REST services, e.g., for their S3 storage solution (see Chapter 6),
Atom is a RESTful alternative to RSS.
(This is far from an exhaustive list.)

Here’s a simple example: the following URL sends a REST request to Yahoo!’s web-search service: http://search.yahooapis.com/WebSearchService/V1/webSearch?appid=YahooDemo&query=rest. Click it, and observe the XML results, ready to be used directly, not wrapped in an SOAP “envelope” or other noise.

This REST request includes two parameters: “appid”, used by Yahoo! to specify your application, and “query”, which is the actual search query.
If you plan to make actual use of Yahoo!’s web-search service, make sure you create your own appid. See the documentation for details.

7. AJAX and REST

AJAX is a popular web development technique that makes web pages interactive using JavaScript.

In AJAX, requests are sent to the server using XMLHttpRequest objects. The response is used by the JavaScript code to dynamically change the current page.

In many ways, AJAX applications follow the REST design principles. Each XMLHttpRequest can be viewed as a REST service request, sent using GET. And the response is often in JSON, a popular response format for REST. (See REST Server Responses, above.)

To make your AJAX application truly RESTful, follow the standard REST design principles (discussed later). You will find that most of them contribute to a good design, even if you don’t think of your architecture in terms of REST.

A later section provides code samples for issuing HTTP requests in JavaScript, but if you’ve done any AJAX programming, you are already familiar with all that.

8. REST Architecture Components

Key components of a REST architecture:

Resources, which are identified by logical URLs. Both state and functionality are represented using resources.
The logical URLs imply that the resources are universally addressable by other parts of the system.
Resources are the key element of a true RESTful design, as opposed to “methods” or “services” used in RPC and SOAP Web Services, respectively. You do not issue a “getProductName” and then a “getProductPrice” RPC calls in REST; rather, you view the product data as a resource — and this resource should contain all the required information (or links to it).
A web of resources, meaning that a single resource should not be overwhelmingly large and contain too fine-grained details. Whenever relevant, a resource should contain links to additional information — just as in web pages.
The system has a client-server, but of course one component’s server can be another component’s client.
There is no connection state; interaction is stateless (although the servers and resources can of course be stateful). Each new request should carry all the information required to complete it, and must not rely on previous interactions with the same client.
Resources should be cachable whenever possible (with an expiration date/time). The protocol must allow the server to explicitly specify which resources may be cached, and for how long.
Since HTTP is universally used as the REST protocol, the HTTP cache-control headers are used for this purpose.
Cilents must respect the server’s cache specification for each resource.
Proxy servers can be used as part of the architecture, to improve performance and scalability. Any standard HTTP proxy can be used.
Note that your application can use REST services (as a client) without being a REST architecture by itself; e.g., a single-machine, non-REST program can access 3rd-party REST services.

9. REST Design Guidelines

Some soft guidelines for designing a REST architecture:

Do not use “physical” URLs. A physical URL points at something physical — e.g., an XML file: “http://www.acme.com/inventory/product003.xml&#8221;. A logical URL does not imply a physical file: “http://www.acme.com/inventory/product/003&#8221;.
Sure, even with the .xml extension, the content could be dynamically generated. But it should be “humanly visible” that the URL is logical and not physical.
Queries should not return an overload of data. If needed, provide a paging mechanism. For example, a “product list” GET request should return the first n products (e.g., the first 10), with next/prev links.
Even though the REST response can be anything, make sure it’s well documented, and do not change the output format lightly (since it will break existing clients).
Remember, even if the output is human-readable, your clients aren’t human users.
If the output is in XML, make sure you document it with a schema or a DTD.
Rather than letting clients construct URLs for additional actions, include the actual URLs with REST responses. For example, a “product list” request could return an ID per product, and the specification says that you should use http://www.acme.com/product/PRODUCT_ID to get additional details. That’s bad design. Rather, the response should include the actual URL with each item: http://www.acme.com/product/001263, etc.
Yes, this means that the output is larger. But it also means that you can easily direct clients to new URLs as needed, without requiring a change in client code.
GET access requests should never cause a state change. Anything that changes the server state should be a POST request (or other HTTP verbs, such as DELETE).

10. ROA vs. SOA, REST vs. SOAP

ROA (REST Oriented Architecture) is just a fancy name for a SOA (Service Based Architecture) using REST services.

The main advantage of SOAP-based SOA over ROA is the more mature tool support; however, this could change over time. Another SOA advantages include the type-safety of XML requests (for responses, ROA can also use XML if the developers desire it).

The main advantage of ROA is ease of implementation, agility of the design, and the lightweight approach to things. In a way, SOA and SOAP is for people in business suits; that’s what you’ll find used in the banking and finance industries. Conversely, somebody that needs something up-and-running quickly, with good performance and low overhead, is often better off using REST and ROA.

For example, when explaining why they chose REST over SOAP, Yahoo! people write that they “believe REST has a lower barrier to entry, is easier to use than SOAP, and is entirely sufficient for [Yahoo’s] services” (Yahoo! Developer Network FAQ, as of February 2008). This is true not only of REST vs. SOAP but also of ROA vs. SOA in general.

Another advantage of REST lies with performance: with better cache support, lightweight requests and responses, and easier response parsing, REST allows for nimbler clients and servers, and reduces network traffic, too.

As REST matures, expect it to become better understood and more popular even in more conservative industries.

A few words on hype vs. reality. In the comments below, I’ve linked to Pete Lacey’s excellent criticism of SOAP, “The S Stands for Simple”. And here’s another one, by Alex Bell, published in Communications of the ACM (vol. 51, no. 10, October ’08): “DOA with SOA”.

11. Documenting REST Services: WSDL and WADL

WSDL, a W3C recommendation, is the Web Services Description Language. It is commonly used to spell out in detail the services offered by a SOAP server. While WSDL is flexible in service binding options (for example, services can be offered via SMTP mail servers), it did not originally support HTTP operations other than GET and POST. Since REST services often use other HTTP verbs, such as PUT and DELETE, WSDL was a poor choice for documenting REST services.

With version 2.0, WSDL supports all HTTP verbs and it is now considered to be an acceptable method of documenting REST services.

The second alternative is WADL, the Web Application Description Language. WADL is championed by Sun Microsystems. Like the rest of REST, WADL is lightweight, easier to understand and easier to write than WSDL. In some respects, it is not as flexible as WSDL (no binding to SMTP servers), but it is sufficient for any REST service and much less verbose.

Here is a fragment from a WADL specification, describing Amazon’s “Item Search” service:

<method name=”GET” id=”ItemSearch”>
 <request>
  <param name=”Service” style=”query”
   fixed=”AWSECommerceService”/>
  <param name=”Version” style=”query” fixed=”2005-07-26″/>
  <param name=”Operation” style=”query” fixed=”ItemSearch”/>
  <param name=”SubscriptionId” style=”query”
   type=”xsd:string” required=”true”/>
  <param name=”SearchIndex” style=”query”
   type=”aws:SearchIndexType” required=”true”>
    <option value=”Books”/>
    <option value=”DVD”/>
    <option value=”Music”/>
  </param>
  <param name=”Keywords” style=”query”
   type=”aws:KeywordList” required=”true”/>
  <param name=”ResponseGroup” style=”query”
   type=”aws:ResponseGroupType” repeating=”true”>
    <option value=”Small”/>
    <option value=”Medium”/>
    <option value=”Large”/>
    <option value=”Images”/>
  </param>
 </request>
 <response>
  <representation mediaType=”text/xml”
   element=”aws:ItemSearchResponse”/>
 </response>
</method>
As you can see, for format is mostly self-explanatory, and it enriches REST with such goodies as type safety using XML schema types.

The entire document is only about 10 lines longer than this fragment (including XML namespace specifications, importing schema grammers, etc.) and can be found in the WADL specification.
For another real-world WADL document, check out the W3C Unicorn project’s specification of the CSS validator service.
Some REST advocates, however, find even the lightweight WADL to be an overkill. And indeed, most REST services are documented by no more than a textual description (a human-readable HTML file).

Tags: ,


Building a Simple SOAP Web Service using Eclipse

January 4, 2011

Recently , i came across a very good article on creating a SOAP Web service using Eclipse.

You can follow the instructions provided in the below URL to create one in 30 mins !!!!

http://www.roseindia.net/webservices/buildingsimplewebservice.shtml


Understanding and Analyzing iPhone OS Application Crash Reports

December 30, 2010

This post contains essential information for developers who wish to receive and process crash reports for their iPhone OS applications.

1.Report Types
2.Symbolication
3.Acquiring Crash Reports
4.The Xcode Organizer

1.Report Types

There are four distinct kinds of crash reports. They are:

i)Application crash: possibly the most common kind of report, this is generated when execution is halted due to bad memory access, an exception or some other programming error.

ii)Low memory: occurs when the application has been killed by the system because there wasn’t enough memory to satisfy the application’s demands. The format of this report differs from the others in that there are no stack traces for the application threads. Rather than be concerned about what part of your code was executing at the time of termination, you should investigate your memory usage patterns and your responses to low memory warnings. Memory usage of each process is reported in terms of number of memory pages, which as of this writing are 4KB each.

iii)User force-quit: distinguished by exception code 0xdeadfa11. Force quits occur when the user holds down the home button for six seconds. It’s reasonable to assume the user has done this because the application has become unresponsive, but it’s not guaranteed – force-quit will work on any application.

iv)Watchdog timeout: distinguished by exception code 0x8badf00d. Timeouts occur when an application takes too long to launch, terminate, or respond to system events.

Except for the low memory crash logs, these logs contain stack traces for each thread at the time of termination. The next section discusses those traces.

2.Symbolication

The most interesting part of a crash report is the stack trace of your application at the time execution halted. This trace is similar to what you would see when stopping execution in the debugger, except that you are not given the method or function names, known as symbols. Instead, you have hexadecimal addresses and executable code – your application or system frameworks – to which they refer. You need to map these addresses to symbols. Unlike crash logs from Mac OS X, iPhone OS logs do not contain symbol information when they’re written out. You have to symbolicate iPhone OS logs before you can analyze them.

Symbolication – resolving stack trace addresses to source code methods and lines – requires the application binary that was uploaded to the App Store and the .dSYM file that was generated when that binary was built. This must be an exact match – otherwise, the report cannot be fully symbolicated. It is essential that you keep each build distributed to users (regardless of the details of that distribution) with its .dSYM file. See The Xcode Organizer for information on how Xcode can help you manage this.

IMPORTANT: You must keep both the application binary and the .dSYM file in order to be able to fully symbolicate crash reports. You should archive these files for every build that you submit to iTunes Connect. The .dSYM and application binary are specifically tied together on a per-build-basis, and subsequent builds, even from the same source files, will not interoperate with files from other builds. If you use the Build and Archive command as discussed in The Xcode Organizer then they will be placed in a suitable location automatically. Otherwise any location searchable by Spotlight (such as your home directory) is fine.
Given a crash report, the matching binary, and its .dSYM file, symbolication is easy. The Xcode Organizer window has a section specifically for Device Logs, and dragging a crash report to this window will symbolicate the crash report and display the results.

3.Acquiring Crash Reports

iTunesConnect service — a web site that iPhone developers use to manage their published applications — has a separate area that will list all the synced crash reports from the application users.

However, not all of the crashes appear there, or are slow to appear. Thus, if you have a desperate problem with someone’s application, it’s a good idea to pick these up and send them to a developer.

Here’s how, in three major operations systems: Mac OS X, Windows Vista / Windows 7 and for Windows XP.

iTunes sync

Application crash logs are transferred to your computer each time you do a sync with the device, in the iTunes. Thus, first step is to sync with iTunes:

Sync the iPhone or iPod Touch through iTunes

Mac OS X

On the Mac, crash logs are kept at:

~/Library/Logs/CrashReporter/MobileDevice/<DEVICE_NAME>
where ~ is your Home folder. Here’s an example:

Crash logs on the Mac OS X. Device name is “iPhone AV” here
There’s the .crash file and .plist file – archive them both and send to a developer. Actually, pick all the files you find there that have the name of the problematic application.

Windows Vista / Windows 7

Files are located here:

C:\Users\<USERNAME>\AppData\Roaming\Apple computer\Logs\CrashReporter/MobileDevice/<DEVICE_NAME>
AppData folder is hidden by default, so here’s how to access it. Get into your personal folder:

User folder, with Vista folder path
Now click on the folder (address) bar which will change the display into Windows folder path and add \AppData to it, then click Enter.

When clicked, the address bar changes into regular Windows folder path
This will then show the folder contents. From here, you can follow the path above until you get to the crash logs.

For Windows 7, follow the same procedure.

Windows XP

Location is here:

C:\Documents and Settings\<USERNAME>\Application Data\Apple computer\Logs\CrashReporter/<DEVICE_NAME>
<USERNAME> is your login username. Application Data folder is usually hidden by default, so you need to reveal it in the same way as in Vista — by typing in and pressing Enter.

4.The Xcode Organizer

The Xcode Organizer allows you to easily manage many development needs related to iPhone OS development, and managing crash reports is no exception. By default the Xcode Organizer will display and symbolicate all crash reports that it finds either on devices or already downloaded by iTunes. These crash reports are available organized by device or as a whole. To see crash reports by device, select that device and then select the Device Logs tab. To see all crash reports that Xcode has obtained, select the Device Logs entry under iPhone Development. To add crash reports to the listing, drag them into the listing.

Xcode will automatically symbolicate all crash reports that it encounters, but in order to do so it must have the .dSYM and application binary that produced the crash report.

Xcode 3.2.2 introduces the “Build and Archive” command to aid in this process. When you use the Build and Archive command, Xcode will gather the application binary and the .dSYM containing symbol information together and store them in a location in your home folder. You can find all of your archived applications in the Xcode Organizer under the Archived Applications section. Xcode will automatically search archived applications when symbolicating crash reports, and you can submit archived applications directly to iTunes Connect ensuring that the application and .dSYM that you have archived match what you release.


iPhone Sensors

December 29, 2010

There are three sensors built into the iPhone (and iPod touch) that allow it to perform some of its coolest tricks. They are:

1.Proximity sensor

This sensor can determine how close the iPhone is to your face. This sensor is what helps the iPhone turn off its screen automatically whenever you hold the phone up to your ear. This is necessary to prevent accidental button clicks by the side of your head when talking.

2.Motion sensor/accelerometer

This sensor enables the iPhone’s screen to automatically switch from landscape to portrait modes and back again based on whether you’re holding the phone up and down or sideways. This sensor is also present in the iPad.

3.Ambient Light sensor

This sensor can determine how much light is available in the area surrounding the iPhone and iPad and automatically adjust the brightness of the screen in order to conserve battery life.

4.Moisture sensor

The iPhone also contains a fourth sensor, though this one isn’t related to the interface. The water sensor is a little red tab that appears in the dock connector when the phone has been submerged in water. It can also appear as a red dot in the headphone jack.

5.iPhone 4 Gyroscope

The iPhone 4 adds another sensor: a three-axis gyroscope. When combining the gyroscope with the accelerometer, this gives the iPhone 4 six axes on which the it can operate. This is designed to make the iPhone 4 more sensitive, responsive, and powerful for gaming.


Introduction to Three20

October 19, 2010

The Three20 Library is a great open source library for the iPhone developed by Joe Hewitt, the developer of the Facebook iPhone app. The library is chock full of useful code for just about any iPhone project. It has an amazing image browser, great asynchronous/web loading support, stylizable views and labels, and a ton more.
In fact, the library is so full of useful stuff that it can be a little difficult getting a handle on it at first. Since I’m just getting started with Three20 myself, I thought I’d write up a tutorial to show a few basic features of Three20 to other newcomers.

Adding Three20 to your project

Three20 is compiled as a static library, and the easiest way to add it to your project is to use Xcode’s “dependent project” facilities. Here is how:
Estimated time: 5 minutes.

1.Clone the three20 git repository: git clone git://github.com/facebook/three20.git. Make sure you store the repository in a permanent place because Xcode will need to reference the files every time you compile your project.

2.Locate the “Three20.xcodeproj” file under “three20/src/Three20/”. Drag Three20.xcodeproj and drop it onto the root of your Xcode project’s “Groups and Files” sidebar. A dialog will appear — make sure “Copy items” is unchecked and “Reference Type” is “Relative to Project” before clicking “Add”.

3.Open the Three20 Xcode Project that you just added to your app and expand the “Dependencies” group. Select all of the projects listed there and drag them to your app as well. You should now have the following list of Three20 projects added to your app:

Three20Core
Three20Network
Three20Style
Three20UICommon
Three20UINavigator
Three20UI
Three20

4.Now you need to link the Three20 static libraries to your project. Select all of the project items that you just added to the sidebar. Under the “Details” table, you will see a number of items, such as libThree20.a and libThree20Core.a. Check the checkbox on the far right for each of the lib files (not the UnitTests). This will link each part of the Three20 framework to your app.

5.Now you need to add Three20 as a dependency of your project, so Xcode compiles it whenever you compile your project. Expand the “Targets” section of the sidebar and double-click your application’s target. Under the “General” tab you will see a “Direct Dependencies” section. Click the “+” button, select “Three20” and each of the other libs, and click “Add Target”. You do not need to add the UnitTests target for each lib.

6.Now you need to add the bundle of images and strings to your app. Locate “Three20.bundle” under “three20/src” and drag and drop it into your project. A dialog will appear — make sure “Create Folder References” is selected, “Copy items” is unchecked, and “Reference Type” is “Relative to Project” before clicking “Add”.

7.Now you need to add the Core Animation framework to your project. Right click on the “Frameworks” group in your project (or equivalent) and select Add > Existing Frameworks. Then locate QuartzCore.framework and add it to the project.

8.Finally, we need to tell your project where to find the Three20 headers. Open your “Project Settings” and go to the “Build” tab. Look for “Header Search Paths” and double-click it. Add the relative path from your project’s directory to the “three20/Build/Products/three20” directory.

9.While you are in Project Settings, go to “Other Linker Flags” under the “Linker” section, and add “-ObjC” and “-all_load” to the list of flags.

10.You’re ready to go. Just #import “Three20/Three20.h” anywhere you want to use Three20 classes in your project.

An Overview of Three20

Photo Viewer

TTPhotoViewController emulates Apple’s Photos app with all of its flick n’ pinch delight. You can supply your own “photo sources”, which works similiarly to the data sources used by UITableView. Unlike Apple’s Photos app, it isn’t limited to photos stored locally. Your photos can be loaded from the network, and long lists of photos can be loaded incrementally.

Message composer

TTMessageController emulates the message composer in Apple’s Mail app. You can customize it to send any kind of message you want. Include your own set of message fields, or use the standard “To:” and “Subject:”. Recipient names can be autocompleted from a data source that you provide.

Web image views

TTImageView makes it as easy to display an image as it is in HTML. Just supply the URL of the image, and TTImageView loads it and displays it efficiently. TTImageView also works with the HTTP cache described below to avoid hitting the network when possible.

Internet-aware table view controllers

TTTableViewController and TTTableViewDataSource help you to build tables which load their content from the Internet. Rather than just assuming you have all the data ready to go, like UITableView does by default, TTTableViewController lets you communicate when your data is loading, and when there is an error or nothing to display. It also helps you to add a “More” button to load the next page of data, and optionally supports reloading the data by shaking the device.

Better text fields

TTTextEditor is a UITextView which can grow in height automatically as you type. I use this for entering messages in Facebook Chat, and it behaves similarly to the editor in Apple’s SMS app.

TTPickerTextField is a type-ahead UITextField. As you type it searches a data source, and it adds bubbles into the flow of text when you choose a type-ahead option. I use this in TTMessageController for selecting the names of message recipients.

HTTP disk cache

TTURLRequest is a replacement for NSURLRequest which supports a disk cache (NSURLRequest can only cache in RAM). It has some other nice features too. HTTP posts are as easy as supplying a dictionary of parameters. The TTURL loading system can also be suspended and resumed at any time, which is a great performance helper. Network threads often fight with the UI thread, so you can suspend the network any time your app is momentarily graphically intensive.

URL-based Navigation

TTNavigator is for those grizzled old web developers like myself who want to organize their app by “pages” which can be displayed by visiting a URL.

Your view controllers can simply register URL patterns that they handle, and when those URLs are visited the controllers will be created and displayed. You can also register generic actions that are called when a URL is visited.

TTNavigator also persists and restores the full path of navigation controllers and modal view controllers, so your users can quite the app and come back exactly where they left off.

Learn more at Three20.info

Blogged with the Flock Browser

Macworld Boston 1997-The Microsoft Deal

July 23, 2010

Here we see Steve Jobs & the almost bankrupt at the time Apple Computer making a temporary deal with Bill Gates & Microsoft. The crowd was not too happy about it.

 Its the funniest Steve Jobs keynote I have watched. In it he announced his new partnership with Microsoft and then goes and tells everyone how Internet Explorer was going to be the default browser on the Mac. What I found funny is the Apple crowd, everyone was like booing and screaming out “Noooo!!”, I can only imagine how fucked up the experience must have been to them back then.

Blogged with the Flock Browser

Tags: ,


Unit Testing Guidelines

November 17, 2009

1. Keep unit tests small and fast

Ideally the entire test suite should be executed before every code check in. Keeping the tests fast reduce the development turnaround time.

2. Unit tests should be fully automated and non-interactive

The test suite is normally executed on a regular basis and must be fully automated to be useful. If the results require manual inspection the tests are not proper unit tests.

3. Make unit tests simple to run

Configure the development environment so that single tests and test suites can be run by a single command or a one button click.

4. Measure the tests

Apply coverage analysis to the test runs so that it is possible to read the exact execution coverage and investigate which parts of the code is executed and not.

5. Fix failing tests immediately


Each developer should be responsible for making sure a new test runs successfully upon check in, and that all existing tests runs successfully upon code check in.
If a test fails as part of a regular test execution the entire team should drop what they are currently doing and make sure the problem gets fixed.

6. Keep testing at unit level

Unit testing is about testing classes. There should be one test class per ordinary class and the class behaviour should be tested in isolation. Avoid the temptation to test an entire work-flow using a unit testing framework, as such tests are slow and hard to maintain. Work-flow testing may have its place, but it is not unit testing and it must be set up and executed independently.

7. Start off simple

One simple test is infinitely better than no tests at all. A simple test class will establish the target class test framework, it will verify the presence and correctness of both the build environment, the unit testing environment, the execution environment and the coverage analysis tool, and it will prove that the target class is part of the assembly and that it can be accessed.
The Hello, world! of unit tests goes like this:

     void testDefaultConstruction()
     {
       Foo foo = new Foo();
       assertNotNull(foo);
     }

8. Keep tests independent

To ensure testing robustness and simplify maintenance, tests should never rely on other tests nor should they depend on the ordering in which tests are executed.

9. Keep tests close to the class being tested

If the class to test is Foo the test class should be called FooTest (not TestFoo) and kept in the same package (directory) as Foo. Keeping test classes in separate directory trees makes them harder to access and maintain.
Make sure the build environment is configured so that the test classes doesn’t make its way into production libraries or executables.

10. Name tests properly

Make sure each test method test one distinct feature of the class being tested and name the test methods accordingly. The typical naming convention is test[what] such as testSaveAs(), testAddListener(), testDeleteProperty() etc.

11. Test public API

Unit testing can be defined as testing classes through their public API. Some testing tools makes it possible to test private content of a class, but this should be avoided as it makes the test more verbose and much harder to maintain. If there is private content that seems to need explicit testing, consider refactoring it into public methods in utility classes instead. But do this to improve the general design, not to aid testing.

12. Think black-box

Act as a 3rd party class consumer, and test if the class fulfills its requirements. And try to tear it apart.

13. Think white-box

After all, the test programmer also wrote the class being tested, and extra effort should be put into testing the most complex logic.

14. Test the trivial cases too

It is sometimes recommended that all non-trivial cases should be tested and that trivial methods like simple setters and getters can be omitted. However, there are several reasons why trivial cases should be tested too:
Trivial is hard to define. It may mean different things to different people.
From a black-box perspective there is no way to know which part of the code is trivial.
The trivial cases can contain errors too, often as a result of copy-paste operations:
     private double weight_;
     private double x_, y_;

     public void setWeight(int weight)
     {
       weight = weight_;  // error
     }

     public double getX()
     {
       return x_;
     }

     public double getY()
     {
       return x_;  // error
     }
The recommendation is therefore to test everything. The trivial cases are simple to test after all.

15. Focus on execution coverage first

Differentiate between execution coverage and actual test coverage. The initial goal of a test should be to ensure high execution coverage. This will ensure that the code is actually executed on some input parameters. When this is in place, the test coverage should be improved. Note that actual test coverage cannot be easily measured (and is always close to 0% anyway).
Consider the following public method:

     void setLength(double length);
By calling setLength(1.0) you might get 100% execution coverage. To acheive 100% actual test coverage the method must be called for every possible double value and correct behaviour must be verified for all of them. Surly an impossible task.

16. Cover boundary cases

Make sure the parameter boundary cases are covered. For numbers, test negatives, 0, positive, smallest, largest, NaN, infinity, etc. For strings test empty string, single character string, non-ASCII string, multi-MB strings etc. For collections test empty, one, first, last, etc. For dates, test January 1, February 29, December 31 etc. The class being tested will suggest the boundary cases in each specific case. The point is to make sure as many as possible of these are tested properly as these cases are the prime candidates for errors.

17. Provide a random generator

When the boundary cases are covered, a simple way to improve test coverage further is to generate random parameters so that the tests can be executed with different input every time.
To achieve this, provide a simple utility class that generates random values of the base types like doubles, integers, strings, dates etc. The generator should produce values from the entire domain of each type.

If the tests are fast, consider running them inside loops to cover as many possible input combinations as possible. The following example verifies that converting twice between little endian and big endian representations gives back the original value. As the test is fast, it is executed on one million different values each time.

    void testByteSwapper()
    {
      for (int i = 0; i < 1000000; i++) {
        double v0 = Random.getDouble();
        double v1 = ByteSwapper.swap(v0);
        double v2 = ByteSwapper.swap(v1);
        assertEquals(v0, v2);
      }
    }

18. Test each feature once

When being in testing mode it is sometimes tempting to assert on “everything” in every test. This should be avoided as it makes maintenance harder. Test exactly the feature indicated by the name of the test method.
As for ordinary code, it is a goal to keep the amount of test code as low as possible.

19. Use explicit asserts

Always prefer assertEquals(a, b) to assertTrue(a == b) (and likewise) as the former will give more useful information of what exactly is wrong if the test fails. This is in particular important in combination with random value parameters as described above when the input values are not known in advance.

20. Provide negative tests

Negative tests intentionally misuse the code and verify robustness and appropriate error handling.
Consider this method that throws an exception if called with a negative parameter:

    void setLength(double length) throws IllegalArgumentException;
Testing correct behavior for this particular case can be done by:
    try {
      setLength(-1.0);
      fail();  // If we get here, something went wrong
    }
    catch (IllegalArgumentException exception) {
      // If we get here, all is fine
    }

21. Design code with testing in mind

Writing and maintaining unit tests are costly, and minimizing public API and reducing cyclomatic complexity in the code are ways to reduce this cost and make high-coverage test code faster to write and easier to maintain.
Some suggestions:

Make class members immutable by establishing state at construction time. This reduce the need of setter methods.
Restrict the use of excessive inheritance and virtual public methods.
Reduce the public API by utilizing friend classes (C++) or package scope (Java).
Avoid unnecessary branching.
Keep as little code as possible inside branches.
Make heavy use of exceptions and assertions to validate arguments in public and private API’s respectively.
Restrict the use of convenience methods. From a black-box perspective every method must be tested equally well. Consider the following trivial example:
    public void scale(double x0, double y0, double scaleFactor)
    {
      // scaling logic
    }

    public void scale(double x0, double y0)
    {
      scale(x0, y0, 1.0);
    }
Leaving out the latter simplifies testing on the expense of slightly extra workload for the client code.

22. Don’t connect to predefined external resources

Unit tests should be written without explicit knowledge of the environment context in which they are executed so that they can be run anywhere at anytime. In order to provide required resources for a test these resources should instead be made available by the test itself.
Consider for instance a class for parsing files of a certain type. Instead of picking a sample file from a predefined location, put the file content inside the test, write it to a temporary file in the test setup process and delete the file when the test is done.

23. Know the cost of testing

Not writing unit tests is costly, but writing unit tests is costly too. There is a trade-off between the two, and in terms of execution coverage the typical industry standard is at about 80%.
The typical areas where it is hard to get full execution coverage is on error and exception handling dealing with external resources. Simulating a database breakdown in the middle of a transaction is quite possible, but might prove too costly compared to extensive code reviews which is the alternative approach.

24. Prioritize testing

Unit testing is a typical bottom-up process, and if there is not enough resources to test all parts of a system priority should be put on the lower levels first.

25. Prepare test code for failures

Consider the simple example:
    Handle handle = manager.getHandle();
    assertNotNull(handle);

    String handleName = handle.getName();
    assertEquals(handleName, “handle-01”);
If the first assertion is false, the code crashes in the subsequent statement and none of the remaining tests will be executed. Always prepare for test failure so that the failure of a single test doesn’t bring down the entire test suite execution. In general rewrite as follows:
    Handle handle = manager.getHandle();
    assertNotNull(handle);
    if (handle == null) return;

    String handleName = handle.getName();
    assertEquals(handleName, “handle-01”);

26. Write tests to reproduce bugs

When a bug is reported, write a test to reproduce the bug (i.e. a failing test) and use this test as a success criteria when fixing the code.

27. Know the limitations

Unit tests can never prove the correctness of code!!
A failing test may indicate that the code contains errors, but a succeeding test doesn’t prove anything at all.

The most useful appliance of unit tests are verification and documentation of requirements at a low level, and regression testing: verifying that code invariants remains stable during code evolution and refactoring.

Consequently unit tests can never replace a proper up-front design and a sound development process. Unit tests should be used as a valuable supplement to the established development methodologies.

Blogged with the Flock Browser