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

Jakartified User Guide - second 10 chapters #4656

Merged
merged 2 commits into from
Jan 7, 2021
Merged

Jakartified User Guide - second 10 chapters #4656

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1d72ea2
another 10 chapters and revised client,deployment,getting-started
senivam Dec 14, 2020
a42a934
Jakartified User Guide - 2 chapters revised
senivam Jan 5, 2021
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
6 changes: 3 additions & 3 deletions docs/src/main/docbook/async.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ public class AsyncResource {
when the method returns. Instead, the injected &lit.jaxrs.container.AsyncResponse; instance (that represents the
suspended client request connection) will be used to explicitly send the response back to the client using some other
thread. In other words, Jersey runtime knows that when the <literal>asyncGet</literal> method completes, the response
to the client may not be ready yet and the processing must be suspended and wait to be explictly resumed with a
to the client may not be ready yet and the processing must be suspended and wait to be explicitly resumed with a
response once it becomes available. Note that the method <literal>asyncGet</literal> returns <literal>void</literal>
in our example. This is perfectly valid in case of an asynchronous JAX-RS resource method, even for a &jaxrs.GET;
method, as the response is never returned directly from the resource method as its return value. Instead, the response
Expand Down Expand Up @@ -250,7 +250,7 @@ public class AsyncResource {
In Jersey you can use &jersey.server.ChunkedOutput; to send response to a client in chunks. Chunks are strictly
defined pieces of a response body can be marshalled as a separate entities using Jersey/JAX-RS
&jaxrs.ext.MessageBodyWriter; providers. A chunk can be String, Long or JAXB bean serialized to XML or JSON or
any other dacustom type for which a &lit.jaxrs.ext.MessageBodyWriter; is available.
any other defined custom type for which a &lit.jaxrs.ext.MessageBodyWriter; is available.
</para>
<para>
The resource method
Expand Down Expand Up @@ -484,7 +484,7 @@ while ((chunk = chunkedInput.read()) != null) {
&lit.jersey.client.ChunkedInput; does not know how to distinguish chunks in the byte stream unless being told by
the developer. In order to define custom chunks boundaries,
the &lit.jersey.client.ChunkedInput; offers possibility to register a &jersey.client.ChunkParser; which
reads chunks from the input stream and separates them. Jersey provides several chunk parser implementation and
reads chunks from the input stream and separates them. Jersey provides several chunk parser implementations and
you can implement your own parser to separate your chunks if you need. In our example above the default parser
provided by Jersey is used that separates chunks based on presence of a <literal>\r\n</literal> delimiting
character sequence.
Expand Down
19 changes: 8 additions & 11 deletions docs/src/main/docbook/bean-validation.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@
</note>

This module depends directly on
<link xlink:href="http://www.hibernate.org/subprojects/validator.html">Hibernate Validator</link>
<link xlink:href="http://hibernate.org/validator/">Hibernate Validator</link>
which provides a most commonly used implementation of the Bean Validation API spec.
</para>
<para>
Expand Down Expand Up @@ -242,9 +242,7 @@ public class ValidationConfigurationContextResolver implements ContextResolver&l
.register( ... );</programlisting>

<note>
<para>This code snippet has been taken from
<link xlink:href='&jersey.github.examples.uri;/bean-validation-webapp'>Bean Validation example</link>.
</para>
<para>This code snippet is based on CustomConfigValidationTest (from Jersey's source codes)</para>
</note>
</example>
</para>
Expand Down Expand Up @@ -277,7 +275,7 @@ public class ValidationConfigurationContextResolver implements ContextResolver&l
</para>
<para>
The Bean Validation specification supports the use of <emphasis>constraint annotations</emphasis>
as a way of declaratively validating beans, method parameters and method returned values. For example, consider
as a way of declarative validating beans, method parameters and method returned values. For example, consider
resource class from <xref linkend="bv.example.constraints"/> augmented with constraint annotations.

<example xml:id="bv.example.constraints">
Expand Down Expand Up @@ -723,7 +721,7 @@ public final class ValidationError {
Content-Length: 114
Content-Type: text/plain
Vary: Accept
Server: Jetty(6.1.24)
Server: Jetty(11.0.0.beta3)

Contact with given ID does not exist. (path = ContactCardResource.getContact.&lt;return value&gt;, invalidValue = null)</screen>
</example>
Expand All @@ -734,7 +732,7 @@ Contact with given ID does not exist. (path = ContactCardResource.getContact.&lt
Content-Length: ...
Content-Type: text/plain
Vary: Accept
Server: Jetty(6.1.24)
Server: Jetty(11.0.0.beta3)

<![CDATA[<div class="validation-errors">
<div class="validation-error">
Expand All @@ -760,7 +758,7 @@ Server: Jetty(6.1.24)
Content-Length: ...
Content-Type: text/plain
Vary: Accept
Server: Jetty(6.1.24)
Server: Jetty(11.0.0.beta3)

<![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<validationErrors>
Expand All @@ -778,7 +776,7 @@ Server: Jetty(6.1.24)
Content-Length: 174
Content-Type: application/json
Vary: Accept
Server: Jetty(6.1.24)
Server: Jetty(11.0.0.beta3)

[ {
"message" : "Contact with given ID does not exist.",
Expand All @@ -793,7 +791,6 @@ Server: Jetty(6.1.24)
<section>
<title>Example</title>

<para>To see a complete working example of using Bean Validation (JSR-349) with Jersey refer to the
<link xlink:href='&jersey.github.examples.uri;/bean-validation-webapp'>Bean Validation Example</link>.</para>
<para>Examples are being processed to comply with Jakarta EE standards.</para>
</section>
</chapter>
4 changes: 2 additions & 2 deletions docs/src/main/docbook/client.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@

<para>
This section introduces the JAX-RS Client API, which is a fluent Java based API for communication with RESTful Web
services. This standard API that is also part of Java EE 7 is designed to make it very easy to consume a Web service
services. This standard API that is also part of Jakarta EE 9 is designed to make it very easy to consume a Web service
exposed via HTTP protocol and enables developers to concisely and efficiently implement portable client-side solutions
that leverage existing and well established client-side HTTP connector implementations.
</para>
Expand Down Expand Up @@ -546,7 +546,7 @@ String entity = client.target("http://example.com/rest")
do require running on another thread, should be executed using provided services.
</para>
<para>
Default values do depend on the environment - in Java EE container, it has to be &jee6.jakarta.enterprise.concurrent.ManagedExecutorService;
Default values do depend on the environment - in Java/Jakarta EE container, it has to be &jee6.jakarta.enterprise.concurrent.ManagedExecutorService;
and &jee6.jakarta.enterprise.concurrent.ManagedScheduledExecutorService;, for Java SE it would be
<literal>ForkJoinPool.commonPool</literal> for Executor service and something undefined for Scheduled
executor service.
Expand Down
20 changes: 10 additions & 10 deletions docs/src/main/docbook/deployment.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@
<para>
This chapter is an overview of various server-side environments currently capable of running JAX-RS applications
on top of Jersey server runtime. Jersey supports wide range of server environments from lightweight http containers
up to full-fledged Java EE servers. Jersey applications can also run in an OSGi runtime.
up to full-fledged Java/Jakarta EE servers. Jersey applications can also run in an OSGi runtime.
The way how the application is published depends on whether the application shall run in a Java SE environment or
within a container.
</para>
Expand Down Expand Up @@ -978,18 +978,18 @@ public class MyApplication extends ResourceConfig {
</section>

<section xml:id="deployment.javaee">
<title>Java EE Platform</title>
<title>Jakarta EE Platform</title>
<para>
This section describes, how you can publish Jersey JAX-RS resources as various Java EE platform elements.
This section describes, how you can publish Jersey JAX-RS resources as various Jakarta EE platform elements.
JAX-RS and Jersey give you wide choice of possibilities and it is up to your taste (and design of your application),
what Java EE technology you decide to use for the management of your resources.
what Jakarta EE technology you decide to use for the management of your resources.
</para>

<section xml:id="deployment.javaee.managed">
<title>Managed Beans</title>

<para>
Jersey supports the use of Java EE Managed beans as root resource classes, providers as well as
Jersey supports the use of Jakarta EE Managed beans as root resource classes, providers as well as
&lit.jaxrs.core.Application; subclasses.
</para>

Expand Down Expand Up @@ -1044,9 +1044,9 @@ public class CdiBeanResource {
}</programlisting>
</para>
<para>
The above works naturally inside any Java EE compliant AS container. In Jersey version 2.15, container agnostic CDI support was introduced.
The above works naturally inside any Java/Jakarta EE compliant AS container. In Jersey version 2.15, container agnostic CDI support was introduced.
This feature allows you to publish CDI based JAX-RS resources also in other containers. Jersey cdi-webapp example shows Jersey/CDI integration
in Grizzly HTTP and Apache Tomcat server. Detailed description of Jersey CDI support outside of a fully fledged Java EE application container
in Grizzly HTTP and Apache Tomcat server. Detailed description of Jersey CDI support outside of a fully fledged Java/Jakarta EE application container
could be found in <xref linkend="cdi.support"/>.
</para>
</section>
Expand Down Expand Up @@ -1093,7 +1093,7 @@ public class StatelessEjbResource implements LocalEjb {
</section>

<section xml:id="deployment.appservers">
<title>Java EE Servers</title>
<title>Jakarta EE Servers</title>

<section xml:id="deployment.appservers.glassfish">
<title>GlassFish Application Server</title>
Expand Down Expand Up @@ -1143,7 +1143,7 @@ public class StatelessEjbResource implements LocalEjb {
<title>Other Application Servers</title>

<para>
Third party Java EE application servers usually ship with a JAX-RS implementation. If you want to
Third party Java/Jakarta EE application servers usually ship with a JAX-RS implementation. If you want to
use Jersey instead of the default JAX-RS provider, you need to add Jersey libraries to your classpath and
disable the default JAX-RS provider in the container.
</para>
Expand All @@ -1170,7 +1170,7 @@ public class StatelessEjbResource implements LocalEjb {
<listitem>HTTP Service</listitem>
</itemizedlist>

WAB is in fact just an OSGified WAR archive. HTTP Service feature allows you to publish Java EE Servlets in
WAB is in fact just an OSGified WAR archive. HTTP Service feature allows you to publish Jakarta EE Servlets in
the OSGi runtime.
</para>
<para>
Expand Down
16 changes: 8 additions & 8 deletions docs/src/main/docbook/entity-filtering.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -470,7 +470,7 @@ public @interface ProjectDetailedView {

<itemizedlist>
<listitem>
<para>Out-bound client request or server response programmatically created with entity-filtering annotations
<para>Outbound client request or server response programmatically created with entity-filtering annotations
that identify the scopes to be applied (available on both, client and server)</para>
</listitem>
<listitem>
Expand Down Expand Up @@ -580,7 +580,7 @@ public class ProjectsResource {
Or, to illustrate this in JSON format:

<programlisting language="xml" linenumbering="numbered">{
"description" : "Jersey is the open source (under dual EPL+GPL license) JAX-RS 2.1 (JSR 370) production quality Reference Implementation for building RESTful Web services.",
"description" : "Jersey is the open source (under dual EPL+GPL license) JAX-RS 3.0 production quality Reference Implementation for building RESTful Web services.",
"id" : 1,
"name" : "Jersey",
"tasks" : [ {
Expand Down Expand Up @@ -612,7 +612,7 @@ public class ProjectsResource {
Or in JSON format:

<programlisting language="xml" linenumbering="numbered">{
"description" : "Jersey is the open source (under dual EPL+GPL license) JAX-RS 2.1 (JSR 370) production quality Reference Implementation for building RESTful Web services.",
"description" : "Jersey is the open source (under dual EPL+GPL license) JAX-RS 3.0 production quality Reference Implementation for building RESTful Web services.",
"id" : 1,
"name" : "Jersey"
}</programlisting>
Expand Down Expand Up @@ -671,13 +671,13 @@ public class ClientsResource {

<itemizedlist>
<listitem>
<para>&jee6.annotations.PermitAll;,</para>
<para>&jee9.annotations.PermitAll;,</para>
</listitem>
<listitem>
<para>&jee6.annotations.RolesAllowed;, and</para>
<para>&jee9.annotations.RolesAllowed;, and</para>
</listitem>
<listitem>
<para>&jee6.annotations.DenyAll;</para>
<para>&jee9.annotations.DenyAll;</para>
</listitem>
</itemizedlist>
</para>
Expand All @@ -690,13 +690,13 @@ public class ClientsResource {
<listitem>
<para>
Custom &jaxrs.core.SecurityContext; should be set by a container request filter in order to use
&lit.jee6.annotations.RolesAllowed; for role-based filtering of domain model data (server-side)
&lit.jee9.annotations.RolesAllowed; for role-based filtering of domain model data (server-side)
</para>
</listitem>
<listitem>
<para>
There is no need to provide entity-filtering (or security) annotations on resource methods in order to
define entity-filtering scopes for &lit.jee6.annotations.RolesAllowed; that is applied to the domain model
define entity-filtering scopes for &lit.jee9.annotations.RolesAllowed; that is applied to the domain model
components, as all the available roles for the current user are automatically determined using
the information from the provided &lit.jaxrs.core.SecurityContext; (server-side only).
</para>
Expand Down
12 changes: 7 additions & 5 deletions docs/src/main/docbook/filters.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -257,7 +257,7 @@ public class PreMatchingFilter implements ContainerRequestFilter {
To summarize the workflow, for any client request invoked from the client API
the client request filters (&jaxrs.client.ClientRequestFilter;)
are executed that could manipulate the request.
If not aborted, the outcoming request is then physically sent over to the server side
If not aborted, the outgoing request is then physically sent over to the server side
and once a response is received back from the server the client response
filters (&jaxrs.client.ClientResponseFilter;)
are executed that might again manipulate the returned response.
Expand Down Expand Up @@ -308,7 +308,7 @@ public class PreMatchingFilter implements ContainerRequestFilter {
</example>
</para>
<para>
The interceptor gets a output stream from the &jaxrs.WriterInterceptorContext; and sets
The interceptor gets an output stream from the &jaxrs.WriterInterceptorContext; and sets
a new one which is a GZIP wrapper of the original output stream. After all interceptors are executed the
output stream lastly set to the &lit.jaxrs.WriterInterceptorContext; will be used for serialization of the entity. In the
example above the entity bytes will be written to the GZIPOutputStream which will compress the stream data
Expand All @@ -320,7 +320,8 @@ public class PreMatchingFilter implements ContainerRequestFilter {
The interceptors wrap the streams and they itself work as wrappers. This means that each interceptor is a wrapper
of another interceptor and it is responsibility of each interceptor implementation to call the wrapped interceptor.
This is achieved by calling the <literal>proceed()</literal> method on the &lit.jaxrs.WriterInterceptorContext;.
This method will call the next registered interceptor in the chain, so effectivelly this will call all remaining registered interceptors. Calling <literal>proceed()</literal> from the last
This method will call the next registered interceptor in the chain, so effectively this will call all remaining
registered interceptors. Calling <literal>proceed()</literal> from the last
interceptor in the chain will call the appropriate message body reader. Therefore every interceptor must call the
<literal>proceed()</literal> method otherwise the entity would not be written. The wrapping principle is reflected
also in the method name, aroundWriteTo, which says that the method is wrapping the writing of the entity.
Expand Down Expand Up @@ -389,11 +390,12 @@ public class PreMatchingFilter implements ContainerRequestFilter {
<listitem>Client request invoked: The POST request with attached entity is built on the client and invoked.</listitem>
<listitem>ClientRequestFilters: client request filters are executed on the client and they
manipulate the request headers.</listitem>
<listitem>Client &lit.jaxrs.WriterInterceptor;: As the request contains an entity, writer interceptor registered on the client is executed before
<listitem>Client &lit.jaxrs.WriterInterceptor;: As the request contains an entity, writer interceptor registered
on the client is executed before
a MessageBodyWriter is executed. It wraps the entity output stream with the GZipOutputStream.</listitem>
<listitem>Client MessageBodyWriter: message body writer is executed on the client which serializes the entity
into the new GZipOutput stream. This stream zips the data and sends it to the "wire".</listitem>
<listitem>Server: server receives a request. Data of entity is compressed which means that pure read from
<listitem>Server: server receives a request. Data of the entity is compressed which means that pure read from
the entity input stream would return compressed data.</listitem>
<listitem>Server pre-matching ContainerRequestFilters: ContainerRequestFilters are executed that can manipulate
resource method matching process.</listitem>
Expand Down
Loading