Skip to content

Commit

Permalink
Added Documentation for JSON-B support
Browse files Browse the repository at this point in the history 
Signed-off-by: Jan Supol <jan.supol@oracle.com>
  • Loading branch information
@jansupol @senivam
jansupol authored and senivam committed Jun 25, 2020
1 parent 81a2587 commit 0f60874
Show file tree
Hide file tree
Showing 2 changed files with 90 additions and 3 deletions.
13 changes: 11 additions & 2 deletions docs/src/main/docbook/jersey.ent
View file
Original file line number Diff line number Diff line change
Expand Up @@ -54,8 +54,9 @@
<!ENTITY jaxb.release.uri "https://eclipse-ee4j.github.io/jaxb-ri">
<!ENTITY jaxb.javadoc.uri "&jaxb.release.uri;/docs/api/javax/xml/bind">
<!ENTITY jaxrs.release.uri "https://github.com/jax-rs">
<!ENTITY jaxrs.javadoc.uri "https://jax-rs.github.io/apidocs/&jax-rs.version;/">
<!ENTITY jaxrs21.javadoc.uri "#/javax/ws/rs"> <!-- TODO - once we have published javadocs to link here -->
<!ENTITY jaxrs.javadoc.uri "https://jax-rs.github.io/apidocs/2.1/javax/ws/rs">
<!ENTITY jaxrs21.javadoc.uri "https://jax-rs.github.io/apidocs/2.1/javax/ws/rs">
<!ENTITY jsonb.javadoc.uri "https://javaee.github.io/javaee-spec/javadocs/javax/json/bind">

<!ENTITY jersey.ext.bean-validation.deps.link "<link xlink:href='&jersey.project-info.uri.prefix;/jersey-bean-validation/dependencies.html'>jersey-bean-validation</link>" >
<!ENTITY jersey.ext.declarative-linking.deps.link "<link xlink:href='&jersey.project-info.uri.prefix;/jersey-declarative-linking/dependencies.html'>jersey-declarative-linking</link>" >
Expand All @@ -67,6 +68,7 @@
<!ENTITY jersey.media.json-jettison.deps.link "<link xlink:href='&jersey.project-info.uri.prefix;/jersey-media-json-jettison/dependencies.html'>jersey-media-json-jettison</link>" >
<!ENTITY jersey.media.json-jackson.deps.link "<link xlink:href='&jersey.project-info.uri.prefix;/jersey-media-json-jackson/dependencies.html'>jersey-media-json-jackson</link>" >
<!ENTITY jersey.media.json-jackson1.deps.link "<link xlink:href='&jersey.project-info.uri.prefix;/jersey-media-json-jackson1/dependencies.html'>jersey-media-json-jackson1</link>" >
<!ENTITY jersey.media.json-binding.deps.link "<link xlink:href='&jersey.project-info.uri.prefix;/jersey-media-json-binding/dependencies.html'>jersey-media-json-binding</link>" >
<!ENTITY jersey.media.moxy.deps.link "<link xlink:href='&jersey.project-info.uri.prefix;/jersey-media-moxy/dependencies.html'>jersey-media-moxy</link>" >
<!ENTITY jersey.media.multipart.deps.link "<link xlink:href='&jersey.project-info.uri.prefix;/jersey-media-multipart/dependencies.html'>jersey-media-multipart</link>" >
<!ENTITY jersey.ext.mvc.deps.link "<link xlink:href='&jersey.project-info.uri.prefix;/jersey-mvc/dependencies.html'>jersey-mvc</link>" >
Expand Down Expand Up @@ -103,6 +105,7 @@
<!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>">
<!ENTITY yasson.link "<link xlink:href='https://eclipse-ee4j.github.io/yasson/'>Yasson</link>">

<!-- API Docs links -->
<!ENTITY bv.Configuration "<link xlink:href='&bv11.javadoc.uri;/javax/validation/Configuration.html'>Configuration</link>">
Expand Down Expand Up @@ -597,6 +600,8 @@
<!ENTITY javax.ws.rs.sse.SseEventSource "<link xlink:href='&jaxrs21.javadoc.uri;/sse/SseEventSource.html'>SseEventSource</link>">
<!ENTITY javax.ws.rs.sse.InboundSseEvent "<link xlink:href='&jaxrs21.javadoc.uri;/sse/InboundSseEvent.html'>InboundSseEvent</link>">

<!ENTITY jsonb.JsonbConfig "<link xlink:href='&jsonb.javadoc.uri;/JsonbConfig'>JsonbConfig</link>">

<!-- Links to specific JIRA issues -->
<!ENTITY jersey.jira.2883 "<link xlink:href='&jira.uri.prefix;/2838'>JERSEY-2838</link>">

