Package org.apache.juneau.http

Annotation Interface Query

@Documented @Target({PARAMETER,METHOD,TYPE,FIELD}) @Retention(RUNTIME) @Inherited public @interface Query
REST request form-data annotation.

Identifies a POJO to be used as a form-data entry on an HTTP request.

Can be used in the following locations:

  • Arguments and argument-types of server-side @RestOp-annotated methods.
  • Arguments and argument-types of client-side @RemoteResource-annotated interfaces.
  • Methods and return types of server-side and client-side @Request-annotated interfaces.
Arguments and argument-types of server-side @RestOp-annotated methods

Annotation that can be applied to a parameter of a @RestOp-annotated method to identify it as a URL query parameter.

Unlike @FormData, using this annotation does not result in the servlet reading the contents of URL-encoded form posts. Therefore, this annotation can be used in conjunction with the @Content annotation or RestRequest.getContent() method for application/x-www-form-urlencoded POST calls.

Example:

@RestGet public void doGet( @Query("p1") int p1, @Query("p2") String p2, @Query("p3") UUID p3 ) {...}

This is functionally equivalent to the following code...

@RestGet public void doGet(RestRequest req, RestResponse res) { int p1 = req.getQueryParam("p1").asInteger().orElse(0); String p2 = req.getQueryParam("p2").asString().orElse(null); UUID p3 = req.getQueryParam("p3").as(UUID.class).orElse(null); ... }

See Also:
Arguments and argument-types of client-side @RemoteResource-annotated interfaces

See Also:
Methods and return types of server-side and client-side @Request-annotated interfaces

See Also:

  • Element Details

    • def

      String def
      Default value for this parameter.
      Returns:
      The annotation value.
      Default:
      ""

    • description

      String[] description
      Optional description for the exposed API.
      Returns:
      The annotation value.
      Since:
      9.2.0
      Default:
      {}

    • summary

      String summary
      Short, concise summary of the exposed API.

      Intended as a brief, single-line description suitable for AI/LLM consumption, compact documentation, or any context where brevity matters. See Schema.summary() for the canonical definition.

      Returns:
      The annotation value.
      Since:
      10.0.0
      Default:
      ""

    • name

      String name
      URL query parameter name. Required. The name of the parameter. Parameter names are case sensitive.

      The value should be either a valid query parameter name, or "*" to represent multiple name/value pairs

      A blank value (the default) has the following behavior:

      • If the data type is NameValuePairs, Map, or a bean, then it's the equivalent to "*" which will cause the value to be serialized as name/value pairs.
        Examples:

        // When used on a REST method @RestPost public void addPet(@Query JsonMap allQueryParameters) {...}

        // When used on a remote method parameter @RemoteResource(path="/myproxy") public interface MyProxy { // Equivalent to @Query("*") @RemoteGet("/mymethod") String myProxyMethod1(@Query Map<String,Object> allQueryParameters); }

        // When used on a request bean method public interface MyRequest { // Equivalent to @Query("*") @Query Map<String,Object> getFoo(); }

      • If used on a request bean method, uses the bean property name.
        Example:

        public interface MyRequest { // Equivalent to @Query("foo") @Query String getFoo(); }

      Notes:
      • The format is plain-text.
      Returns:
      The annotation value.
      Default:
      ""

    • schema

      Schema schema
      schema field of the Swagger Parameter Object.

      The @Schema annotation can also be used standalone on the parameter or type. Values specified on this field override values specified on the type, and values specified on child types override values specified on parent types.

      The schema defining the type used for parameter.

      Used for:
      • Server-side schema-based parsing and parsing validation.
      • Server-side generated Swagger documentation.
      • Client-side schema-based serializing and serializing validation.
      Returns:
      The annotation value.
      Default:
      @org.apache.juneau.commons.Schema

    • value

      String value
      A synonym for name().

      Allows you to use shortened notation if you're only specifying the name.

      The following are completely equivalent ways of defining the existence of a query entry:

      public Order placeOrder(@Query(name="petId") long petId) {...}

      public Order placeOrder(@Query("petId") long petId) {...}

      Returns:
      The annotation value.
      Default:
      ""