About Bill Bejeck

Husband, father of 3, passionate about software development.

Google Guava – Futures

This post is a continuation of my series on Google Guava, this time covering Futures. The Futures class is a collection of static utility methods for working with the Future/ListenableFuture interface. A Future is a handle to an asynchronous task, either a Runnable or Callable, that was submitted to an ExecutorService. The Future interface provides methods for: getting the results of a task, checking if a task is done, or canceling a task. The ListenableFuture interface extends the Future interface and adds the ability to set a completion listener to run once a task is finished. To create a ListenableFuture you first need to decorate an ExecutorService instance like so:
 
 
 
 
 

ExecutorService executorService = MoreExecutors.listeningDecorator(Executors.newCachedThreadPool());

Now all submitted Callables/Runnables will return a ListenableFuture. MoreExecutors can be found in the com.google.common.util.concurrent package. ListenableFutures were covered in the previous post. There are too many methods in Futures to effectively cover in one post, so I am only going to cover: chain, transform, allAsList and successfulAsList. Throughout this post, I will refer to Futures and ListenableFutures interchangeably.

Chain

The chain method returns a ListenableFuture whose value is calculated by taking the results from an input Future and applying it as an argument a Function object, which in turn, returns another ListenableFuture. Let’s look at a code example and step through it:

ListenableFuture<List<String>> indexSearch = 
              luceneSearcher.searchAsync('firstName:martin');

Function<List<String>, ListenableFuture<List<Person>>> queryFunction = 
 new Function<List<String>, ListenableFuture<List<Person>>>() {
            @Override
            public ListenableFuture<List<Person>> apply(final List<String> ids) {
                 return dataService.getPersonsByIdAsync(ids);
            }
        };

ListenableFuture<List<Person>> results = 
              Futures.chain(indexSearch, queryFunction,executorService);
  1. Line 1 is executing an asynchronous search using Lucene and will return a list of id’s that represent the primary key of a person record stored in a database. (I created a small index where the only data stored in Lucene is the id’s and the rest of the data was indexed only).
  2. Lines 4 – 11 are building the function object where the apply method will use the results from the search future as input. The future returned from apply is a result of the call to the dataService object.
  3. Line 12 is the future that is returned from the chain call. The executorService is used to run the function once the input future is completed.

For additional clarity, here is what the searchAsync and getPersonsByIdAsync methods are doing. These method calls are from lines 2 and 8 respectively, in the previous code example:

public ListenableFuture<List<String>> searchAsync(final String query)  {
	        return executorService.submit(new Callable<List<String>>() {
	            @Override
	            public List<String> call() throws Exception {
	                return search(query);
	            }
	        });
  }

public ListenableFuture<List<Person>> getPersonsByIdAsync(final List<String> ids) {
        return executorService.submit(new Callable<List<Person>>() {
            @Override
            public List<Person> call() throws Exception {
                return getPersonsById(ids);
            }
        });
    }

The chain method has two signatures:

  1. chain(ListentableFuture, Function)
  2. chain(ListenableFuture, Function, ExecutorService)

When determining which method to use there are a few points to consider.
If the input future is completed by the time chain is called, the supplied function will be executed immediately in the calling thread. Additionally, if no executor is provided then a MoreExecutors.sameThreadExecutor is used. MoreExecutors.sameThreadExecutor (as the name implies) follows the ThreadPoolExecutor.CallerRunsPolicy, meaning the submitted task is run in the same thread that called execute/submit.

Transform

The transform method is similar to the chain method, in that it takes a Future and Function object as arguments. The difference is that a ListenableFuture is not returned, just the results of applying the given function to the results of the input future. Consider the following:

