com.azure.core.annotation.PathParam 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 to annotate replacement for a named path segment in REST endpoint URL.
 *
 * A parameter that is annotated with PathParam will be ignored if the "uri template" does not contain a path
 * segment variable with name {@link PathParam#value()}.
 *
 * Example 1:
 *
 * 
 *  * @Get("subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/"
 *     + "virtualMachines/")
 * VirtualMachine getByResourceGroup(@PathParam("subscriptionId") String subscriptionId,
 *     @PathParam("resourceGroupName") String rgName,
 *     @PathParam("foo") String bar);
 *
 * // The value of parameters subscriptionId, resourceGroupName will be encoded and used to replace the
 * // corresponding path segments {subscriptionId}, {resourceGroupName} respectively.
 * 
 * 
 *
 * Example 2: (A use case where PathParam.encoded=true will be used)
 *
 * 
 *  * // It is possible that a path segment variable can be used to represent sub path:
 *
 * @Get("http://wq.com/foo/{subpath}/value")
 * String getValue(@PathParam("subpath") String param1);
 *
 * // In this case, if consumer pass "a/b" as the value for param1 then the resolved url looks like:
 * // "http://wq.com/foo/a%2Fb/value".
 * 
 * 
 *
 * 
 *  * // For such cases the encoded attribute can be used:
 *
 * @Get("http://wq.com/foo/{subpath}/values")
 * List<String> getValues(@PathParam(value = "subpath", encoded = true) String param1);
 *
 * // In this case, if consumer pass "a/b" as the value for param1 then the resolved url looks as expected:
 * // "http://wq.com/foo/a/b/values".
 * 
 * 
 */
@Retention(RUNTIME)
@Target(PARAMETER)
public @interface PathParam {
    /**
     * 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 PathParam#value()} is already encoded
     * hence engine should not encode it, by default value will be encoded.
     * @return Whether or not this path parameter is already encoded.
     */
    boolean encoded() default false;
}