JEN KING: Hi, I'm Jen King, and I'm
the Technical Lead on the Drive Android API.
Today I'm going to talk about the DriveEventService, which
allows your app to respond to background events.
First, we'll cover change events, which notify you
of changes to a particular item.
Next, we'll introduce completion events,
which tell you the outcome a particular action.
For example, whether a file you created
was uploaded successfully.
Last, we'll show you how to use completion events to resolve
conflicts when multiple apps or multiple devices
edit the same file.
Let's get started.
Some of you may already be aware of change event listeners,
which allow you to listen for changes to a particular item
while your app is running.
But what if you want to inform users that a file
they're interested in has changed
while your app isn't running.
The newly added change event subscriptions
allow you to do just that.
Subscriptions deliver exactly the same events
as are delivered to a change event listener,
but you request them and receive them
in a slightly different way.
To add a change event subscription,
retrieve the Drive resource you're interested in
and simply call add change subscription.
But now you're probably wondering
where these events get delivered.
That's a good question.
To handle background events, you need
to create a service that extends DriveEventService
and add this class to your apps manifest.
You'll override the Handler method
in this class for each event in DriveEventService
that you care about.
Let's try this out.
First, let's create the service class
that will handle the change events.
Create a class that extends DriveEventService--
in this example, my DriveEventService.
Override the onChange method in your DriveEventService subclass
and print out the event using Log.d.
This is where you should do any application specific processing
that you need to do.
The last thing you need to do is define your service
in the manifest so that the Drive API can find it.
In AndroidManifest and XML, create
an entry for your service.
Set the Android exported attribute to true
and add an intent filter for the handle event actions
so that Drive knows how to identify your service.
Now whenever name gets updated by another app on the device
or the Drive API download changes from the server,
your app will receive a change event.
Now that you've got your DriveEventService set up,
you can easily add support for handling completion events.
When you make a call to the Drive API
you receive a pending result with a status.
The pending result status tells you
whether this action was successfully
applied locally on the device.
But the action might not get sent to the server
until later-- for instance, if you're offline.
Completion events let you know when the action has actually
made it up to the server if it was successfully
applied on the device.
You'll only receive the completion event
is the original call successful, meaning the pending
result returned from that call had a successful status.
Completion events themselves can result
in either success, failure, or conflict.
We'll start by looking at how to request these notifications
and how to handle success and failure results.
Completion events are requested for a single action,
rather than for a single file or folder like change events.
To request a completion event, create an execution options
builder call set notify on completion
and pass the new object as a parameter in your file creation
or content update method calls.
You can also add an optional tracking tag
to the execution options to make it easier
to identify which action the completion event
corresponds to.
To add a tracking tag call set tracking tag
when you create your execution options.
This tracking tag will be returned to you
when the event is delivered.
To handle events when they're fired,
use the same DriveEventService class you created before
and override the onCompletion method.
You can compare the results of event.getStatus
to CompletionEvent.statuses success
to determine whether the action was successful.
Similarly, check for CompletionEvent.status failure
to determine if the action failed.
For more info on what other data the completion event contains,
take a look at the documentation for the completion event class.
Last, once you've processed the completionEvent,
you need to dismiss the event to acknowledge
that you were able to respond.
If your app can't process the event right away-- for example,
if your app is offline and needs to do a server query to process
it-- you can snooze the event.
The Drive API will notify you about it again in the future.
You should dismiss or snooze every event that you receive.
In addition to success and failure,
actions can also result in conflicts.
Conflicts can happen when two apps on the same device
head at the same file at the same time,
or when a user interacts with your app from multiple devices.
Let's take a look at how you can use completion events
to resolve a conflict.
Requesting a conflict event is almost
exactly the same as requesting a standard completion event.
The only difference is the conflict strategy.
You set the conflict strategy using the set conflict strategy
method when creating your execution options.
The default strategy, overwrite remote,
overrides any changes on the server.
To respond to a conflict, you need
to use the key promote strategy to keep the remote changes.
Conflict events are a type of completion event.
So you'll receive these events in exactly the same way, using
the onCompletion method of your DriveEventService subclass.
If the upload results in a conflict,
you'll receive an event with the status-status conflict.
Remember to dismiss or snooze the event
when you finish processing it.
Each app will handle conflicts differently.
You might be able to do a three way merge
or you might want to ask the user.
To get the server version of the file,
open the file from the devices you normally
would using DriveFile.open file.
As long as your online this call will download the new version
from the server.
To get your modified version of the file,
call getModifiedContentsInputStream
on the completion event.
Last, to get your original local copy
before your modification was made,
call getBaseContentsInputStream on the completion event.
Now compare the three copies of the file
to create the merged version, write this content
as you normally would using contents.commit
and dismiss the completion event.
See our sample code for an example
of merging items in a task list.
You've just learned how to use the DriveEventService
to respond to change events, completion
events, and conflicts.
We can't wait to see what you built with these APIs.
I'm Jen King, and thanks for watching.