blob: 7386d8bee5fd7c74cb4096fcbee1f8d303a63fbc [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!-- NewPage -->
<html lang="en">
<head>
<title>ClientHeaderParam</title>
<link rel="stylesheet" type="text/css" href="../../../../../../stylesheet.css" title="Style">
<script type="text/javascript" src="../../../../../../script.js"></script>
<link rel="shortcut icon" href="/img/microprofile-favicon.png">
</head>
<body>
<script type="text/javascript"><!--
try {
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="ClientHeaderParam";
}
}
catch(err) {
}
//-->
</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
<!-- ========= START OF TOP NAVBAR ======= -->
<div class="topNav"><a name="navbar.top">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.top.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../../../index-all.html">Index</a></li>
<li><a href="../../../../../../help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList">
<li>Prev&nbsp;Class</li>
<li><a href="../../../../../../org/eclipse/microprofile/rest/client/annotation/ClientHeaderParams.html" title="annotation in org.eclipse.microprofile.rest.client.annotation"><span class="typeNameLink">Next&nbsp;Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../../../../../index.html?org/eclipse/microprofile/rest/client/annotation/ClientHeaderParam.html" target="_top">Frames</a></li>
<li><a href="ClientHeaderParam.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_top">
<li><a href="../../../../../../allclasses-noframe.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_top");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li><a href="#annotation.type.required.element.summary">Required</a>&nbsp;|&nbsp;</li>
<li><a href="#annotation.type.optional.element.summary">Optional</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li><a href="#annotation.type.element.detail">Element</a></li>
</ul>
</div>
<a name="skip.navbar.top">
<!-- -->
</a></div>
<!-- ========= END OF TOP NAVBAR ========= -->
<!-- ======== START OF CLASS DATA ======== -->
<div class="header">
<div class="subTitle">org.eclipse.microprofile.rest.client.annotation</div>
<h2 title="Annotation Type ClientHeaderParam" class="title">Annotation Type ClientHeaderParam</h2>
</div>
<div class="contentContainer">
<div class="description">
<ul class="blockList">
<li class="blockList">
<hr>
<br>
<pre>@Target(value={TYPE,METHOD})
@Retention(value=RUNTIME)
@Documented
@Repeatable(value=<a href="../../../../../../org/eclipse/microprofile/rest/client/annotation/ClientHeaderParams.html" title="annotation in org.eclipse.microprofile.rest.client.annotation">ClientHeaderParams.class</a>)
public @interface <span class="memberNameLabel">ClientHeaderParam</span></pre>
<div class="block">Used to specify an HTTP parameter that should be sent with the outbound request. When this annotation is placed at
the interface level of a REST client interface, the specified header will be sent on each request for all methods in
the interface. When this annotation is placed on a method, the header will be sent only for that method. If the same
HTTP header is specified in an annotation for both the type and the method, only the header value specified in the
annotation on the method will be sent.
<p>
The value of the header to send can be specified explicitly by using the <code>value</code> attribute. The value can
also be computed via a default method on the client interface or a public static method on a different class. The
compute method must return a String or String[] (indicating a multivalued header) value. This method must be
specified in the <code>value</code> attribute but wrapped in curly-braces. The compute method's signature must either
contain no arguments or a single <code>String</code> argument. The String argument is the name of the header.
<p>
Here is an example that explicitly defines a header value and computes a value:
<pre>
public interface MyClient {
static AtomicInteger counter = new AtomicInteger(1);
default String determineHeaderValue(String headerName) {
if ("SomeHeader".equals(headerName)) {
return "InvokedCount " + counter.getAndIncrement();
}
throw new UnsupportedOperationException("unknown header name");
}
@ClientHeaderParam(name="SomeHeader", value="ExplicitlyDefinedValue")
@GET
Response useExplicitHeaderValue();
@ClientHeaderParam(name="SomeHeader", value="{determineHeaderValue}")
@DELETE
Response useComputedHeaderValue();
}
</pre>
The implementation should fail to deploy a client interface if the annotation contains a
<code>@ClientHeaderParam</code> annotation with a <code>value</code> attribute that references a method that does not
exist, or contains an invalid signature.
<p>
The <code>required</code> attribute will determine what action the implementation should take if the method specified
in the <code>value</code> attribute throws an exception. If the attribute is true (default), then the implementation
will abort the request and will throw the exception back to the caller. If the <code>required</code> attribute is set
to false, then the implementation will not send this header if the method throws an exception.
<p>
Note that if an interface method contains an argument annotated with <code>@HeaderParam</code>, that argument will
take priority over anything specified in a ClientHeaderParam annotation.</div>
<dl>
<dt><span class="simpleTagLabel">Since:</span></dt>
<dd>1.2</dd>
</dl>
</li>
</ul>
</div>
<div class="summary">
<ul class="blockList">
<li class="blockList">
<!-- =========== ANNOTATION TYPE REQUIRED MEMBER SUMMARY =========== -->
<ul class="blockList">
<li class="blockList"><a name="annotation.type.required.element.summary">
<!-- -->
</a>
<h3>Required Element Summary</h3>
<table class="memberSummary" border="0" cellpadding="3" cellspacing="0" summary="Required Element Summary table, listing required elements, and an explanation">
<caption><span>Required Elements</span><span class="tabEnd">&nbsp;</span></caption>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colLast" scope="col">Required Element and Description</th>
</tr>
<tr class="altColor">
<td class="colFirst"><code>java.lang.String</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../../../org/eclipse/microprofile/rest/client/annotation/ClientHeaderParam.html#name--">name</a></span></code>&nbsp;</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code>java.lang.String[]</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../../../org/eclipse/microprofile/rest/client/annotation/ClientHeaderParam.html#value--">value</a></span></code>&nbsp;</td>
</tr>
</table>
</li>
</ul>
<!-- =========== ANNOTATION TYPE OPTIONAL MEMBER SUMMARY =========== -->
<ul class="blockList">
<li class="blockList"><a name="annotation.type.optional.element.summary">
<!-- -->
</a>
<h3>Optional Element Summary</h3>
<table class="memberSummary" border="0" cellpadding="3" cellspacing="0" summary="Optional Element Summary table, listing optional elements, and an explanation">
<caption><span>Optional Elements</span><span class="tabEnd">&nbsp;</span></caption>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colLast" scope="col">Optional Element and Description</th>
</tr>
<tr class="altColor">
<td class="colFirst"><code>boolean</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../../../org/eclipse/microprofile/rest/client/annotation/ClientHeaderParam.html#required--">required</a></span></code>&nbsp;</td>
</tr>
</table>
</li>
</ul>
</li>
</ul>
</div>
<div class="details">
<ul class="blockList">
<li class="blockList">
<!-- ============ ANNOTATION TYPE MEMBER DETAIL =========== -->
<ul class="blockList">
<li class="blockList"><a name="annotation.type.element.detail">
<!-- -->
</a>
<h3>Element Detail</h3>
<a name="name--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>name</h4>
<pre>public abstract&nbsp;java.lang.String&nbsp;name</pre>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the name of the HTTP header.</dd>
</dl>
</li>
</ul>
</li>
</ul>
<ul class="blockList">
<li class="blockList"><a name="value--">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>value</h4>
<pre>public abstract&nbsp;java.lang.String[]&nbsp;value</pre>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the value(s) of the HTTP header - or the method to invoke to get the value (surrounded by curly braces).</dd>
</dl>
</li>
</ul>
</li>
</ul>
<!-- ============ ANNOTATION TYPE MEMBER DETAIL =========== -->
<ul class="blockList">
<li class="blockList"><a name="required--">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>required</h4>
<pre>public abstract&nbsp;boolean&nbsp;required</pre>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>whether to abort the request if the method to compute the header value throws an exception (true;
default) or just skip this header (false)</dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>true</dd>
</dl>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
<!-- ========= END OF CLASS DATA ========= -->
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<div class="bottomNav"><a name="navbar.bottom">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.bottom.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../../../index-all.html">Index</a></li>
<li><a href="../../../../../../help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList">
<li>Prev&nbsp;Class</li>
<li><a href="../../../../../../org/eclipse/microprofile/rest/client/annotation/ClientHeaderParams.html" title="annotation in org.eclipse.microprofile.rest.client.annotation"><span class="typeNameLink">Next&nbsp;Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../../../../../index.html?org/eclipse/microprofile/rest/client/annotation/ClientHeaderParam.html" target="_top">Frames</a></li>
<li><a href="ClientHeaderParam.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_bottom">
<li><a href="../../../../../../allclasses-noframe.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_bottom");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li><a href="#annotation.type.required.element.summary">Required</a>&nbsp;|&nbsp;</li>
<li><a href="#annotation.type.optional.element.summary">Optional</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li><a href="#annotation.type.element.detail">Element</a></li>
</ul>
</div>
<a name="skip.navbar.bottom">
<!-- -->
</a></div>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
</body>
</html>