List<String> ids = ....
ListenableFuture<List<Map<String, String>>> dbRecords =   
                                           dataService.getPersonDataByIdAsync(ids);

 Function<List<Map<String, String>>,List<Person>> transformDbResults = 
  new Function<List<String>, List<Person>>() {
              @Override
              public List<Person> apply(List<Map<String, String>> personMapList) {
                      List<Person> personObjList = new ArrayList<Person>();
                      for(Map<String,String> personDataMap : personMapList){
                             personObjList.add(new Person(personDataMap);
                      } 
                      return personObjList;
                    }
     };

ListenableFuture<List<Person>> transformedResults = 
                      Futures.transform(dbRecords, transformDbResults, executorService);
  1. On line 2 an asynchronous database lookup is performed
  2. On line 4 a function object is being created, but on line 8, notice the return type is List<Person>

The transform method has the same overloaded method calls as chain, with the same caveats.

AllAsList

The allAsList method will take an arbitrary number of ListenableFutures either as varargs or in the form of an Iterator<ListenableFuture>. A ListenableFuture is returned whose value is a list of all of the results of the inputs. The values returned in the list are in the same order as the original list. If any of the input values were cancelled or failed then the returned ListenableFuture will be cancelled or fail as well. Canceling the returned future from the allAsList call will not propagate down to any of the original tasks submitted in the list.

ListenableFuture<List<Person>> lf1 = getPersonsByFirstNameFuture('martin');
ListenableFuture<List<Person>> lf2 = getPersonsByFirstNameFuture('bob');
ListenableFuture<List<List<Person>>> lfResults = Futures.allAsList(lf1, lf2);
//assume lf1 failed
List<List<Person>> personLists = lfResults.get() //call results in exception

 
SuccessfulAsList

The successfulAsList method is very similar to allAsList, but is more forgiving. Just like allAsList, successfulAsList returns a list of results in the same order as the input list, but if any of the inputs failed or were cancelled the corresponding value in the list is null. Canceling the returned future will not cancel any of the original inputs as well.

ListenableFuture<List<Person>> lf1 = getPersonsByFirstNameFuture('martin');
ListenableFuture<List<Person>> lf2 = getPersonsByFirstNameFuture('bob');
ListenableFuture<List<List<Person>>> lfResults = Futures.successfulAsList(lf1, lf2);
//assume lf1 failed
List<List<Person>> personLists = lfResults.get();
List<Person> listOne = personLists.get(0) //listOne is null
List<Person> listTwo = personLists.get(1) //listTwo, not null

 
Conclusion

Hopefully this was helpful in discovering the usefulness contained in the Futures class from Google Guava. I have created a unit test that shows example usages of the methods described in this post. As there is a fair amount of supporting code, I have created a project on gihub, guava-blog. This project will also contain the source code from my previous posts (Monitor, ListenableFuture) on Guava. As always comments and suggestions are welcomed.

Resources

 
Reference: Google Guava – Futures from our JCG partner Bill Bejeck at the Random Thoughts On Coding blog.

Related Whitepaper:

Bulletproof Java Code: A Practical Strategy for Developing Functional, Reliable, and Secure Java Code

Use Java? If you do, you know that Java software can be used to drive application logic of Web services or Web applications. Perhaps you use it for desktop applications? Or, embedded devices? Whatever your use of Java code, functional errors are the enemy!

To combat this enemy, your team might already perform functional testing. Even so, you're taking significant risks if you have not yet implemented a comprehensive team-wide quality management strategy. Such a strategy alleviates reliability, security, and performance problems to ensure that your code is free of functionality errors.Read this article to learn about this simple four-step strategy that is proven to make Java code more reliable, more secure, and easier to maintain.

Get it Now!  

Leave a Reply


nine − 9 =



Java Code Geeks and all content copyright © 2010-2014, Exelixis Media Ltd | Terms of Use | Privacy Policy
All trademarks and registered trademarks appearing on Java Code Geeks are the property of their respective owners.
Java is a trademark or registered trademark of Oracle Corporation in the United States and other countries.
Java Code Geeks is not connected to Oracle Corporation and is not sponsored by Oracle Corporation.

Sign up for our Newsletter

20,709 insiders are already enjoying weekly updates and complimentary whitepapers! Join them now to gain exclusive access to the latest news in the Java world, as well as insights about Android, Scala, Groovy and other related technologies.

As an extra bonus, by joining you will get our brand new e-books, published by Java Code Geeks and their JCG partners for your reading pleasure! Enter your info and stay on top of things,

  • Fresh trends
  • Cases and examples
  • Research and insights
  • Two complimentary e-books