Jersey Configuration documentation (#4371)
Signed-off-by: Maxim Nesen <maxim.nesen@oracle.com>
diff --git a/docs/src/main/docbook/jersey.ent b/docs/src/main/docbook/jersey.ent
index 956443c..520c599 100644
--- a/docs/src/main/docbook/jersey.ent
+++ b/docs/src/main/docbook/jersey.ent
@@ -1,7 +1,7 @@
<?xml version="1.0" encoding="iso-8859-1" ?>
<!--
- Copyright (c) 2010, 2019 Oracle and/or its affiliates. All rights reserved.
+ Copyright (c) 2010, 2020 Oracle and/or its affiliates. All rights reserved.
This program and the accompanying materials are made available under the
terms of the Eclipse Public License v. 2.0, which is available at
@@ -100,6 +100,9 @@
<!ENTITY rxjava.uri "https://github.com/ReactiveX/RxJava">
<!ENTITY wikipedia.uri "http://en.wikipedia.org/wiki/">
<!ENTITY jira.uri.prefix "https://github.com/eclipse-ee4j/jersey/issues">
+<!ENTITY microprofile.spec.link "<link xlink:href='https://microprofile.io/project/eclipse/microprofile-config'>Microprofile Config Specification</link>">
+<!ENTITY helidon.link "<link xlink:href='https://helidon.io/'>Helidon</link>">
+<!ENTITY smallrye.link "<link xlink:href='https://smallrye.io/'>SmallRye</link>">
<!-- API Docs links -->
<!ENTITY bv.Configuration "<link xlink:href='&bv11.javadoc.uri;/javax/validation/Configuration.html'>Configuration</link>">
diff --git a/docs/src/main/docbook/mp-config.xml b/docs/src/main/docbook/mp-config.xml
new file mode 100644
index 0000000..36c1e45
--- /dev/null
+++ b/docs/src/main/docbook/mp-config.xml
@@ -0,0 +1,93 @@
+<?xml version="1.0"?>
+<!--
+
+ Copyright (c) 2020 Oracle and/or its affiliates. All rights reserved.
+
+ This program and the accompanying materials are made available under the
+ terms of the Eclipse Public License v. 2.0, which is available at
+ http://www.eclipse.org/legal/epl-2.0.
+
+ This Source Code may also be made available under the following Secondary
+ Licenses when the conditions for such availability set forth in the
+ Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
+ version 2 with the GNU Classpath Exception, which is available at
+ https://www.gnu.org/software/classpath/license.html.
+
+ SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+
+-->
+
+<!DOCTYPE chapter [<!ENTITY % ents SYSTEM "jersey.ent" > %ents; ]>
+<chapter xmlns="http://docbook.org/ns/docbook"
+ version="5.0"
+ xml:lang="en"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xsi:schemaLocation="http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd
+ http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd"
+ xml:id="jersey-configuration">
+ <title>Jersey configuration</title>
+ <para>
+ This chapter provides Jersey configuration basics which includes configuration using default configuration
+ provider (included in Jersey by default) using system properties. And micro-profile configuration extension
+ which allows plugging-in of configuration modules based on micro profile configuration specification
+ </para>
+ <section xml:id="default-config">
+ <title>Jersey default configuration provider</title>
+ <para>
+ Since Jersey 2.29 it is possible to turn on the ability to convert the System properties into
+ Configuration properties. That can be done by using the System property, too:
+ <programlisting language="bash" linenumbering="unnumbered">java -Djersey.config.allowSystemPropertiesProvider=true -DNAME=VALUE
+ </programlisting>
+ Note that with the security manager turned on, write access permission is required to execute
+ System.getProperties(). With insufficient permissions, the warning message is logged (with Level.FINER) and
+ only &jersey.common.CommonProperties;, &jersey.client.ClientProperties;,
+ and &jersey.server.ServerProperties;
+ properties are used, as the property names are known and System.getProperty(name) method can be used,
+ which does not require the write access permission.
+ </para>
+ </section>
+ <section xml:id="mp-config">
+ <title>Micro profile configuration provider</title>
+ <para>
+ Microprofile platform became very popular lately and µprofile.spec.link;
+ is a recommended way in the Jakarta EE world to configure the specifications under the Jakarta EE umbrella.
+ </para>
+ <para>
+ Jersey 2.29 comes with support for Microprofile Config implementation such as &helidon.link; or &smallrye.link;.
+ To configure the Jersey application, the microprofile-config.properties file needs to be created in the
+ META-INF folder. The required properties are then simply set in the microprofile-config.properties:
+ <programlisting language="java" linenumbering="unnumbered">
+ NAME=VALUE
+ </programlisting>
+ </para>
+ <para>
+ Then Jersey Microprofile Config extension is needed to be added:
+ <programlisting language="xml" linenumbering="unnumbered">
+ <dependency>
+ <groupId>org.glassfish.jersey.ext.microprofile</groupId>
+ <artifactId>jersey-mp-config</artifactId>
+ <version>2.30</scope>
+ </dependency>
+ </programlisting>
+ And the Microprofile Config implementation, such as Helidon:
+ <programlisting language="xml" linenumbering="unnumbered">
+ <dependency>
+ <groupId>io.helidon.microprofile.config</groupId>
+ <artifactId>helidon-microprofile-config</artifactId>
+ <version>1.3.1</version>
+ </dependency>
+ </programlisting>
+ Or SmallRye:
+ <programlisting language="xml" linenumbering="unnumbered">
+ <dependency>
+ <groupId>io.smallrye</groupId>
+ <artifactId>smallrye-config</artifactId>
+ <version>1.3.6</version>
+ </dependency>
+ </programlisting>
+ or any other suitable Microprofile Config implementation.
+ </para>
+ </section>
+</chapter>
\ No newline at end of file
diff --git a/docs/src/main/docbook/user-guide.xml b/docs/src/main/docbook/user-guide.xml
index fc1dbf2..0247500 100644
--- a/docs/src/main/docbook/user-guide.xml
+++ b/docs/src/main/docbook/user-guide.xml
@@ -1,7 +1,7 @@
<?xml version="1.0"?>
<!--
- Copyright (c) 2010, 2019 Oracle and/or its affiliates. All rights reserved.
+ Copyright (c) 2010, 2020 Oracle and/or its affiliates. All rights reserved.
This program and the accompanying materials are made available under the
terms of the Eclipse Public License v. 2.0, which is available at
@@ -104,6 +104,7 @@
<xi:include href="uris-and-links.xml" />
<xi:include href="declarative-linking.xml" />
<xi:include href="resource-builder.xml" />
+ <xi:include href="mp-config.xml" />
<xi:include href="sse.xml" />
<xi:include href="security.xml" />
<xi:include href="wadl.xml" />
