Skip to content

Commit

Permalink
DOC: User guide, CDI 2.0 (JSR 365) section: fix example and add warni…
Browse files Browse the repository at this point in the history 
…ng about dynamic proxies
  • Loading branch information
@remkop
Mert Zeybekler authored and remkop committed May 24, 2024
1 parent da98db6 commit b03121b
Show file tree
Hide file tree
Showing 2 changed files with 114 additions and 80 deletions.
16 changes: 14 additions & 2 deletions docs/index.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12409,7 +12409,7 @@ public class CDIFactory implements IFactory {
if (instance.isResolvable()) {
return instance.get();
}
return defaultFactory.create(cls);
return fallbackFactory.create(cls);
}
}
----
Expand All @@ -12421,9 +12421,13 @@ How to use the above factory depends on the specific container, but in general i
@Command(name = "cdi-app", mixinStandardHelpOptions = true)
class MyCDIApp implements Runnable {

@Option(names = {"-x", "--option"}, description = "example option")
boolean flag;

@Option(names = {"-x", "--option"}, description = "example option")
public void setFlag(boolean flag) {
this.flag = flag;
}

@Override
public void run() {
// business logic
Expand All @@ -12436,6 +12440,14 @@ class MyCDIApp implements Runnable {
}
----

[IMPORTANT]
====
Depending on your configuration, CDI may use dynamic proxies for managed instances.

The safest thing to do in CDI applications is to use public <<option-parameters-methods,annotated **setter methods**>> for picocli's `@Option` and `@Parameters`, `@Spec`, and other annotations.
Using picocli annotations on fields or on non-public methods may result in picocli-injected values not being available in the proxied instance.
====

== Java 9 JPMS Modules

The main `picocli-${version}.jar` is a JPMS module named `info.picocli`.
Expand Down
178 changes: 100 additions & 78 deletions docs/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1709,81 +1709,81 @@
});
});
</script>
<style>
.hidden {
display: none;
}
.switch {
border-width: 1px 1px 0 1px;
border-style: solid;
border-color: #7a2518;
display: inline-block;
}
.switch--item {
padding: 10px;
background-color: #ffffff;
color: #7a2518;
display: inline-block;
cursor: pointer;
}
.switch--item.selected {
background-color: #7a2519;
color: #ffffff;
}
</style>
<script src="https://cdnjs.cloudflare.com/ajax/libs/zepto/1.2.0/zepto.min.js"></script>
<script type="text/javascript">
function addBlockSwitches() {
$('.primary').each(function() {
primary = $(this);
createSwitchItem(primary, createBlockSwitch(primary)).item.addClass("selected");
primary.children('.title').remove();
});
$('.secondary').each(function(idx, node) {
secondary = $(node);
primary = findPrimary(secondary);
switchItem = createSwitchItem(secondary, primary.children('.switch'));
switchItem.content.addClass('hidden');
findPrimary(secondary).append(switchItem.content);
secondary.remove();
});
}
function createBlockSwitch(primary) {
blockSwitch = $('<div class="switch"></div>');
primary.prepend(blockSwitch);
return blockSwitch;
}
function findPrimary(secondary) {
candidate = secondary.prev();
while (!candidate.is('.primary')) {
candidate = candidate.prev();
}
return candidate;
}
function createSwitchItem(block, blockSwitch) {
blockName = block.children('.title').text();
content = block.children('.content').first().append(block.next('.colist'));
item = $('<div class="switch--item">' + blockName + '</div>');
item.on('click', '', content, function(e) {
$(this).addClass('selected');
$(this).siblings().removeClass('selected');
e.data.siblings('.content').addClass('hidden');
e.data.removeClass('hidden');
});
blockSwitch.append(item);
return {'item': item, 'content': content};
}
$(addBlockSwitches);
</script>
<style>
.hidden {
display: none;
}

.switch {
border-width: 1px 1px 0 1px;
border-style: solid;
border-color: #7a2518;
display: inline-block;
}

.switch--item {
padding: 10px;
background-color: #ffffff;
color: #7a2518;
display: inline-block;
cursor: pointer;
}

.switch--item.selected {
background-color: #7a2519;
color: #ffffff;
}

</style>
<script src="https://cdnjs.cloudflare.com/ajax/libs/zepto/1.2.0/zepto.min.js"></script>
<script type="text/javascript">
function addBlockSwitches() {
$('.primary').each(function() {
primary = $(this);
createSwitchItem(primary, createBlockSwitch(primary)).item.addClass("selected");
primary.children('.title').remove();
});
$('.secondary').each(function(idx, node) {
secondary = $(node);
primary = findPrimary(secondary);
switchItem = createSwitchItem(secondary, primary.children('.switch'));
switchItem.content.addClass('hidden');
findPrimary(secondary).append(switchItem.content);
secondary.remove();
});
}

