Como criar tarefas push | Ambiente padrão do App Engine para Java 8
Esta solução não é mais recomendada: nesta página, descrevemos o uso de um serviço legado do App Engine. Os aplicativos que usam esse serviço só podem ser executados no ambiente de execução do Java 8 e precisarão fazer upgrade para uma solução recomendada antes de migrar para o ambiente de execução do Java 11.
Para criar uma tarefa e colocá-la em fila, receba um Queue usando QueueFactory e chame o respectivo método add(). É possível receber uma fila nomeada especificada no arquivo queue.xml usando o método getQueue() da fábrica ou receber a fila padrão usando getDefaultQueue(). É possível chamar o método add() de Queue com uma instância TaskOptions (produzida por TaskOptions.Builder) ou chamá-lo sem argumentos para criar uma tarefa com as opções padrão da fila.
Como especificar o serviço de trabalhador
Quando uma tarefa é retirada da fila, o serviço de fila de tarefas a envia para um serviço de worker. Cada tarefa tem um destino e um url, que determinam o serviço e o gerenciador que vão realizar a tarefa.
O destino especifica o serviço que receberá a solicitação HTTP para executar a tarefa. É uma string que especifica um serviço/versão/instância em qualquer uma das formas canônicas. As formas mais usadas são estas:
Declarar o destino ao construir a tarefa. Para definir explicitamente o destino ao criar a tarefa, defina o cabeçalho Host usando TaskOptions:
Incluir uma diretiva target ao definir uma fila em queue.xml, como na definição de queue-blue. Todas as tarefas incluídas em uma fila com um target terão esse destino, mesmo que outro destino seja atribuído à tarefa no momento da criação.
O construtor TaskOptions.Builder tem métodos para adicionar dados como payload da solicitação HTTP e como parâmetros, que são adicionados ao URL como parâmetros de consulta.
Não especifique parâmetros ao usar o método POST junto a um payload ou se usar o método GET e tiver incluído um URL com parâmetros de consulta.
Se você mesmo atribuir nomes às tarefas, observe que o comprimento máximo do nome é 500 caracteres. O nome pode conter letras maiúsculas e minúsculas, sublinhados de números e hifens.
Como adicionar tarefas de maneira assíncrona
Por padrão, as chamadas que adicionam tarefas a filas são síncronas. As chamadas síncronas funcionam bem na maioria dos cenários. Adicionar uma tarefa a uma fila costuma ser uma operação rápida. O tempo médio para adicionar uma tarefa é de menos de 5 minutos. Porém, uma pequena porcentagem dessas operações pode demorar muito mais tempo.
Não é possível colocar em lote as operações de adição de tarefas a filas diferentes. Por isso, a API Task Queue também fornece chamadas assíncronas que permitem adicionar essas tarefas em paralelo, minimizando ainda mais essa latência. Isso é útil para a criação de um aplicativo muito sensível à latência que precisa executar diversas operações de adição de tarefas a diferentes filas ao mesmo tempo.
Se você quiser fazer chamadas assíncronas a uma fila de tarefas, use os métodos assíncronos fornecidos pelaclasse Queue. Chame get no Future retornado para forçar a conclusão da solicitação. Ao adicionar tarefas a uma transação de maneira assíncrona, chame get() na classe Future antes de confirmar a transação para garantir que a solicitação foi concluída.
Você pode enfileirar uma tarefa como parte de uma transação do Datastore, de modo que ela seja enfileirada e garantida para ser enfileirada se a transação for confirmada. As tarefas adicionadas a uma transação são consideradas parte dela e têm o mesmo nível de isolamento e consistência.
O exemplo de código a seguir demonstra como inserir tarefas transacionais em uma fila push como parte de uma transação do Datastore:
Como usar DeferredTasks em vez de um serviço de worker
A configuração de um gerenciador para cada tarefa distinta, conforme descrito nas seções anteriores, pode ser complicada. A serialização e desserialização de argumentos complexos para a tarefa também podem ter complicações, especialmente se você quiser executar na fila muitas tarefas distintas, porém, pequenas. O Java SDK inclui uma interface denominada DeferredTask, que permite definir uma tarefa como um método único. A interface usa a serialização do Java para empacotar uma unidade de trabalho em uma fila de tarefas. Um retorno simples desse método é considerado sucesso. A geração de qualquer exceção desse método é considerada uma falha.
Aviso: a API DeferredTask oferece uma maneira conveniente de processar a serialização. Entretanto, é necessário controlar com cuidado a compatibilidade da serialização dos objetos transferidos nos métodos de payload. O controle cuidadoso é necessário porque os objetos não processados permanecem na fila de tarefas, mesmo após a atualização do código do aplicativo. As tarefas baseadas em código de aplicativo desatualizado não são desserializadas adequadamente quando a tarefa é decodificada com novas revisões do aplicativo.
Como trabalhar com tarefas em um aplicativo multilocatário
Por padrão, as filas push usam o namespace atual configurado no gerenciador de namespace no momento da criação da tarefa. Se o aplicativo usa multilocação, consulte a API Namespaces Java 8.