<commit_before>= Servlets in brief
:toc:
:toc-placement: preamble
:sectanchors:

This document gives a (rough and incomplete) overview of Servlets in Java EE application servers. This document may serve as an introduction to application servers in Java EE.

== Overview
=== Application servers
Java EE defines a http://www.oracle.com/technetwork/java/javaee/tech/index.html[set] of specifications, known as Java Specification Requests (JSR). Application servers have to implement [small]#(parts of)# these standards in order to be compliant with [small]#(a subset of)# Java EE. An important standard among those is the Servlet API, or https://www.jcp.org/en/jsr/detail?id=340[JSR 340].

A Java EE application server is a piece of software that ease the development of web applications, by providing services to the Java web developer. Your application server provides containers in which you, the web developer, embed your code. The container calls your code whenever adequate.

Examples of Java EE compliant application servers: GlassFish (Oracle, open source, reference implementation of Java EE), WildFly (Red Hat / JBoss, open source), WebSphere AS (IBM)…

=== Servlets
A servlet is a piece of software that, given some web request parameters, returns some response to the request. You, the web application developer, write the code that, given the request parameters, computes the response. That code gets embedded into the “web” container of your application server.

The web container is one of the containers provided by any Java EE compliant application server. The web container listens for web requests on some port and will call your servlet code whenever it detects a web request directed to your servlet. The Java servlet specification also defines how to tell the application server which web requests should be sent to your servlet code.

An application will typically contain many such servlets, configured to process different kinds of web requests.

In this document, web requests are considered to be HTTP requests. [small]#(The specification is more general but I doubt anybody would seriously consider writing non HTTP servlets in a Java EE application server.)#

=== HTTP requests
HTTP, Hypertext Transfer Protocol, is a W3C / IETF https://tools.ietf.org/html/rfc7540[standard] that describes a way of exchanging information between a client and a server. It is ubiquitous on the internet. In an HTTP exchange, a client sends an HTTP request to a server, then the server sends an HTTP response back to the client. An HTTP message is either an HTTP request or an HTTP response. The client is typically a browser (such as your browser you use when you browse the internet).

.An HTTP exchange
====
. A client sends an HTTP request, targeted to http://example.com/mycat, specifying that the chosen HTTP method is HTTP GET.
. The server replies with an HTTP response with a header “content-type = image/jpeg” and a message body containing an image of a cat.
====

An HTTP message contains headers and possibly a message body [small]#(this document considers pseudo-headers or start-line data as headers, for simplicity)#. The headers for an HTTP request specify the URI that the request targets, the request method to be used for the exchange, and possibly other information such as the encodings used in the message body, … The headers for an HTTP response specify the status code (three digits that indicate whether something went wrong), and possibly other information such as the content-type of the message body, …

HTTP requests target _resources_, identified by URIs (Uniform Resource Identifiers). For example, the URI http://example.com/mycat might identify the resource describing someone’s cat.

Request methods indicate the request semantics: what the client wishes to do in relation with the targeted resource. A GET request method asks the server for a current representation of the target resource. This is the method your browser uses when you type a URI in your browser navigation bar and hit enter, and by far the most common request method. A GET request [small]#typically# has no message body. A POST request method, on the contrary, typically has a message body. It asks the server to perform resource-specific processing on the message body. It is typically used to post new data to a server, for example, to post a new image of your cat for it to become accessible at some URI.

== Servlets in Java EE

=== My first servlet
For you to define a new servlet that will be recognized as such by the container, you must define a new class that represents your servlet, and:

* your class must extend http://docs.oracle.com/javaee/7/api/javax/servlet/http/HttpServlet.html[`HttpServlet`] (a class provided by Java EE);
* your class must be annotated with http://docs.oracle.com/javaee/7/api/javax/servlet/annotation/WebServlet.html[`@WebServlet`];
* your class overrides one method, depending on the request method you want it to handle.

The value of the `@WebServlet` annotation is the URI at which your servlet must be reached.

//[source, java]
.An example of a Java EE servlet
--
include::https://github.com/oliviercailloux/samples/raw/master/JavaEE-Servlets/src/main/java/io/github/oliviercailloux/javaee_servlets/servlets/SayHelloServlet.java[]
--

