How to use Queries in Java

To use Queries to query the state of a Workflow at any stage of the Workflow Execution, create a Query handler using the @QueryMethod annotation in the Workflow interface and call the method in your external process.

You can send a Query to an open or closed Workflow Execution.

When using Queries, the following restrictions apply:

• It cannot modify Workflow state in any way.
• It is not allowed to block its thread in any way.

Define Query Method

To define a Query, define the method name and the result type of the Query.

query(String queryType, Class<R> resultClass, Type resultType, Object... args);

  /* @param queryType name of the Query handler. Usually it is a method name.
   * @param resultClass class of the Query result type
   * @param args optional Query arguments
   * @param <R> type of the Query result
  */

Query methods can take in any number of input parameters which can be used to limit the data that is returned.

Use the Query method names to send and receive Queries.

Query methods must never change any Workflow state including starting Activities or blocking threads in any way.

Handle Query

To handle a Query in the Workflow, create a Query handler using the @QueryMethod annotation in the Workflow interface and define it in the Workflow implementation.

The @QueryMethod annotation indicates that the method is used to handle a Query that is sent to the Workflow Execution. The method can have parameters that can be used to filter data that the Query returns. Because the method returns a value, it must have a return type that is not void.

The Query name defaults to the name of the method. In the following example, the Query name defaults to getStatus.

@WorkflowInterface
public interface FileProcessingWorkflow {
   @QueryMethod
   String getStatus();
}

To overwrite this default naming and assign a custom Query name, use the @QueryMethod annotation with the name parameter. In the following example, the Query name is set to "history".

@WorkflowInterface
public interface FileProcessingWorkflow {
   @QueryMethod(name = "history")
   String getStatus();
}

A Workflow Definition interface can define multiple methods annotated with @QueryMethod, but the method names or the name parameters for each must be unique.

The following Workflow interface has a Query method getCount() to handle Queries to this Workflow.

  @WorkflowInterface
  public interface HelloWorld {
    @WorkflowMethod
    void sayHello(String name);

    @QueryMethod
    int getCount();
  }

The following example is the Workflow implementation with the Query method defined in the HelloWorld Workflow interface from the previous example.

  public static class HelloWorldImpl implements HelloWorld {

    private String greeting = "Hello";
    private int count = 0;

    @Override
    public void sayHello(String name) {
      while (!"Bye".equals(greeting)) {
        logger.info(++count + ": " + greeting + " " + name + "!");
        String oldGreeting = greeting;
        Workflow.await(() -> !Objects.equals(greeting, oldGreeting));
      }
      logger.info(++count + ": " + greeting + " " + name + "!");
    }

    @Override
    public int getCount() {
      return count;
    }
  }

Dynamic Query Handler You can also implement Query handlers dynamically. This is useful for library-level code and implementation of DSLs.

Use Workflow.registerListener(Object) to register an implementation of the DynamicQueryListener in the Workflow implementation code.

      Workflow.registerListener(
        (DynamicQueryHandler)
            (queryName, encodedArgs) -> name = encodedArgs.get(0, String.class));

When registered, any Queries sent to the Workflow without a defined handler will be delivered to the DynamicQueryHandler. Note that you can only register one Workflow.registerListener(Object) per Workflow Execution. DynamicQueryHandler can be implemented in both regular and dynamic Workflow implementations.

Send Query from Temporal Client

To send a Query to a Workflow Execution from an external process, call the Query method (defined in the Workflow) from a WorkflowStub within the Client code.

For example, the following Client code calls a Query method queryGreeting() defined in the GreetingWorkflow Workflow interface.

 // Create our workflow options
    WorkflowOptions workflowOptions =
        WorkflowOptions.newBuilder()
        .setWorkflowId(WORKFLOW_ID)
        .setTaskQueue(TASK_QUEUE).build();

    // Create the Temporal client stub. It is used to start our workflow execution.
    GreetingWorkflow workflow = client.newWorkflowStub(GreetingWorkflow.class, workflowOptions);

    // Start our workflow asynchronously to not use another thread to query.
    WorkflowClient.start(workflow::createGreeting, "World");

    // Query the Workflow to get the current value of greeting and print it.
    System.out.println(workflow.queryGreeting());