Why we should Love ‘null’

Gallery

Ray Yagubyan

Ray Yagubyan

Abstract

null has been the cause for countless troubles in the history of software development. Today, ‘null‘ and ‘the billion-dollar mistake’ are synonyms. Therefore some developers try to avoid null by using techniques such as ‘return zero instead of null‘, the NullObject pattern or the Optional/Maybe pattern.

Should you use these techniques in your source code? Do they lead to more reliable software? Or is there a better solution?

These are the questions this article tries to answer.


Many developers dislike null.

Some hate null.

null is the reason for the infamous null pointer error (called NullPointerException in Java).

Null pointer exception (NPE)

Practice shows: The null pointer error is the most frequent bug occurring in popular programming languages.

Professor John Sargeant from the Manchester school of computer science puts it like this:

Of the things which can go wrong at runtime in Java programs, null pointer exceptions are by far the most common.

In Java, the NullPointerException is the only exception that has deserved its own acronym: NPE. If you tell a Java programmer something like “This code is full of NPEs”, he/she knows exactly what you are talking about.

null has been the cause of:

  • billions of dollars of damages caused by software bugs
  • millions of hours spent by developers to prevent or repair null pointer errors
  • frustration and bad headaches among developers, managers and users of software products

Null pointer error message

Tony Hoare, the inventor of null, calls it a “billion-dollar mistake”.

Therefore some developers try to avoid null.

For example, they use 0 instead of null in case of a number value, or their functions return an empty list or an empty string instead of null.

Others try to get completely rid of null with techniques like the NullObject pattern or the Optional/Maybe pattern.

We will have a look at these techniques later.

Now one might wonder: Why does the title of this article suggest we should love null?

Let’s see!

In real life, we are all used to the notion of ‘nothing’ appearing in thousands of different ways.

It is easy to come up with examples even a child would understand:

  • There is no chocolate in the fridge.
  • Fred doesn’t have a bicycle.
  • The class room is empty.

More than an astonishing 99.999% of the universe is nothing – just empty space.

It is therefore more than evident that any programming language (or, more generally, any technique used to represent data) must provide a way to express the notion of ‘nothing’.

In 1965, Tony Hoare had the brilliant idea to simply use the keyword (or symbol) null.

Richard Hoare, the inventor of 'null'

Sir Charles Antony Richard Hoare, the inventor of ‘null’, by Rama license: CC BY-SA

Some languages use other keywords such as nil, void, none or nothing, but the concept is the same.

null is indeed an incredibly important concept.

null is what allows us to state things like:

  • Alice’s birth date has not yet been entered in the database (alice.birth_date = null)
  • No orders have yet been placed by this customer (customer.order_list = null)
  • The operation succeeded without any errors (error = null)
  • There is no more beer in the fridge (fridge.beer = null)

 

Before looking at the merits of null, let’s have a look at some simple source code.

[Note] Note
In this article, I use Java in the source code examples. You might want to try out these simple examples in any other language you prefer.

If Alice has an email address, we can write code like:

String email = "alice@company.com";

And if she hasn’t an email address (or the address is unknown), we simply write:

String email = null;

Then we can check for the existence of an email address and take appropriate action:

if ( email != null ) {
   System.out.println ( "Alice's email address is " + email );
} else {
   System.out.println ( "Alice doesn't have an email address." );
}

Simple, elegant and practical!

So, what’s the problem? Why does null cause so many troubles?

It turns out that there is a very simple and unique reason for the many troubles with null:

Sometimes, we (the programmers) forget to consider the fact that a value might be null.

Yes, it is that easy:

if ( you_never_forget_to_check_for_null ) {
   System.out.println ( "Bravo!!!" );
   System.out.println ( "Enjoy and be proud of an application free of null pointer errors." );
}

Unfortunately, forgetting to check for null happens often in practice. And that’s the reason for so many null pointer errors, some of them leading to catastrophic consequences.

Suppose, for instance, that in the above source code example, we forget to check if Alice has an email address. We leave of the if and simply write.

System.out.println ( "Alice's email address is " + email );

There are two important questions:

  1. What should happen if email points to null at runtime?
  2. What will happen?

There are at least 3 things that could happen:

  • The program simply ignores null and prints:
    Alice's email address is
  • The program prints:
    Alice's email address is null
  • The program throws a NullPointerException

This is a trivial example of a null handling situation. Nevertheless, the only way to know what will happen is to try it out because it really depends on the programming language and the compiler we use. Ask any experienced Java programmer and you will see that most of them (me included) will struggle to predict the actual behaviour without hesitation. I tried out the code with Java version 8 and was eager to see the result because I didn’t have any idea. Here is the result displayed in the system console:

Alice's email address is null

One could argue that this is nice because the system clearly informs us that the email is unknown. But – most importantly – no NullPointerException is thrown.

We’ll come back to the question “What should happen?” in a while.

[Note] Note
If we want to understand how the NPE is avoided in the above example, we have to look at the source code of the Java Development Kit (JDK). We won’t go into the details of how the above string concatenation (using the operator +) works behind the scenes. But the interesting part is method valueOf in class java.lang.String:

public static String valueOf(Object obj) {
   return (obj == null) ? "null" : obj.toString();
}

As we can see, if the input value is null then the string null” is used. That’s why the above code displays:

Alice's email address is null

Note: You can yourself have a look at the JDK source code by unzipping file src.zip in your JDK’s root directory and then opening file java/lang/String.java in a text editor. If you want more information about Java’s + operator you might have a look at the top rated answer in the Stackoverflow question Concatenating null strings in Java.

We have just seen an example of a practice used to suppress the risk for a null pointer error.

A crucial question arises: Are practices like the above one – used to avoid null pointer errors – to be recommended. Do they increase the quality and reliability of software? Should you use these techniques in your code?

Before discovering the answer, let’s have a look at three other popular techniques aiming to ‘avoid null pointers’.

  1. using zero instead of null for numbers
  2. the Null object pattern
  3. the Optional/Maybe pattern

Using Zero Instead of Null

Suppose we are writing an on-line shop application that allows customers to buy products via internet. Suppose also that the shop owner must be allowed to enter a new product without entering a price, because the price is still unknown and will be entered later.

Which approach is better:

  1. We don’t allow null for the price field because this eliminates the risk for a null pointer error. If the price is unknown, we simply store the value zero (0) in the database.
  2. If the price is unknown, we store null in the database and open the door for null pointer errors.

The answer becomes obvious if we look at an excerpt of an excellent comment made by user Jay in the Stackoverflow question Is it better to return null or empty collection?

Many programs are unable to distinguish “don’t know” from blank or zero, which seems to me a potentially serious flaw. For example, I was shopping for a house a year or so ago. I went to a real estate web site and there were many houses listed with an asking price of $0. Sounded pretty good to me: They’re giving these houses away for free! But I’m sure the sad reality was that they just hadn’t entered the price. In that case, you may say, “Well, OBVIOUSLY zero means they didn’t enter the price — nobody’s going to give a house away for free.”

But the site also listed the average asking and selling prices of houses in various towns. I can’t help but wonder if the average didn’t include the zeros, thus giving an incorrectly low average for some places. i.e. what is the average of $100,000; $120,000; and “don’t know”? Technically the answer is “don’t know”. What we probably really want to see is $110,000. But what we’ll probably get is $73,333, which would be completely wrong. Also, what if we had this problem on a site where users can order on-line? (Unlikely for real estate, but I’m sure you’ve seen it done for many other products.) Would we really want “price not specified yet” to be interpreted as “free”?

User Jay also says:

I’ve often been frustrated by systems that cannot distinguish between zero and no answer. I’ve had a number of times where a system has asked me to enter some number, I enter zero, and I get an error message telling me that I must enter a value in this field. I just did: I entered zero! But it won’t accept zero because it can’t distinguish it from no answer.

How would the web shop behave if we used the second approach, that is to say we use null for product prices not yet entered?

The risk of displaying a price of zero and buying a product for free is instantly eliminated.

We would be required to test for null and display a message like “price not yet available” or “please call us”. If we forget to do this, then a null pointer error is thrown. This is undesirable, but much better than letting the user buy a house for free, or – why not – the set of all free houses available on the website.

The risk of calculating a wrong average price is also instantly eliminated.

Again, we would be required to test for null and ignore products with null prices. If we forget it, a null pointer error appears as soon as there is a price with null in the database. But this is of course much better than silently delivering wrong results.

We could easily find more examples of software defects caused by using zero (0) instead of null.

Moreover, we have to be aware that the same problems exist with similar approaches such as:

  • using an empty string (or the string null“) instead of null in case of a string value
  • using the value false instead of null in case of a boolean value

In all cases, the conclusion is obvious:

Instead of using a non-null value to represent ‘no data available’ it is (in most cases) much better to use null.

Yes, we increase the risk for null pointer errors. But we decrease the risk for outcomes that are worse, such as delivering wrong results without any error message and other unacceptable or catastrophic situations – for example letting users buy houses for free.

If our application crashes because of a null pointer error, our customer is unhappy.

If our application delivers wrong results or does other stupid or dangerous things, our customer is very unhappy.

‘unhappy’ is better than ‘very unhappy’.

Hence, we should embrace null and make it our friend and … love it!

 

So, what can we say about our introductory example in which we saw that the following code:

String email = null;
System.out.println ( "Alice's email address is " + email );

produces this result:

Alice's email address is null

In this specific case, the result might be acceptable. But the language/compiler shouldn’t decide this. As we have seen already, it would be much better to throw a NullPointerException because this would inform the programmer quickly about a problem with the code. null is virtually always a special case and as such it should explicitly be treated as a special case in the source code.

Even in this simple case, the correct solution:

if ( email != null ) {
   System.out.println ( "Alice's email address is " + email );
} else {
   System.out.println ( "Alice doesn't have an email address." );
}

is superior, because saying…

Alice doesn't have an email address.

…is obviously better (more understandable – especially for non-programmers) than saying:

Alice's email address is null
[Note] Note
In many cases, Java does throw a NullPointerException (or another exception, like IllegalArgumentException) if an input value is null.

For example, let’s compare two alternatives:

The following code:

String s = "foo";
s = s + null;
System.out.println ( s );

doesn’t throw a NullPointerException, but displays:

foonull

However, the behaviour is different if, instead of using the + operator, we use method concat in class String:

String s = "foo";
s = s.concat ( null );
System.out.println ( s );

Now a NullPointerException is thrown, because method concat doesn’t accept null as input.

The Null Object Pattern

The Null Object pattern takes the previously described practice – used for simple scalar values – a step further by applying the same idea to composite objects, that is to say objects composed of several data fields and operations.

Instead of using null, a special non-null object is used to represent ‘there are no data’, thus eliminating the risk for null pointer errors.

Let’s look at an example.

Suppose we have the following interface in Java:

import java.io.PrintWriter;

public interface ICustomer {

   public String getName();
        
   public void writeOrders ( PrintWriter writer );
        
}

A standard implementation of this interface would look like this:

import java.io.PrintWriter;

public class Customer implements ICustomer {

   private String name;

   public Customer ( String name ) {
      this.name = name;
   }
        
   public String getName() { return name; }

   public void writeOrders ( PrintWriter writer ){

      writer.println ( "List of orders:" );
      // more code to get orders and write them out
   }
}

And here is another implementation that applies the Null object pattern:

import java.io.PrintWriter;

public class NullCustomer implements ICustomer {

   public NullCustomer () {}
        
   public String getName() { return ""; }
        
   public void writeOrders ( PrintWriter writer ) {
      // do nothing
   }       
}

Now, instead of using null, a shared instance of NullCustomer would be used each time a customer doesn’t exist. For example, look at the following method signature:

public static ICustomer getCustomerByName ( String name );

This method would return an instance of NullCustomer (instead of returning null) if there is no customer with the given name in the database.

Because the basic idea of the null object pattern is exactly the same as for practices like ‘use zero instead of null‘, the null object pattern suffers from the same inconveniences and dangers described before: it easily leads to defects that are worse than a null pointer error.

In a comment to an interesting article with the title No more excuses to use null references in Java 8 (and with comments worth reading) user Henk De Boer eloquently describes what can happen:

I do agree with especially Erwin, that this style of programming does carry a risk with it. If you’re not careful, you really do obscure the cause of problems. In absence of no data (where not allowed), your code will simply keep running until all operations that you programmed are done and then things stop.

The result of the above is that simply “nothing has happened”. This can be nice (don’t bug the user or programmer with nasty errors), but you can actually be in a worse situation. The action that the user thought has happened, actually hasn’t happened at all. Yet there is no error and no indication anywhere that something has gone wrong.

Imagine a hotel booking example. The user should have entered a city, but forgot it. That value is now null, but since we’re functional advocated, we hate null and have None. All our code still runs. We locate the hotel correctly (it returns another None, no error) and we book the None hotel “correctly” (e.g. our operation is a noop).

When the user actually arrives at the hotel, with the wife and children, he finds no room has been booked at all. The hotel is completely full, it’s 11:00 PM and there are no other hotels nearby. I’m sure the user is not going to be happy, but hey, we didn’t had to deal with a NPE!

I’m slightly exaggerating perhaps, but this stuff DOES happen in “null friendly” languages.

The Null Object pattern might be useful in some rare situations, but we should be very careful before deciding to use it. For more information, refer to the Wikipedia article and look at the Criticism section which starts like this:

This pattern should be used carefully as it can make errors/bugs appear as normal program execution.

It is also interesting to note that appearances of null objects are virtually non-existent in real life. Such objects would be of little use and lead to funny, bizarre or even dangerous behaviour. Imagine a NullEmployee in real life: You pay him a salary but he doesn’t do anything. Or: You buy and eat plenty of NullFood, but it doesn’t have any taste and you still feel hungry.

The final conclusion is obvious:

Don’t use the Null Object pattern just to avoid null pointer errors.

Returning an empty collection instead of ‘null’

There is a popular and widely accepted advice in the world of software development that says:

You should always return an empty collection instead of ‘null’!

This established advice is often applied in practice and there is a lot to say about it. Therefore I have written a follow-up article that focuses on this subject: Is it Really Better to ‘Return an Empty List Instead of null’?

The Optional/Maybe Pattern

The basic idea of the Optional/Maybe pattern is this:

Instead of providing a non-null value or null, always provide a non-null container object that either contains a value or doesn’t contain a value.

You can also think of this container as a list having 0 or 1 elements.

This pattern is used in different languages, with different names for the container type. For example, in Java version 8, in Google’s Guava library and in Swift it is called Optional, in Scala it is called Option and Haskell uses Maybe as name.

To understand how it works, let’s have a look at a stripped version of the JDK source code of class Optional in Java version 8:

package java.util;

public final class Optional<T> {

   public static<T> Optional<T> empty()

   public static <T> Optional<T> of(T value)

   public static <T> Optional<T> ofNullable(T value)

   public boolean isPresent()

   public T get()
}

The first three static methods are used to create an Optional object:

  • empty() is used to create an empty container – the pendant to null.
  • of(T value) is used to create a container with a non-null value.
  • ofNullable(T value) is used to create a container with a nullable value (i.e. value can be null or non-null).

isPresent() is used to check if the container holds a non-null value.get() is used to retrieve the non-null value in case isPresent() returns true.

[Note] Note
There are more methods in Java’s Optional class, but they are irrelevant for the discussion in this article.

Now let’s have a look at a simple example of how Optional could be used in practice.

Suppose the following method exists – used to find a customer in a database by the customer’s name:

public static ICustomer findCustomerByName ( String name ) {
   ICustomer customer = null;
   // code to find customer in database
   // if customer not found return null
}

Obviously, this method can lead to a NullPointerException because null is returned if a customer with the given name doesn’t exist in the database.

To avoid this, we can return a non-null Optional<ICustomer> (instead of a nullable ICustomer) as follows:

public static Optional<ICustomer> findCustomerByName ( String name ) {

   ICustomer customer = null;
   // code to find customer in database
   // if customer not found null will be stored in variable customer
        
   // now create an Optional object and return it
   if ( customer != null ) {
      return Optional.of(customer);
   } else {
      return Optional.empty();
   }

   // Note: the above 'if' can be simplified as:
   // return Optional.ofNullable(customer);
}

As we can see, this method never returns null.

If the customer is found, it is stored in the Optional container object.

If the customer doesn’t exist, an empty Optional container object is returned.

We would use the new version of findCustomerByName like this:

Optional<ICustomer> customerOptional = findCustomerByName ( "Albert" );

// check if the customer has been found
if ( customerOptional.isPresent() ) {
   ICustomer customer = customerOptional.get(); // get the value stored in Optional
   System.out.println ( "Customer found: " + customer.toString() );
} else {
   System.out.println ( "Customer not found." );
}

There is an undeniable advantage of using the Optional pattern.

By looking at the method signature, we can see that an Optional<ICustomer> is returned (instead of simply an ICustomer). This makes it clear that the method returns with an empty Optional in case of ‘no data found’. Compare this with the ambiguity of the first version of the method which doesn’t use an Optional. In that case, without further information provided by a comment or an annotation, the API doesn’t tell us what happens in case of ‘no data found’. null could be returned, or a Null Object could be returned or an exception could be thrown. So, knowing that an Optional is returned, we also know that we have to check the presence of data with method isPresent(), before retrieving the value with method get().

Another advantage of the Optional/Maybe pattern is that you can use it in any programming language. If your preferred programming language doesn’t provide Optional/Maybe components in the standard libraries then you can simply create your own version and customize it to your specific needs.

Unfortunately, there are a number of considerable inconveniences with this pattern.

[Note] Note
The following observations are related to class java.util.Optional in Java 8. They don’t necessarily apply to variations of this pattern in other libraries or other programming languages.
  • A number of misuses cannot be checked and prevented by the compiler and therefore exceptions can still be thrown. For example:
    • If we call get() without first checking the presence of data with isPresent() then we get a NoSuchElementException if there is no value present. Here is a simple example:
      Optional<String> o = Optional.empty();
      String name = o.get(); // causes a NoSuchElementException

      This is similar to the situation of forgetting to check for null and then getting a NullPointerException. However, an advantage is that the NoSuchElementException is thrown immediately when get() is called. On the other hand, if we retrieve a null value from a method then a NullPointerException doesn’t occur immediately. It occurs (maybe much later) when a method is called on the null value. This can make the code more difficult to debug.

    • If a method is declared to return an Optional, nothing prevents the programmer who implements the method from (involuntarily) returning null instead of returning a non-null Optional.

      Example:

      public static Optional<ICustomer> findCustomerByName ( String name ) {
         return null;
      }
    • If we accidentally construct an Optional by calling method of() with null as input, we get a NullPointerException.

      Example:

      String name = null;
      Optional<String> o = Optional.of ( name ); // causes a NullPointerException
  • The compiler cannot force programmers to use Optional in their own methods. It is up to the programmer to decide whether he/she returns an Optional or simply sticks to returning null in case of no data.
  • Existing standard Java libraries cannot be retrofitted to use Optional because this would break backwards compatibility.
  • Using Optional is a bit cumbersome and requires more verbose/boilerplate code.

    Compare the traditional version of method findCustomerByName with the version that uses Optional:

    Traditional version:

    public static ICustomer findCustomerByName ( String name ) {
    
       ICustomer customer = null;
       // code to find customer in database
    
       return customer;
    }

    Version that uses Optional:

    public static Optional<ICustomer> findCustomerByName ( String name ) {
    
       ICustomer customer = null;
       // code to find customer in database
    
       return Optional.ofNullable(customer);
    }

    Using findCustomerByName also requires more code to write and read.

    Traditional code:

    ICustomer customer = findCustomerByName ( "Albert" );
    
    if ( customer != null ) {
       System.out.println ( "Customer found: " + customer.toString() );
    }

    Code that uses Optional:

    Optional<ICustomer> customerOptional = findCustomerByName ( "Albert" );
    
    if ( customerOptional.isPresent() ) {
       ICustomer customer = customerOptional.get();
       System.out.println ( "Customer found: " + customer.toString() );
    }
  • Using Optional consumes more memory and slows down execution because of the additional container (wrapper) objects that need to be created. In practice this might be totally negligible or a real performance bottleneck in exceptional cases.

    On the other hand null is always cheap in terms of memory and speed.

  • Class Optional is not serializable.

For more information, refer to this article and don’t miss the FAQ and reader comments.

We can conclude:

Under certain conditions the Optional/Maybe pattern helps to prevent null pointer errors. However, some misuses cannot be prevented by the compiler and the pattern requires more verbose code. Therefore a good amount of discipline is required. Another issue is that the wrapper objects create overhead at runtime.

In any case, the Optional/Maybe pattern doesn’t lead to 100% null-safety.

So, Is There A Better Solution?

We saw before that the trouble with null is this:

We sometimes forget to check for null in our code and take appropriate actions. This leads to potential null pointer errors.

Hence it is easy to come up with the ideal solution: If we sometimes forget to check for null then we simply need a compiler that forces us to check for null. If we forget to check for null or are too lazy to check for null or wrongly assume that a value will never be null at runtime then the compiler should nag and refuse to create executable code and force us to fix the code until all potential null pointer errors have been completely eliminated.

Is it technically feasible to build such a compiler?

Yes, it is!

It is indeed possible to design a language and implement a compiler with so-called null-safety built in.

It is possible to achieve 100% null-safety.

This is certainly an ultimate goal worth to be achieved because it means that the most frequent bug in applications will definitely be eliminated – at no costs for the developers. The benefits are obvious: less time and resources needed to debug and maintain code, more reliable software delivered to customers, and more satisfaction among all people involved in the project.

And it means we are back to our simple syntax for null checks:

if ( expression != null ) {
   // code for 'we have data'
} else {
   // code for 'no data'
}

If we forget the null check the compiler barks and gently reminds us to write reliable code. We are always on the safe side. We don’t need any of the unsatisfactory ‘avoid null‘ practices we saw before. And we won’t suffer from their inconveniences and dangers. We enjoy null-safe code.

Are there any programming languages with compile-time null-safety built-in?

I made some research and here are my observations:

[Note] Note
The following observations are incomplete and based on information I found at the time of writing (May 2014). If you see any omissions or outdated information, then please send me a comment and I will make an update.
  • Among the 20 most popular programming languages listed at the Tiobe index (Basic, C, C++, C#, Java, JavaScript, Lisp, Objective-C, Perl, PHP, Python, Ruby and more) none of them has null-safety built-in.
  • Some languages don’t have compile-time null-safety, but they have special language constructs that make checking for null and/or avoiding null pointer errors more easy.
    • C# has a Nullable<T> type that is similar to Optional<T> and can be expressed as T?. T can be any primitive value type (int, char, boolean, etc.) or a struct. It cannot be a reference type.
    • F# provides the Option monad. Pattern matching is used in idiomatic F# code to differentiate between ‘data’ and ‘no data’, and the compiler emits a warning if either case is not covered – so there is good compiler support. Null pointer errors can occur if F# interoperates with the .NET framework which is largely written in C# and not null-safe, or if the Option monad is not used idiomatically.
    • Gosu has some null-safe operators used to handle null values in expressions.
    • Groovy has the Safe Navigation Operator (?.) as well as the Elvis Operator (?:).
    • In Java there are some non-null annotations which are supported by some tools. However, there is no standard for this and different IDEs and tools support these annotations more or less in different ways, as explained in the Stackoverflow question Which @NotNull Java annotation should I use?
    • Swift (Apple’s new programming language for iDevices) supports the Optional pattern and provides the ? type suffix as syntactic sugar (e.g. String? is equivalent to Optional<String>).
  • The following 4 languages have null-safety natively built in:
    • Ceylon has an option type implemented directly in the core of the language, as well as some special operators for null handling.
    • Eiffel supports void-safe programming (Eiffel uses the term void instead of null). For more information search for ‘eiffel void safety’, refer to a quick overview or chapter Void-safe programming in Eiffel in the official documentation.
    • Kotlin enforces null safety during compilation, as explained here.
    • Practical Programming Language (PPL) – see below

Null-safety in PPL

PPL is an object-oriented, JVM-targeted programming language I created and is still a work in progress. PPL has been specifically designed from the ground up to help writing more reliable code in less time. This goal should be attained by embedding effective Fail-fast! features natively into the language and libraries. A maximum of bugs should be caught at compile-time or else as early as possible at runtime.

Of all the Fail-fast! features natively built into PPL (such as null-safety, Design by Contract, immutable objects, etc.), I consider null-safety to be the most effective feature contributing to more reliable code – for the reasons explained in this article.

The fundamental principle for achieving null-safety in PPL is this:

PPL makes a distinction between nullable and non-nullable types.

By default all values are non-nullable. Non-nullable values cannot be null at runtime and therefore can’t lead to a null pointer error.

Values that are allowed to be null at runtime must explicitly be declared as nullable in the source code. The compiler requires that nullable values must be checked for null before an operation can be executed on them. Thus null pointer errors can’t occur at runtime.

There are specific instructions and operators to support writing compact and readable null-safe code.

To see how PPL source code looks like, let’s rewrite our initial example in PPL.

The following code asks the user to enter an email address in the system console. If he/she doesn’t enter a value (just hits the <Enter> key) then email will be null. The second instruction checks for null and prints an appropriate message.

const nullable string email = system.console?.ask_string ( "Please enter Alice's email address: " )

if email is not null then
   system.out.write_line ( """Alice's email address is {{email}}""" )
else
   system.out.write_line ( "Alice doesn't have an email address." )
end

In the above code:

  • The const keyword declares a script constant (i.e. a variable whose value cannot be re-assigned) named email of type string.
  • The nullable keyword states that email is allowed to be null. By default (if nullable is omitted) null is not allowed for object references in PPL.
  • A Java application can be run with or without a system console. Therefore we must use the so-called safe navigation operator (?. instead of .) after system.console. If no system console is available then ask_string will not be executed and email will be null.
    Note: An improvement in the above source code would be to print an error message if no console is available.
  • The check for null (if email is not null) is required. If we omitted it, the compiler would generate an error in the instruction that prints out the email address. This is the key to compile-time null-safety.
  • The expression """Alice's email address is {{email}}""" uses PPL’s triple quoted string literal which allows us to embed expressions in a string literal between {{ and }}.
[Note] Note
If you want to try out this example yourself, proceed as follows after installing PPL:

  • Create file null_test.ppl in any directory and with the above source code as content.
  • Open a system console in the directory of the .ppl file you created and type:
    ppl null_test.ppl

Instead of using an if is null instruction we could also use the if_null: operator which is similar to the so-called Elvis operator (?:) in other languages:

const nullable string email = system.console?.ask_string ( "Please enter Alice's email address: " )

system.out.write_line ( """Alice's email address is {{email if_null: "not yet defined."}}""" )

Now, if email is null, the output will be:

Alice's email address is not yet defined.

There would be much more to say about null-safety in PPL. For more information and examples, please refer to chapter Null safety in PPL’s on-line manual.

There is, however, one important point to stress.

Look at the following source code:

var nullable string email = "alice@company.com"
                
if email is not null then
   system.out.write_line ( """Alice's email address is {{email}}""" )
else
   system.out.write_line ( "Alice doesn't have an email address." )
end

We can immediately see that in this case, the check for null is completely superfluous, because at runtime email contains a non-null value and the else branch will therefore never be executed.

The PPL compiler is able to see this too. Internally it uses static code analysis and keeps track of the null-state of all object references.

Therefore, we have to omit the if in the above example and simply write:

var nullable string email = "alice@company.com"
system.out.write_line ( """Alice's email address is {{email}}""" )

This peculiarity also works fine in non-trivial cases such as a variable which is changed several times in complex nested ifs and loops, because the compiler knows the null-state of any object reference in any location of the source code.

It turns out that this distinguishing feature is really useful in day to day programming because situations like the above one appear often in source code. Null-checks in PPL are only required if the null-state of a value cannot reliably be determined at compile-time – for example in case of a value read from an external resource at run-time. Hence, we are relieved from a lot of unnecessary checks for null.

Final Conclusion

null is an extremely important concept in every programming language.

Although null has caused plenty of bugs, often with severe consequences, we have to be very careful if we use techniques to avoid null (for example the NullObject pattern or the Optional/Maybe pattern), because doing so can lead to outcomes that are worse than null pointer errors.

The best solution is to use a programming language that provides compile-time null-safety and good support for handling null values in the source code. You can then use null as often as needed with no fear of null pointer errors. You enjoy 100% null-safety without any drawbacks, you are more productive and you deliver more reliable software.

Using Buffering Techniques for Large List Controls

Gallery

Ray Yagubyan

Ray Yagubyan

Making use of buffering techniques to efficiently and flawlessly render large quantities of items in list controls.

Introduction

The purpose of this article is to highlight the effectiveness of using buffering techniques when rendering large quantities of data. Combining several different methods for increasing the processing time of rendering can result in real-time rendering of items, even when the container list control owns millions of entries. This is targetted more towards custom owner-drawn components, the likes of tile components or custom list view components.

Background

While developing a framework of Metro style components, I stumbled across the need for buffering when working on a custom ListView component. A ListView is capable of containing any number of items, and rendering should be a seamless and flicker-free experience. In order to achieve this, different layers of buffering were aggregated until the rendering operation became visibily instantaneous.

Buffering Methods

To achieve buffering in custom controls, there are several different options available which provide the functionality. Below is an outline of the core concepts and their purposes when buffering GDI.

Double Buffering

public class MyControl : UserControl
{
    public MyControl()
    {
        DoubleBuffered = true;
        SetStyle(ControlStyles.OptimizedDoubleBuffer, true);
    }
}

A large number of components implement a protected DoubleBuffered property. This property internally signals that the component should execute any painting operations on a separate memory buffer.

What this means is that the Paint event does not execute on the graphics handle of the component directly, but instead a separate Graphics buffer is created in memory, and the painting operation occurs on that instead. One the painting operation has completed on the memory buffer, this buffer is then painted onto the component graphics handle.

The purpose of this is to enable the commit of a completed paint operation in a single operation. For instance, imagine a component responsible for rendering 1,000 items in a single paint operation, each with a 0.0004s rendering time. A single paint operation would consume 0.4s (400ms) to complete. During this 400ms, the control will actively update while the paint operation is occurring, resulting in partial graphics updates being committed to the visible screen while the operation is on-going. This is a consequence known as tearing, where parts of the component are being updated, while the old graphics are still visible.

Double buffering eliminates this issue by completing the 400ms painting operation on a separate handle, then replaces the entire component visible state in a single swoop, removing the tearing issue and appearing as though the update completed seamlessly.

Disabling WM_ERASEBKGND

public class MyControl : UserControl
{
    private const int WM_ERASEBKGND = 0x0014;

    protected override void WndProc(ref Message m)
    {
        if (m.Msg != WM_ERASEBKGND)
            base.WndProc(ref m);
    }
}

In Windows, a WM_ERASEBKGND message corresponds to a request sent to the active component when the background of the component should be erased. This message is responsible for only erasing the background, and thus becomes redundant when we begin implementing a custom drawn control.

This Windows message increases strain on a custom control, forcing the system to destroy the existing background prior to any painting operation. This increases the amount of work involved before any painting operation actually takes place, thus it becomes common practise to disable this Windows message and instead fill the Paint graphics handle with the background color, replicating the same process.

Buffered Graphics (and Buffered Graphics Context)

The .NET Framework supplies a BufferedGraphics class. This class, when instantiated, is responsible for retaining an active graphics handle which can be re-used for a painting operation. The major advantage of using this class is that a single, expensive paint operation can be retain in memory, so that a repeat painting operation does not need to render all of the relevant items again.

A BufferedGraphics object should be disposed and reset whenever the graphical interface requires updating, for example:

  • The control is resized; more information may need rendering, or the background color needs to be updated to fill the new region.
  • The control is scrolled; the list of visible items in the control need moving to accommodate the scroll.
  • The control has a mouse movement: a visible item may now be in the ‘hovered over’ state, resulting in a different color being drawn.

These situations require the existing graphics handle being disposed so the change in state can be committed to the control graphics handle. See the below example of the user of a BufferedGraphics object.

public class MyControl : UserControl
{
    private BufferedGraphics buffer;
    private BufferedGraphicsContext bufferContext;

    public MyControl()
    {
        // initialize the BufferedGraphics object to null by default
        buffer = null;

        // initialize the BufferedGraphicsContext object which is the
        // graphics context for the current application domain
        bufferContext = BufferedGraphicsManager.Current;
    }

    protected override void OnPaint(PaintEventArgs e)
    {
        // check whether our buffered graphics have been allocated yet,
        // if not then we need to create it and render our graphics
        if (buffer == null)
        {
            Rectangle bounds = new Rectangle(0, 0, Width, Height);

            // allocate our graphics buffer, which matches the dimensions of
            // our control, and uses the paint Graphics object as a base for
            // generating the Graphics handle in the buffered graphics
            buffer = bufferContext.Allocate(e.Graphics, bounds);

            // fill our graphics buffer with a white color
            buffer.Graphics.FillRectangle(Brushes.White, bounds);
        }

        // render our graphics buffer onto the target graphics handle for
        // the paint operation
        buffer.Render(e.Graphics);
    }

    protected override void OnResize(EventArgs e)
    {
        // check whether we have an existing graphics buffer which uses
        // some old dimensions (prior to the resize)
        if (buffer != null)
        {
            // dispose of the graphics buffer object and reset to null to force
            // the invalidation to re-create our graphics object
            buffer.Dispose();
            buffer = null;
        }

        // invalidate our control which will cause the graphics buffer to be
        // re-created and drawn with the new dimensions
        Invalidate();
    }
}

Slicing Large Data

In order to benefit from the above double buffering techniques when rendering a custom list control, it’s important to realise that there’s no realistic method of being able to render all items in the collection. When a control has upwards of one million rows, the painting operation would become too intensive for double buffering to make any sense.

Instead, to decrease the amount of work involved with painting, the collection needs slicing such that we only have to render a small segment of the data required. This is achievable by using mathematical formulae to determine which item is visible at the top of the control view region, and calculating how many items are visible from the top to the bottom.

In order to achieve any of this functionality, it’s important that either a constant or configurable field or property be available to define the height (or dimensions) of a single item. Below, let’s allow a property (ItemHeight) be available for the user to specify a custom height:

public class MyControl : UserControl
{
    private int itemHeight;

    public MyControl()
    {
        itemHeight = 18;
    }

    [Browsable(true)]
    public int ItemHeight
    {
        get { return itemHeight; }
        set { if (itemHeight != value) { itemHeight = value; Invalidate(); } }
    }
}

The default item height is 18px, which can be configured at design time or runtime. Whenever the item height is changed the control is invalidated.

The next stage is to create the collection which will store the items we are interested in displaying in the control. For the purposes of this tutorial the control will display a list of String objects. If we wish to properly monitor our collection for additions, removals or movement of items, we need to implement methods of corresponding back to our control on any of the Add, Remove etc. methods.

To make this simple, our control shall use the ObservableCollection<> class which implements the INotifyCollectionChanged interface, and we’ll hook into the CollectionChanged event to update the control.

public class MyControl : UserControl
{
    private int itemHeight;
    private ObservableCollection<string> items;

    public MyControl()
    {
        itemHeight = 18;
        items = new ObservableCollection<string>();
        items.CollectionChanged +=
             new NotifyCollectionChangedEventHandler(ItemsCollectionChanged);
    }

    [Browsable(true)]
    public int ItemHeight
    {
        get { return itemHeight; }
        set { if (itemHeight != value) { itemHeight = value; Invalidate(); } }
    }

    [Browsable(false)]
    public ObservableCollection<string> Items
    {
        get { return items; }
    }

    protected virtual void ItemsCollectionChanged(object sender, NotifyCollectionChangedEventArgs e)
    {
        
    }
}

The next stage is to implement an algorithm to enable scrolling when the number of visible items in the control would exceed the height of the view. This can be calculated using the item height property, the number of items and the current height of the control.

    protected virtual void CalculateAutoScroll()
    {
        // ensure that autoscrolling is enabled in the control for scrollbar visibility
        AutoScroll = true;

        // update the minimum size for the scrolling procedure, which ensures that the
        // maximum scroll value vertically is equal to the item height x item count
        AutoScrollMinSize = new Size(0, itemHeight * items.Count);
    }

This will display a scroll-bar which accommodates for any number of items in the collection. This method should be called any time the collection changes, so we must modify the ItemsCollectionChanged method to raise this calculation.

    protected virtual void ItemsCollectionChanged(object sender, NotifyCollectionChangedEventArgs e)
    {
        // recalculate the auto-scroll region to accommodate the changes
        CalculateAutoScroll();

        // invalidate the control so that any removed or moved items are updated
        Invalidate();
    }

The same method should also be raised when the item height property is changed, so that the new item height is applied to the algorithm.

    [Browsable(true)]
    public int ItemHeight
    {
        get { return this.itemHeight; }
        set
        {
            if (itemHeight != value)
            {
                itemHeight = value;
                CalculateAutoScroll();
                Invalidate();
            }
        }
    }

Once these have been configured, the operation for slicing data can begin. The calculation for the starting and ending indices are extremely easy to calculate using an algorithm.

The Paint method for the control must be overridden so we can render out items appropriately.

    protected override void OnPaint(PaintEventArgs e)
    {

    }

To calculate the starting index, the scroll position must be taken into account to properly generate the correct index. The base index is calculated based on the scroll position and the height of each item.

    int start = (int)Math.Floor((double)Math.Abs(AutoScrollPosition.Y) / (double)itemHeight;

The number of items available for view is calculated based on the height of the control and the height of each item.

    int count = (int)Math.Ceiling((double)Height / (double)itemHeight);

Additionally, if the user has scrolled to a position where only half of an item may be visible at the top of the control, we must take into account the positional offset. To account for this we must calculate the remaining pixels after dividing the scroll position by the height of each item.

    int offset = -(int)(Math.Abs(AutoScrollPosition.Y) % itemHeight);

The below image highlights where the values represent when calculating the indices and offset.

Finally, using these values we can devise which items in the control need to be rendered.

    protected override void OnPaint(PaintEventArgs e)
    {
        int start = (int)Math.Floor((double)Math.Abs(AutoScrollPosition.Y) / (double)itemHeight);
        int count = (int)Math.Ceiling((double)Height / (double)itemHeight);
        int offset = -(int)(Math.Abs(AutoScrollPosition.Y) % itemHeight);

        for (int i = 0; count > i && start + i < items.Count && 0 <= i; i++)
        {
            int index = start + i;
            string value = items[index];
    
            int x = 0;
            int y = (i * itemHeight) + offset;

            e.Graphics.DrawString(
                value,
                this.Font,
                Brushes.Black,
                new Rectangle(x, y, Width, itemHeight)
            );
        }
    }

The result of this code is a small, simple control which can handle rendering slices of data from a collection, rather than attempting to render all data into the control. The procedure outlined above is similar to a ‘clipping’ effect, where items which aren’t visible at neither the top nor bottom of the control are simply not rendered.

Combining the Methods

As mentioned in the introduction, the purpose of this article is to highlight how to use these rendering methodologies to represent large quantities of data in a simple control. We can combine the buffered graphics approach with the slicing of data to provide the interface for millions of rows with very little overhead.

The article has an attachment containing two core files: UI.cs and CustomBufferedList.cs. The CustomBufferedList.cs file contains the code for our list control which combines the double buffering and data slicing techniques.

A method implemented in the CustomBufferedList class adds support for identifying a row at a given location in the control. In order to calculate an item at a location, a similar method is used to the previous OnPaint implementation, where the starting index and number of visible items is calculated, and then the visible items are iterated through to determine whether the bounds would fall within the location.

        public int GetItemAt(Point location)
        {
            // calculate the starting index based on the scroll position 
            int start = itemHeight > 0 ?
                (int)Math.Floor((double)Math.Abs(AutoScrollPosition.Y) / itemHeight) : 0;

            // calculate the total number of items visible in the control
            int visible = (int)Math.Ceiling((double)Height / (double)itemHeight);

            // calculate the rectangle for the first item bounds
            Rectangle bounds = new Rectangle(
                0,
                -(int)(Math.Abs(AutoScrollPosition.Y) % itemHeight),
                Width,
                itemHeight
            );

            // increment through the items to match the item at the location
            for (int i = 0; 0 <= start + i && start + i < items.Count && visible > i; i++)
            {
                // check whether the mouse location falls within these bounds
                if (bounds.Contains(location))
                    return start + i;

                // increment the position of the bounds based on the item height
                bounds.Y += itemHeight;
            }

            // failed to match an item at this location
            return -1;
        }

All other content in the file is responsible for handling the process of using buffering techniques and using data slicing. The OnInvalidateBuffer() method is responsible for handling the invalidation of the BufferedGraphics object, and also supports ignoring the method invoke when updates have been suspended.

When adding large bodies of data to the CustomBufferedList, it’s good practise to invoke the BeginUpdate() and EndUpdate() methods. These methods temporarily suspend painting of the component, and then resume and invalidate the component, respectively.

// begin an update on the list, which suspends the layout
list.BeginUpdate();

// populate the list with a massive amount of values
for (int i = 0; 1000000 > i; i++)
    list.Items.Add(string.Format("Custom buffered list item {0}", i + 1));

// end the update to commit the changes to the buffer
list.EndUpdate();

Points of Interest

The CustomBufferedList component included with the project also implements OnMouseMove encapsulation which handles item highlighting. It would be just as simple to implement a selection process based on similar behaviour, which would provide the functionality of a ListView component.

Apologies if I have missed anything important or if some areas of the article appear rushed. I haven’t had much time to write articles, so this was an overview of how to achieve the goal which was set-out at the beginning.

Running a ClickOnce App as Adminstrator under Windows 8

Gallery

0539e-ray-yagubyan

Ray Yagubyan

Introduction

This article explains how to run a ClickOnce application as an Administrator under Windows 8, when the app also includes a SQL Compact Database.

My particular application must run as Administrator because it needs to pass data to a MYOB accounting data file, and the MYOB ODBC Driver requires elevated permission under Windows 8.  Because the app is to be distributed to many different customers, I like the deployment simplicity that ClickOnce offers.  However, ClickOnce deployments do not support changing the requestedExecutionLevel in the manifest to “requireAdministrator”.

Background

I saw a few articles such as this which put me on the right track.  The code checks if the app is running as Administrator, and if not, restarts the app as an Administrator.  However, I found a couple of problems with this solution. First, “Application.Current.Shutdown()” does not actually shutdown the application immediately, but continues to execute code, as I found described in several articles.  I found this caused my app to keep restarting ad inifinitum under Windows 7.  Secondly, when the app is restarted as Administrator, it loses its “ClickOnce” status.  Therefore, any references to System.Deployment.Application result in error – which has implications for the path to my app’s SQL Compact database.  The reference to ApplicationDeployment.CurrentDeployment.DataDirectory becomes invalid and the app chooses to look in the executable’s working directory for the database, which of course it cannot find, and returns the error “The underlying provider failed on Open. Database was not found”.

After several hours (actually, several days), I finally found the workarounds to all these issues, and my ClickOnce WPF app now runs beautifully under Windows 8, happily connecting to MYOB and sharing data.

Using the code

Here is the full code listing.

Class Application

    ' Application-level events, such as Startup, Exit, and DispatcherUnhandledException
    ' can be handled in this file.

    Protected Overrides Sub OnStartup(e As StartupEventArgs)

        Dim blnCloseInstance As Boolean = False

       ' Check if OS is Windows 8 or higher

        Dim osVer As System.OperatingSystem = System.Environment.OSVersion
        If osVer.Version.Major > 6 Or (osVer.Version.Major = 6 And osVer.Version.Minor >= 2) Then

            ' Check if user is NOT admin
            If Not IsRunningAsAdministrator() Then

                ' Setting up start info of the new process of the same application
                Dim processStartInfo As New ProcessStartInfo(Assembly.GetEntryAssembly().CodeBase)

                ' Set the DataDirectory as an argument to the new process
                processStartInfo.Arguments = "" & Chr(34) & ApplicationDeployment.CurrentDeployment.DataDirectory & Chr(34) & ""
                
                ' Using operating shell and setting the ProcessStartInfo.Verb to &ldquo;runas&rdquo; will let it run as admin
                processStartInfo.UseShellExecute = True
                processStartInfo.Verb = "runas"

                ' Start the application as new process
                Process.Start(processStartInfo)

                blnCloseInstance = True
                Application.Current.Shutdown()
                
            End If
        End If

        If blnCloseInstance = False Then

            'set DataDirectory
            If IsRunningAsAdministrator() = True Then
                Dim arguments As String() = Environment.GetCommandLineArgs()
                Try
                    Dim datadir As String = arguments(1)
                    AppDomain.CurrentDomain.SetData("DataDirectory", datadir)
                Catch ex As Exception
                    'already running as administrator - app was not restarted
                End Try
            End If

            ' Do your startup tasks

            MyBase.OnStartup(e)

       End If

    End Sub

    Public Function IsRunningAsAdministrator() As Boolean
        ' Get current Windows user
        Dim windowsIdentity__1 As WindowsIdentity = WindowsIdentity.GetCurrent()

        ' Get current Windows user principal
        Dim windowsPrincipal As New WindowsPrincipal(windowsIdentity__1)

        ' Return TRUE if user is in role "Administrator"
        Return windowsPrincipal.IsInRole(WindowsBuiltInRole.Administrator)
    End Function

End Class

This is a WPF application, so I have overridden Application_OnStartup.

First I check the current operating system.  I found the ClickOnce app runs fine under Windows 7, therefore there is no need to check whether the app is running as Administrator under Windows 7.

Dim osVer As System.OperatingSystem = System.Environment.OSVersion
        If osVer.Version.Major > 6 Or (osVer.Version.Major = 6 And osVer.Version.Minor >= 2) Then

If the OS is Windows 8 or higher, the app then checks if it is running as Administrator.  On the first execution, this will be False – so the app gets restarted by starting a new process using the same assembly name.  The important thing to note here is the argument passed to the process – which is the path to the SQL Compact datbase.  This is necessary for when the app restarts in non-ClickOnce mode.

' Check if user is NOT admin
            If Not IsRunningAsAdministrator() Then

                ' Setting up start info of the new process of the same application
                Dim processStartInfo As New ProcessStartInfo(Assembly.GetEntryAssembly().CodeBase)

                ' Set the DataDirectory as an argument to the new process
                processStartInfo.Arguments = "" & Chr(34) & ApplicationDeployment.CurrentDeployment.DataDirectory & Chr(34) & ""
                
                ' Using operating shell and setting the ProcessStartInfo.Verb to &ldquo;runas&rdquo; will let it run as admin
                processStartInfo.UseShellExecute = True
                processStartInfo.Verb = "runas"

                ' Start the application as new process
                Process.Start(processStartInfo)

                blnCloseInstance = True
                Application.Current.Shutdown()
                
            End If

The boolean variable blnCloseInstance determines whether the current instance will be closed.  It only gets set to True when the current OS is Windows 8 and the app is not running as Administrator.

The current instance of the app is then shutdown.  As noted above, Application.Current.Shutdown() does not immediately exit the application – the thread still runs and code continues to execute.  Therefore, I have ensured the remaining code in the sub is only executed when blnCloseInstance  = False.  So on the first execution under Windows 8, this code will not be executed.

When the app restarts in non-ClickOnce mode, it will be running as Administrator, and blnCloseInstance will be False.  Therefore only this code will execute:

        If blnCloseInstance = False Then

            'set DataDirectory
            If IsRunningAsAdministrator() = True Then
                Dim arguments As String() = Environment.GetCommandLineArgs()
                Try
                    Dim datadir As String = arguments(1)
                    AppDomain.CurrentDomain.SetData("DataDirectory", datadir)
                Catch ex As Exception
                    'already running as administrator - app was not restarted
                End Try
            End If

            ' Do your startup tasks

            MyBase.OnStartup(e)

       End If

Being in non-ClickOnce mode, the app does not support references to System.Deployment.Application, and it will report an error trying to locate the database.  The code above sets the SQL Compact database location manually, using the argument passed in when the process was started.

How to Use Onedrive Features in a Windows Phone 8 Application

Gallery

Ray Yagubyan

Ray Yagubyan

Introduction

Microsoft provides a Windows Live Connect SDK which allows you to easily connect, upload and download files from and to OneDrive (previously called Skydrive).

Background

Before starting, we have to download the latest Live SDK for Windows, Windows Phone 8, and .NET from http://msdn.microsoft.com/en-us/live/ff621310.aspx.

Start Creating Your Own Windows Phone 8 App

After downloading the version 5.5, we are going to create a new Windows Phone 8 application called « SkyDrive Example » in which the user can register using his Microsoft Live Account in order to send the file to Skydrive.

Left click on «References under your project in the Solution Explorer Windows and add these essential references to your project:

Change the title of our application to be more significant and add «SignInButton » to Toolbox to make the authentification process.

So, you will find many components, so Write « SignInButton » in the filter zone to find this functionality as shown below:

Well done. Now, we want to create a Client Id in order to store the user’s authorization information to not sign in every time the app opens.

Go to https://account.live.com/developers/applications/create and we will enter the name of our application and accept the term of uses.

After doing that, you will find your own client ID as shown in the picture below:

Now, you need to add this code into the MainPage.xaml in order the add the signInButton and don’t forget to add your own client ID in Client Id Zone:

<StackPanel x:Name="TitlePanel" 
Grid.Row="0" Margin="12,17,0,28">
            <TextBlock Text="SkyDrive Example" 
            Style="{StaticResource PhoneTextNormalStyle}" Margin="12,0"/>
            <TextBlock Text="Upload a File" Margin="9,-7,0,0" 
            Style="{StaticResource PhoneTextTitle1Style}"/>
        </StackPanel>

        
        <Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">

            <Controls:SignInButton Name="loginButton" 
            Content="SignInButton" HorizontalAlignment="Left" 
            Margin="110,75,0,0" VerticalAlignment="Top" 
            Scopes="wl.signin wl.offline_access wl.skydrive_update" 
            SessionChanged="loginButton_SessionChanged" Visibility="Visible"/>
            <Button Content="Upload" HorizontalAlignment="Left" 
            Margin="110,256,0,0" VerticalAlignment="Top" 
            Width="211" Click="Upload_Click"/>

        </Grid>

Now, it is time for managing our MainPage.cs. So that we don’t want to register every time the application launches, we are going to add the code below starting with adding the essential libraries:

using Microsoft.Live;
using Microsoft.Live.Controls; 

Don’t forget to declare the LiveConnectClient.

private LiveConnectClient client;

Add the following code for the loginButton_SessionChanged helper method.

private void loginButton_SessionChanged(object sender, LiveConnectSessionChangedEventArgs e)
        {
           
        if (e != null && e.Status == LiveConnectSessionStatus.Connected)
        {
        //the session status is connected so we need to set this session status to client
        this.client = new LiveConnectClient(e.Session);        
        }
        else
        {    
        this.client = null;
        }

        }

If the user clicks on download, he will send a file called ‘sample.txt’ that contains ‘hello world’ to his Onedrive Account.

 private async void Upload_Click(object sender, RoutedEventArgs e)
        {
            if (client != null)
            {
                try
                {
                    string fileName = "sample.txt";
                    IsolatedStorageFile myIsolatedStorage = 
                    IsolatedStorageFile.GetUserStoreForApplication();//deletes the file if it already exists
                    if (myIsolatedStorage.FileExists(fileName))
                    {
                        myIsolatedStorage.DeleteFile(fileName);
                    }//now we use a StreamWriter to write inputBox.Text to the file and save it to IsolatedStorage
                    using (StreamWriter writeFile = new StreamWriter
                    (new IsolatedStorageFileStream(fileName, FileMode.Create, FileAccess.Write, myIsolatedStorage)))
                    {
                        writeFile.WriteLine("Hello world");
                        writeFile.Close();
                    }
                    IsolatedStorageFileStream isfs = myIsolatedStorage.OpenFile(fileName, FileMode.Open, FileAccess.Read);
                    var res = await client.UploadAsync("me/skydrive", fileName, isfs, OverwriteOption.Overwrite);
                }
                catch (Exception ex)
                {
                    MessageBox.Show("Error: " + ex.Message);
                }
            }
            else
            {
                MessageBox.Show("Please sign in with your Microsoft Account.");
            }
        }

Conclusion

Well done! We have seen together how to implement the OneDrive API in your Windows Phone 8 application and how to send a simple file to the OneDrive.

Windows Phone 8.1 Media Editing API

Gallery

Ray Yagubyan

Ray Yagubyan

Introduction

WP 8.1 is one of major update for Windows Phone. WP 8.1 has unveiled new APIs, new universal apps concept, inclusion of WinRT APIs, new UI controls and much more. One of new API introduced is media editing API.

In earlier days, we were using Movie Maker or other 3rd party desktop softwares to trim the video, to make a composition of multiple video, to apply various effects etc. We were required to have a computer with more memory & high-end processors, but now our smartphones are enough powerful to do such tasks. So let’s get a deep dive in new media editing API of Windows Phone 8.1.

Windows Media Editing API

Media editing API has MediaClip class, whose object represents a single media i.e. video, image or a solid color video clip. To perform any kind of editing operation on a media file, you must first create MediaClip object. MediaClip provides three static method to create object.

MediaClip.CreateFromFileAsync(IStorageFile file)

Which creates a MediaClip object from a video file.

MediaClip.CreateFromImageFileAsync(IStorageFile file, TimeSpan originalDuration)

Which creates a MediaClip object from an image file. The parameter “originalDuration” has use while we create composition of media files. It represents how long the image would be displayed in the composed video clip.

MediaClip.CreateFromColor(Color color, TimeSpan originalDuration)

Which creates a solid color video clip that displays a single color for a specified length of time. Solid color video clips are typically used to create an explicit gap between video segments.

After creating media clip, you will have object of particular file. Then you can apply effects as well as editing. Let’s go through one by one.

 

Trimming

Trimming the video is now just two steps process. MediaClip object has two properties (i) TrimTimeFromStart (ii) TrimTimeFromEnd. After creating MediaClip, you just have to set these two properties. After setting it, the MediaClip will have trimmed media. You can change later on the trimming times as many times as you want. We will see further how to render this MediaClip into a file.

// Create MediaClip object
MediaClip objMediaClip = await MediaClip.CreateFromFileAsync(file)

// Trim from objMediaClip everything after specified position (1 minute & 20 seconds)
objMediaClip.TrimTimeFromStart = new TimeSpan(0,1,20);

// Trim from objMediaClip everything after the specified position
objMediaClip.TrimTimeFromEnd = objMediaClip.OriginalDuration - new TimeSpan(0,2,9);

Slow motion & video stabilization effects

Microsoft has MFT (Media Foundation Transform) platform, through which one can developer C++ WinRT components. These can be used to apply various video playback & filter effects.

Windows.Media.Effects namespace is dedicated to pre-defined effects, which can be used to apply on any video file. One of effect is slow motion effects. Windows.Media.Effects has class SlowMotionEffectDefinition, which is used to apply slow motion effects to media. That class has one property called TimeStretchRate. It refers how slower the video will be. It takes double value of less than 1. Hence, if you set TimeStretchRate as 0.5, the video speed will be half of original. Setting its value greater than 1 throws exception. So don’t consider its use for fast motion video effects.

Now to apply the slow motion effect to any video, first you have to create its MediaClip object which is essential for media editing. MediaClip object has IList<IVideoEffectDefinition> property called VideoEffectDefinitions. So first all you have to create object of SlowMotionEffectDefinition and set TimeStretchRate property. Then add that object to VideoEffectDefinitions list. That’s it, your video is now in slow motion. We will see later on how to preview and how to save video with effects.

// Let's consider we have already MediaClip object.

// Create object of SlowMotionEffectDefinition
var objSlowMotionEffectDefinition = new SlowMotionEffectDefinition();

objSlowMotionEffectDefinition.TimeStretchRate = 0.6;

// Add effect object to MediaClip object's VideoEffectDefinitions list.
objMediaClip.VideoEffectDefinitions.Add(objSlowMotionEffectDefinition);

 

Similarly you can also add video stabilization effect. The VideoStabilization effect can help reduce shakiness in video. That effect resides in Windows.Media namespace. It has only class named VideoEffects, which is static class. To add this effect you don’t have to create an object. It has static string property VideoStabilization, which is activatable class ID of that video effect definition.

// Create object of VideoEffectDefinition
// Pass static string property VideoEffects.VideoStabilization as argument
var objVideoStabilization = new VideoEffectDefinition(VideoEffects .VideoStabilization);

// Add effect object to MediaClip object's VideoEffectDefinitions list.
objMediaClip.VideoEffectDefinitions.Add(objVideoStabilization);

Filter & other video effects

Nokia Imaging SDK provides a plethora of filters for image processing. Unfortunately, it doesn’t work for videos. We can solve this problem by developing C++ WinRT components using MFT. According to MSDN, Media Foundation transforms (MFTs) provide a generic model for processing media data. MFTs are used for decoders, encoders, and digital signal processors (DSPs). In short, anything that sits in the media pipleine between the media source and the media sink is an MFT.

MSDN has provided a sample with several effect source code, wiz grayscale, fisheye, pinch, warp and invert. The sample also shows how to apply these effects in playback. No words for saving after applying the effects. So to apply MSDN sample’s effect is quite similar to slow motion & video stabilization effect. You have to first add WinRT C++ components from MSDN sample to your own project and then you have to define activatable class IDs in WP 8.1 project’s manifest file. Add below given lines by opening manifest file in text editor before </Package>.

<Extensions>

    <Extension Category="windows.activatableClass.inProcessServer">

      <InProcessServer>

        <Path>GrayscaleTransform.dll</Path>

        <ActivatableClass ActivatableClassId="GrayscaleTransform.GrayscaleEffect" ThreadingModel="both"/>

      </InProcessServer>

    </Extension>

    <Extension Category="windows.activatableClass.inProcessServer">

      <InProcessServer>

        <Path>PolarTransform.dll</Path>

        <ActivatableClass ActivatableClassId="PolarTransform.PolarEffect" ThreadingModel="both"/>

      </InProcessServer>

    </Extension>

    <Extension Category="windows.activatableClass.inProcessServer">

      <InProcessServer>

        <Path>InvertTransform.dll</Path>

        <ActivatableClass ActivatableClassId="InvertTransform.InvertEffect" ThreadingModel="both"/>

      </InProcessServer>

    </Extension>

</Extensions>

 

Now each effect has its own activatable class ID, you have to first create object of VideoEffectDefinition class & pass that activatable class ID as argument in constructor. Finally add object of VideoEffectDefinition to MediaClip, that’s it.

// Create object of VideoEffectDefinition, pass acitvatable class ID as parameter

var objGrayScaleEffect = new VideoEffectDefinition("GrayscaleTransform.GrayscaleEffect");
objMediaClip.VideoEffectDefinitions.Add(objGrayScaleEffect);

var objInvertEffect = new VideoEffectDefinition("InvertTransform.InvertEffect");
objMediaClip.VideoEffectDefinitions.Add(objInvertEffect);

 

In MSDN sample fisheye, pinch & warp effect is defined in single WinRT componenet. To apply any of effect among them you need to pass configuration parameter, with activatable class. VideoEffectDefinition’s constructor has one more overload, which takes a key-value pair to configure the effect.

// First define configuration

PropertySet configuration = new PropertySet();
configuration.Add("effect", "Fisheye");
// configuration.Add("effect", "Warp");
// configuration.Add("effect", "Pinch");

// Create object of VideoEffectDefinition, pass acitvatable class ID and configuration as parameter
var objPolarEffect = new VideoEffectDefinition("PolarTransform.PolarEffect", configuration);

// Add effect object to MediaClip object's VideoEffectDefinitions list.
objMediaClip.VideoEffectDefinitions.Add(objPolarEffect);

Saving video

We have learned how to apply effects & trimming, now it’s turn to save the video. MediaEditing API has one more important class called MediaComposition. MediaClip represents a single media file, while MediaComposition is a group of MediaClip objects. It allows you manage all the MediaClip objects in composition.

Composing a video with multiple clips is complex task, it is better to have preview of it, isn’t it? MediaComposition provides a preview of itself. So to preview the video on which you have applied effects, you have to first add MediaClip object to MediaComposition and then generate preview stream. Set that stream as source to MediaElement. You can also set height & width of preview.

// Create object of MediaComposition class
var objMediaComposition = new MediaComposition();

// Add MediaClip to composition after applying effects
objMediaComposition.Clips.Add(objMediaClip);

// Generate preview stream & set as source to MediaElement
MediaElement.SetSource(objMediaComposition. GeneratePreviewMediaStreamSource(360, 240));

Now to save MediaClip you have to call its asynchronous method RenderToFileAsync(IStorageItem file).

// Create file using save picker or in local/temporary folder
var file = await ApplicationData.Current.LocalFolder.CreateFileAsync(&ldquo;MyVideo.mp4&rdquo;);

// Render MediaComposition to file.
await objMediaComposition.RenderToFileAsync(file);

 

That’s it, your dream of media editing on Windows Phone is accomplished. Now you can edit media files from your WP apps.