(You may define more than one servlet. [small]#The constraints described above are not the only way to define a Java EE compliant servlet.#)
<commit_msg>Format links<commit_after>= Servlets in brief
:toc:
:toc-placement: preamble
:sectanchors:

This document gives a (rough and incomplete) overview of Servlets in Java EE application servers. This document may serve as an introduction to application servers in Java EE.

== Overview
=== Application servers
Java EE defines a http://www.oracle.com/technetwork/java/javaee/tech/index.html[set] of specifications, known as Java Specification Requests (JSR). Application servers have to implement [small]#(parts of)# these standards in order to be compliant with [small]#(a subset of)# Java EE. An important standard among those is the Servlet API, or https://www.jcp.org/en/jsr/detail?id=340[JSR 340].

A Java EE application server is a piece of software that ease the development of web applications, by providing services to the Java web developer. Your application server provides containers in which you, the web developer, embed your code. The container calls your code whenever adequate.

Examples of Java EE compliant application servers: GlassFish (Oracle, open source, reference implementation of Java EE), WildFly (Red Hat / JBoss, open source), WebSphere AS (IBM)…

=== Servlets
A servlet is a piece of software that, given some web request parameters, returns some response to the request. You, the web application developer, write the code that, given the request parameters, computes the response. That code gets embedded into the “web” container of your application server.

The web container is one of the containers provided by any Java EE compliant application server. The web container listens for web requests on some port and will call your servlet code whenever it detects a web request directed to your servlet. The Java servlet specification also defines how to tell the application server which web requests should be sent to your servlet code.

An application will typically contain many such servlets, configured to process different kinds of web requests.

In this document, web requests are considered to be HTTP requests. [small]#(The specification is more general but I doubt anybody would seriously consider writing non HTTP servlets in a Java EE application server.)#

=== HTTP requests
HTTP, Hypertext Transfer Protocol, is a W3C / IETF https://tools.ietf.org/html/rfc7540[standard] that describes a way of exchanging information between a client and a server. It is ubiquitous on the internet. In an HTTP exchange, a client sends an HTTP request to a server, then the server sends an HTTP response back to the client. An HTTP message is either an HTTP request or an HTTP response. The client is typically a browser (such as your browser you use when you browse the internet).

.An HTTP exchange
====
. A client sends an HTTP request, targeted to +++http://example.com/mycat+++, specifying that the chosen HTTP method is HTTP GET.
. The server replies with an HTTP response with a header “content-type = image/jpeg” and a message body containing an image of a cat.
====

An HTTP message contains headers and possibly a message body [small]#(this document considers pseudo-headers or start-line data as headers, for simplicity)#. The headers for an HTTP request specify the URI that the request targets, the request method to be used for the exchange, and possibly other information such as the encodings used in the message body, … The headers for an HTTP response specify the status code (three digits that indicate whether something went wrong), and possibly other information such as the content-type of the message body, …

HTTP requests target _resources_, identified by URIs (Uniform Resource Identifiers). For example, the URI +++http://example.com/mycat+++ might identify the resource describing someone’s cat.

Request methods indicate the request semantics: what the client wishes to do in relation with the targeted resource. A GET request method asks the server for a current representation of the target resource. This is the method your browser uses when you type a URI in your browser navigation bar and hit enter, and by far the most common request method. A GET request [small]#typically# has no message body. A POST request method, on the contrary, typically has a message body. It asks the server to perform resource-specific processing on the message body. It is typically used to post new data to a server, for example, to post a new image of your cat for it to become accessible at some URI.

== Servlets in Java EE

=== My first servlet
For you to define a new servlet that will be recognized as such by the container, you must define a new class that represents your servlet, and:

* your class must extend http://docs.oracle.com/javaee/7/api/javax/servlet/http/HttpServlet.html[`HttpServlet`] (a class provided by Java EE);
* your class must be annotated with http://docs.oracle.com/javaee/7/api/javax/servlet/annotation/WebServlet.html[`@WebServlet`];
* your class overrides one method, depending on the request method you want it to handle.

The value of the `@WebServlet` annotation is the URI at which your servlet must be reached.

//[source, java]
.An example of a Java EE servlet
--
include::https://github.com/oliviercailloux/samples/raw/master/JavaEE-Servlets/src/main/java/io/github/oliviercailloux/javaee_servlets/servlets/SayHelloServlet.java[]
--

(You may define more than one servlet. [small]#The constraints described above are not the only way to define a Java EE compliant servlet.#)

{'fraction_non_alphanumeric': 0.057792863040088065, 'fraction_numerical': 0.0023851022841941106, 'mean_word_length': 4.684045881126173, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 6, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2300940', 'n_tokens_mistral': 2684, 'n_tokens_neox': 2570, 'n_words': 1581}