Expand Down Expand Up @@ -636,6 +641,7 @@
<!ENTITY lit.jersey-media-json-jettison "<literal>jersey-media-json-jettison</literal>" >
<!ENTITY lit.jersey-media-json-jackson "<literal>jersey-media-json-jackson</literal>" >
<!ENTITY lit.jersey-media-json-jackson1 "<literal>jersey-media-json-jackson1</literal>" >
<!ENTITY lit.jersey-media-json-binding "<literal>jersey-media-json-binding</literal>" >
<!ENTITY lit.jersey-media-moxy "<literal>jersey-media-moxy</literal>" >
<!ENTITY lit.jersey-media-multipart "<literal>jersey-media-multipart</literal>" >
<!ENTITY lit.jersey-rx-client "<literal>jersey-rx-client</literal>" >
Expand Down Expand Up @@ -903,6 +909,7 @@
<!ENTITY lit.jersey.media.JettisonConfig "<literal>JettisonConfig</literal>" >
<!ENTITY lit.jersey.media.JettisonJaxbContext "<literal>JettisonJaxbContext</literal>" >
<!ENTITY lit.jersey.media.JsonProcessingFeature "<literal>JsonProcessingFeature</literal>" >
<!ENTITY lit.jersey.media.JsonBindingFeature "<literal>JsonBindingFeature</literal>" >
<!ENTITY lit.jersey.media.MoxyJsonConfig "<literal>MoxyJsonConfig</literal>" >
<!ENTITY lit.jersey.media.MoxyJsonFeature "<literal>MoxyJsonFeature</literal>" >
<!ENTITY lit.jersey.media.ObjectMapper "<literal>ObjectMapper</literal>" >
Expand Down Expand Up @@ -1036,3 +1043,5 @@
<!ENTITY lit.jersey.test.spi.TestContainerFactory "<literal>TestContainerFactory</literal>">
<!ENTITY lit.jersey.test.util.LoopBackConnectorProvider "<literal>LoopBackConnectorProvider</literal>">
<!ENTITY lit.jersey.test.util.ContainerRequestBuilder "<literal>ContainerRequestBuilder</literal>">

<!ENTITY lit.jsonb.Jsonb "<literal>Jsonb</literal>">
80 changes: 79 additions & 1 deletion docs/src/main/docbook/media.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@
<!ENTITY link.json-p "<link linkend='json.json-p'>Java API for JSON Processing (JSON-P)</link>" >
<!ENTITY link.jackson "<link linkend='json.jackson'>Jackson</link>" >
<!ENTITY link.jettison "<link linkend='json.jettison'>Jettison</link>" >
<!ENTITY link.json-b "<link linkend='json.json-b'>Java API for JSON Binding (JSON-B)</link>" >

<!ENTITY % ents SYSTEM "jersey.ent" > %ents;
]>
Expand Down Expand Up @@ -64,6 +65,9 @@
<listitem>
<para>&link.jettison;</para>
</listitem>
<listitem>
<para>&link.json-b;</para>
</listitem>
</itemizedlist>
</para>

Expand Down Expand Up @@ -97,7 +101,7 @@
<title>POJO support</title>

<para>POJO support represents the easiest way to convert your Java Objects to JSON and back.</para>
<para>Media modules that support this approach are &link.moxy; and &link.jackson;</para>
<para>Media modules that support this approach are &link.moxy;, &link.jackson;, and &link.json-b;</para>
</section>

<section xml:id="json-jaxb">
Expand Down Expand Up @@ -1076,6 +1080,80 @@ public JaxbBean getSimpleJSONP() {
</para>
</formalpara>
</section>
<section xml:id="json.json-b">
<title>Java API for JSON Binding (JSON-B)</title>

<para>
Jersey uses &yasson.link; for JSON Binding (JSR-367) implementation.
</para>
<section>
<title>Dependency</title>
<para>
To use JSON-B as your JSON provider you need to add &lit.jersey-media-json-binding; module to your
&lit.pom.xml; file:

<programlisting language="xml" linenumbering="unnumbered">&lt;dependency&gt;
&lt;groupId&gt;org.glassfish.jersey.media&lt;/groupId&gt;
&lt;artifactId&gt;jersey-media-json-binding&lt;/artifactId&gt;
&lt;version&gt;&version;&lt;/version&gt;
&lt;/dependency&gt;</programlisting>

If you're not using Maven make sure to have all needed dependencies
(see &jersey.media.json-binding.deps.link;) on the classpath.
</para>
</section>

<section xml:id="json.jsonb-registration">
<title>Configure and register</title>

<para>
As stated in <xref linkend="deployment.autodiscoverable"/> JSON-Binding media module is one of the
modules where you don't need to explicitly register its
&lit.jaxrs.core.Feature;s (&lit.jersey.media.JsonBindingFeature;) in your client/server
&jaxrs.core.Configurable; as this feature is automatically discovered and registered when you add
&lit.jersey-media-json-binding; module to your classpath.
</para>
<para>
To use custom preconfigured JSON-B, it is simply possible to register
a &lit.jaxrs.ext.ContextResolver; for &lit.jsonb.Jsonb; in your &jaxrs.core.Configurable;
(client/server) and configure &jsonb.JsonbConfig;.
</para>

<example>
<title><literal>ContextResolver&lt;Jsonb&gt;</literal></title>

<programlisting language="java">@Provider
public class JsonbContextResolver implements ContextResolver&lt;Jsonb&gt; {

@Override
public Jsonb getContext(Class&gt;?&lt; type) {
JsonbConfig config = new JsonbConfig();
// configure JsonbConfig
...
return JsonbBuilder.create(config);
}
}</programlisting>
</example>
<example>
<title><literal>Register the feature and ContextResolver&lt;Jsonb></literal></title>
<programlisting language="java">ClientBuilder.newClient(new ClientConfig()
// The line below that registers JSON-Binding feature can be
// omitted if FEATURE_AUTO_DISCOVERY_DISABLE is not disabled.
.register(JsonBindingFeature.class)
.register(JsonbContextResolver.class)
);</programlisting>
</example>

<formalpara>
<title>Example</title>
<para>
You can take a look at a provided
<link xlink:href='&jersey.github.examples.uri;/json-binding-webapp'>JSON-B example.</link>.
</para>
</formalpara>
</section>

</section>
</section>

<section xml:id="xml">
Expand Down

0 comments on commit 0f60874

Please sign in to comment.