Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Added Documentation for JSON-B support #4502

Merged
merged 1 commit into from
Jun 25, 2020
Merged

Added Documentation for JSON-B support #4502

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 11 additions & 2 deletions docs/src/main/docbook/jersey.ent
View file
Open in desktop
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
Open in desktop
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