001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.http;
018
019import static java.lang.annotation.ElementType.*;
020import static java.lang.annotation.RetentionPolicy.*;
021
022import java.lang.annotation.*;
023
024/**
025 * REST request dynamic-URL annotation.
026 *
027 * <p>
028 * Identifies a method parameter on a REST proxy interface whose value supplies the entire request URL (or a
029 * root-relative URL) for that single call &mdash; the Retrofit <c>@Url</c> pattern.
030 *
031 * <h5 class='topic'>Arguments of client-side @Remote-annotated interfaces</h5>
032 * <p>
033 * When the bound argument is non-<jk>null</jk> and non-blank, its string value becomes the effective URL for that
034 * invocation, overriding the interface/method-declared path resolution:
035 * <ul class='spaced-list'>
036 *    <li>
037 *       If the value contains a scheme (e.g. <js>"http://other-host/path"</js>) it is treated as an <b>absolute</b> URL
038 *       that replaces the whole computed endpoint and bypasses the client root URL.
039 *    <li>
040 *       If the value has no scheme (e.g. <js>"/other/path"</js>) it is treated as a <b>relative</b> URL resolved against
041 *       the client root URL only &mdash; <i>not</i> against the interface {@link org.apache.juneau.http.remote.Remote#path()}
042 *       (matching Retrofit "endpoint replacement").
043 * </ul>
044 *
045 * <p>
046 * Any <c>{var}</c> tokens in the supplied value are still filled by the call's {@link Path @Path} parameters, so a
047 * caller-supplied URL may contain path templates.  An <ja>@Url</ja> argument takes precedence over
048 * {@link org.apache.juneau.http.remote.Remote#path()} + {@code @RemoteOp(path=...)} and over any declarative
049 * {@code baseUrl} override.
050 *
051 * <h5 class='figure'>Example:</h5>
052 * <p class='bjava'>
053 *    <ja>@Remote</ja>(path=<js>"/api"</js>)
054 *    <jk>public interface</jk> MyProxy {
055 *       <jc>// Caller chooses the endpoint at runtime.</jc>
056 *       <ja>@RemoteGet</ja>
057 *       String fetch(<ja>@Url</ja> String <jv>url</jv>);
058 *    }
059 * </p>
060 *
061 * <h5 class='section'>Notes:</h5><ul>
062 *    <li class='note'>
063 *       At most one <ja>@Url</ja> parameter is allowed per method (validated at proxy-build time).
064 *    <li class='note'>
065 *       A <jk>null</jk> or blank <ja>@Url</ja> argument is rejected with an {@link IllegalArgumentException}.
066 *    <li class='note'>
067 *       Only <c>http</c>/<c>https</c> schemes are permitted; other schemes (e.g. <c>file:</c>, <c>gopher:</c>) are
068 *       rejected (SSRF guardrail).
069 *    <li class='note'>
070 *       Honored by both the next-generation engine (<c>RestClient.remote(...)</c>) and the classic engine
071 *       (<c>RestClient.getRemote(...)</c>), with the same http/https-only scheme guard on both.
072 * </ul>
073 *
074 * <h5 class='section'>See Also:</h5><ul>
075 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestProxies">REST Proxies</a>
076 * </ul>
077 *
078 * @since 9.2.1
079 */
080@Documented
081@Target({ PARAMETER })
082@Retention(RUNTIME)
083@Inherited
084public @interface Url {
085}