Using Push Queues in Java
In App Engine push queues, a task is a unit of work to be performed by the application. Each task is an object of the TaskOptions class . Each Task object contains an application-specific URL with a request handler for the task, and an optional data payload that parameterizes the task.
For example, consider a calendaring application that needs to notify an invitee, via email, that an event has been updated. The data payload for this task consists of the email address and name of the invitee, along with a description of the event. The webhook might live at
/app_worker/send_email
and contain a function that adds the relevant strings to an email template and sends the email. The app can create a separate task for each email it needs to send.
You can use push queues only within the App Engine environment; if you need to access App Engine tasks from outside of App Engine, use pull queues .
- Using push queues
- Push task execution
- Deferred tasks
- URL endpoints
- Push queues and the development server
- Push queues and backends
- Quotas and limits for push queues
Using push queues
A Java app sets up queues using a configuration file named
queue.xml
, in the
WEB-INF/
directory inside the WAR. See
Java Task Queue Configuration
. Every app has a push queue named
default
with some default settings.
To enqueue a task, you get a
Queue
using the
QueueFactory
, then call its
add()
method. You can get a named queue specified in the
queue.xml
file using the
getQueue()
method of the factory, or you can get the default queue using
getDefaultQueue()
. You can call the
Queue
's
add()
method with a
TaskOptions
instance (produced by
TaskOptions.Builder
), or you can call it with no arguments to create a task with the default options for the queue.
The following code adds a task to a queue with options.
In
index.html
:
<!-- A basic index.html file served from the "/" URL. -->
<html>
<body>
<p>Enqueue a value, to be processed by a worker.</p>
<form action="/enqueue" method="post">
<input type="text" name="key">
<input type="submit">
</form>
</body>
</html>
In
Enqueue.java
:
// The Enqueue servlet should be mapped to the "/enqueue" URL.
import com.google.appengine.api.taskqueue.Queue;
import com.google.appengine.api.taskqueue.QueueFactory;
import static com.google.appengine.api.taskqueue.TaskOptions.Builder.*;
public class Enqueue extends HttpServlet {
protected void doPost(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {
String key = request.getParameter("key");
// Add the task to the default queue.
Queue queue = QueueFactory.getDefaultQueue();
queue.add(withUrl("/worker").param("key", key));
response.sendRedirect("/");
}
}
In
Worker.java
:
// The Worker servlet should be mapped to the "/worker" URL.
public class Worker extends HttpServlet {
protected void doPost(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {
String key = request.getParameter("key");
// Do something with key.
}
}
Tasks added to this queue will execute by calling the request handler at the URL
/worker
with the parameter
key
. They will execute at the rate set in the
queue.xml
file, or the default rate of 5 tasks per second.
Push task execution
App Engine executes push tasks by sending HTTP requests to your app. Specifying a programmatic asynchronous callback as an HTTP request is sometimes called a web hook . The web hook model enables efficient parallel processing.
The task's URL determines the handler for the task and the module that runs the handler.
The handler is determined by the path part of the URL (the forward-slash separated string following the hostname), which is specified by the
url
parameter in the
TaskOptions
that you include in your call to the
Queue.add()
method.
The url must be relative and local to your application's root directory.
The module (or frontend or backend) and version in which the handler runs is determined by: