IT Lesson

What’s the difference between reality and theory? In theory, there is no difference. But reality often imposes unanticipated constraints on developers. These may come in the form of bandwidth restrictions, memory limits, timeouts, or other requirements of the systems that interact with your application.

My team recently built an application that helps us analyze the scheduling and usage of conference rooms at Google. We use the new Calendar API v3 on Google App Engine to read the rooms’ schedules, which we combine with actual occupancy data to calculate utilization and other metrics.

As you might imagine, Google has a lot of conference rooms (I believe the last official count was “more than twelve.”) And many of the rooms seem to be booked fairly solid. That means we need to read a lot of data from Calendar. So much, in fact, that our queries time out if we try to read an entire calendar at once. But the API team anticipated “Google scale” use and designed a mechanism that allows us to retrieve data in batches.

The idea is simple. When you create a request, you specify the page size: the maximum number of results you’d like Calendar to return in one batch. Calendar returns the data you requested, along with an opaque page token, which you can think of as a bookmark. To retrieve the next batch of data, you ask the API for the next page token and include the new token in your next request. The page token keeps track of the results you’ve already seen, so Calendar can send the next batch each time. You repeat this process until you’ve exhausted all the results.

Here’s how we did this in Java:

public void getRoomEvents(String roomEmail) throws IOException {
    // Create a request to list this room’s events (see code, below)
    Calendar.Events.List listRequest = getListRequest(roomEmail);
    do {
      // Retrieve one page of events
      Events events = executeListRequest(listRequest);
      List eventList = events.getItems();

      // Process each event
      for (Event event : eventList) {
        processEvent(event);
      }

      // Update the page token
      listRequest.setPageToken(events.getNextPageToken());

    // Stop when all results have been retrieved
    } while (listRequest.getPageToken() != null);
  }

  // Create a request to list the events for a room
  private Calendar.Events.List getListRequest(String roomEmail)
        throws IOException {
    return calendarClient.events().list(roomEmail)
        .setMaxResults(1000) // Limit each response to 1000 events
        .setPageToken(null)  // Start with the first page of results
        // Return an individual event for each instance occurrence of a
        // recurring event
        .setSingleEvents(true); 
  }

We call getRoomEvents() for each room, using the room’s email address to identify it to Calendar. (You can retrieve events from your own calendar by substituting your own email address.) Then getListRequest() creates a request that we will send to Calendar. The request asks for a list of up to 1000 events from the room’s calendar.

The remainder of getRoomEvents() is a loop that executes the request, processes the results, and updates the page token in preparation for the next request. The loop continues, retrieving and processing each subsequent page of results, until the entire list has been returned. The call to getNextPageToken() indicates the end of the results by returning a null value.

By paginating our requests we avoid timeouts and reduce memory requirements. As an added benefit, each request completes fairly quickly, which means it’s also quick to retry if an error should occur. And finally, a multithreaded application may be able to process one or more pages of results while it retrieves the next, speeding execution. These advantages have led developers at Google to adopt pagination as a best practice. Look for it in our APIs when you need to exchange large amounts of data, and consider adding it to your own services.

If you have questions about our services or APIs, or if you want to see what other developers are doing with Google Calendar, check the discussions and documentation in the Google Apps Calendar API forum.

Adam Liss profile Adam is an engineer who believes that "technical" shouldnt necessarily mean "difficult." He enjoys building infrastructure and tools that make Googlers more productive. Before joining Google in 2010, he built network-security appliances and one of the first wireless application delivery platforms.

Before I write up todays technology Tuesday post, I want to take a moment to reflect on life in general.  As many of you know, I lost my Grandma Vicky less than two weeks ago.  I spent a lot of time reflecting on our time together and I can truly say that I was fortunate to have such a loving grandmother who was and is such an important part of my life. 

I truly miss her more than words can say.


A week after finding out that my Grandma passed, I found out that my ex-boyfriend had passed as well.  He was only 25.  Though he and I grew apart and havent spoken for years, I truly wished only the best for him.  He was my first "love" and he has always had a special place in my heart.  As much as I was left speechless by my Grandmas death, I am having just as hard of a time finding the words to express my deepest sympathies and regrets for his death as well. 

I truly believe that everything happens for a reason, but I can never find or explain the reasons why we have to lose the ones we love.  It truly breaks your heart and makes you question the world.  Ive honestly felt like nothing has been going right lately.  As hard as it is, I keep reminding myself of something my mom told me once:


As hard as it is to cope with lose and to cope with change, I know I am fortunate for the relationships that I have had and that there are so many more who are going through worse.  As hard as things are to cope with or manage, we somehow need to put one foot in front of the other and try to move on.  To the same idea, I found this other quote on pinterest and I really like it:


The past week and a half, I have spent a good amount of time crying and a lot of time reminiscing.  Fortunately Im surrounded by supportive family, friends, neighbors, co-workers and followers who have put up with my distance and my ramblings.  So for now, my rambling will cease for the time being and Ill put one foot in front of the other.  Perhaps getting myself back on track with my blog and my life will help ease the pain.

This two week long poll had a lot of votes, and the winner was the most recent addition to the poll... how to find out a Microsoft Word documents reading level.  This tutorial is actually SUPER EASY!!! 


Here are the official poll results...


 And here is the incredibly easy tutorial!!!



As for next weeks poll, Ill be adding a blogger tutorial: how to host a linky party!