function createBlockSwitch(primary) {
blockSwitch = $('<div class="switch"></div>');
primary.prepend(blockSwitch);
return blockSwitch;
}

function findPrimary(secondary) {
candidate = secondary.prev();
while (!candidate.is('.primary')) {
candidate = candidate.prev();
}
return candidate;
}

function createSwitchItem(block, blockSwitch) {
blockName = block.children('.title').text();
content = block.children('.content').first().append(block.next('.colist'));
item = $('<div class="switch--item">' + blockName + '</div>');
item.on('click', '', content, function(e) {
$(this).addClass('selected');
$(this).siblings().removeClass('selected');
e.data.siblings('.content').addClass('hidden');
e.data.removeClass('hidden');
});
blockSwitch.append(item);
return {'item': item, 'content': content};
}

$(addBlockSwitches);

</script>

</head>
<body class="article toc2 toc-left">
Expand Down Expand Up @@ -17486,7 +17486,7 @@ <h3 id="_cdi_2_0_jsr_365"><a class="anchor" href="#_cdi_2_0_jsr_365"></a>22.5. C
<span class="k">if</span> <span class="o">(</span><span class="n">instance</span><span class="o">.</span><span class="na">isResolvable</span><span class="o">())</span> <span class="o">{</span>
<span class="k">return</span> <span class="n">instance</span><span class="o">.</span><span class="na">get</span><span class="o">();</span>
<span class="o">}</span>
<span class="k">return</span> <span class="n">defaultFactory</span><span class="o">.</span><span class="na">create</span><span class="o">(</span><span class="n">cls</span><span class="o">);</span>
<span class="k">return</span> <span class="n">fallbackFactory</span><span class="o">.</span><span class="na">create</span><span class="o">(</span><span class="n">cls</span><span class="o">);</span>
<span class="o">}</span>
<span class="o">}</span></code></pre>
</div>
Expand All @@ -17499,9 +17499,13 @@ <h3 id="_cdi_2_0_jsr_365"><a class="anchor" href="#_cdi_2_0_jsr_365"></a>22.5. C
<pre class="rouge highlight"><code data-lang="java"><span class="nd">@Command</span><span class="o">(</span><span class="n">name</span> <span class="o">=</span> <span class="s">"cdi-app"</span><span class="o">,</span> <span class="n">mixinStandardHelpOptions</span> <span class="o">=</span> <span class="kc">true</span><span class="o">)</span>
<span class="kd">class</span> <span class="nc">MyCDIApp</span> <span class="kd">implements</span> <span class="nc">Runnable</span> <span class="o">{</span>

<span class="nd">@Option</span><span class="o">(</span><span class="n">names</span> <span class="o">=</span> <span class="o">{</span><span class="s">"-x"</span><span class="o">,</span> <span class="s">"--option"</span><span class="o">},</span> <span class="n">description</span> <span class="o">=</span> <span class="s">"example option"</span><span class="o">)</span>
<span class="kt">boolean</span> <span class="n">flag</span><span class="o">;</span>

<span class="nd">@Option</span><span class="o">(</span><span class="n">names</span> <span class="o">=</span> <span class="o">{</span><span class="s">"-x"</span><span class="o">,</span> <span class="s">"--option"</span><span class="o">},</span> <span class="n">description</span> <span class="o">=</span> <span class="s">"example option"</span><span class="o">)</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">setFlag</span><span class="o">(</span><span class="kt">boolean</span> <span class="n">flag</span><span class="o">)</span> <span class="o">{</span>
<span class="k">this</span><span class="o">.</span><span class="na">flag</span> <span class="o">=</span> <span class="n">flag</span><span class="o">;</span>
<span class="o">}</span>

<span class="nd">@Override</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">run</span><span class="o">()</span> <span class="o">{</span>
<span class="c1">// business logic</span>
Expand All @@ -17514,6 +17518,24 @@ <h3 id="_cdi_2_0_jsr_365"><a class="anchor" href="#_cdi_2_0_jsr_365"></a>22.5. C
<span class="o">}</span></code></pre>
</div>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
<div class="paragraph">
<p>Depending on your configuration, CDI may use dynamic proxies for managed instances.</p>
</div>
<div class="paragraph">
<p>The safest thing to do in CDI applications is to use public <a href="#option-parameters-methods">annotated <strong>setter methods</strong></a> for picocli&#8217;s <code>@Option</code> and <code>@Parameters</code>, <code>@Spec</code>, and other annotations.
Using picocli annotations on fields or on non-public methods may result in picocli-injected values not being available in the proxied instance.</p>
</div>
</td>
</tr>
</table>
</div>
</div>
</div>
</div>
Expand Down Expand Up @@ -19140,4 +19162,4 @@ <h3 id="_source"><a class="anchor" href="#_source"></a>37.2. Source</h3>
handleTocOnResize();
</script>
</body>
</html>
</html>

0 comments on commit b03121b

Please sign in to comment.