com.azure.core.annotation.QueryParam Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of azure-core Show documentation
This package contains core types for Azure Java clients.
There is a newer version: 1.54.1
// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.

package com.azure.core.annotation;

import java.lang.annotation.Retention;
import java.lang.annotation.Target;

import static java.lang.annotation.ElementType.PARAMETER;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

/**
 * Annotation for query parameters to be appended to a REST API Request URI.
 *
 * Example 1:
 *
 * 
 *  * @Get("subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/resources")
 * Mono<ResponseBase<ResponseHeaders, ResponseBody>> listByResourceGroup(
 *     @PathParam("resourceGroupName") String resourceGroupName,
 *     @PathParam("subscriptionId") String subscriptionId,
 *     @QueryParam("$filter") String filter,
 *     @QueryParam("$expand") String expand,
 *     @QueryParam("$top") Integer top,
 *     @QueryParam("api-version") String apiVersion);
 *
 * // The value of parameters filter, expand, top, apiVersion will be encoded and will be used to set the query
 * // parameters {$filter}, {$expand}, {$top}, {api-version} on the HTTP URL.
 * 
 * 
 *
 * Example 2: (A use case where PathParam.encoded=true will be used)
 *
 * 
 *  * // It is possible that a query parameter will need to be encoded:
 * @Get("http://wq.com/foo/{subpath}/value")
 * String getValue(@PathParam("subpath") String param,
 *     @QueryParam("query") String query);
 *
 * // In this case, if consumer pass "a=b" as the value for 'query' then the resolved url looks like:
 * // "http://wq.com/foo/subpath/value?query=a%3Db"
 * 
 * 
 *
 * For such cases the encoded attribute can be used:
 *
 * 
 *  * @Get("http://wq.com/foo/{subpath}/values")
 * List<String> getValues(@PathParam("subpath") String param,
 *     @QueryParam(value = "query", encoded = true) String query);
 *
 * // In this case, if consumer pass "a=b" as the value for 'query' then the resolved url looks like:
 * // "http://wq.com/foo/paramblah/values?connectionString=a=b"
 * 
 * 
 *
 * Example 3:
 *
 * 
 *  * @Get("http://wq.com/foo/multiple/params")
 * String multipleParams(@QueryParam(value = "query", multipleQueryParams = true) List<String> query);
 *
 * // The value of parameter avoid would look like this:
 * // "http://wq.com/foo/multiple/params?avoid%3Dtest1&avoid%3Dtest2&avoid%3Dtest3"
 * 
 * 
 */
@Retention(RUNTIME)
@Target(PARAMETER)
public @interface QueryParam {
    /**
     * The name of the variable in the endpoint uri template which will be replaced with the value
     * of the parameter annotated with this annotation.
     * @return The name of the variable in the endpoint uri template which will be replaced with the
     *     value of the parameter annotated with this annotation.
     */
    String value();
    /**
     * A value true for this argument indicates that value of {@link QueryParam#value()} is already encoded
     * hence engine should not encode it, by default value will be encoded.
     * @return Whether this query parameter is already encoded.
     */
    boolean encoded() default false;
    /**
     * A value true for this argument indicates that value of {@link QueryParam#value()} should not be
     * converted to Json in case it is an array but instead sent as multiple values with same parameter
     * name.
     * @return Whether this query parameter list values should be sent as individual query
     * params or as a single Json.
     */
    boolean multipleQueryParams() default false;
}