Getting Started with Web Applications

This describes steps 3 through 6. You need Maven and a servlet container.
本文将介绍第 3 步至第 6 步。您需要 Maven 和 servlet 容器。

In a typical Jakarta Servlet-based web application, the class must extend jakarta.servlet.http.HttpServlet and override one of the doXxx() methods where Xxx represents the HTTP method of interest. Such a class is in the Jakarta Servlet world called a Servlet.
在典型的基于 Jakarta Servlet 的 Web 应用程序中，类必须扩展 jakarta.servlet.http.HttpServlet 并覆盖 doXxx() 方法之一，其中 Xxx 代表感兴趣的 HTTP 方法。在 Jakarta Servlet 的世界里，这样的类被称为 Servlet。

For this Hello World web application, the src/main/java/jakarta/tutorial/web/servlet/Greeting.java servlet listens on HTTP GET requests and extracts the name request parameter as input and creates the greeting as output.
在这个 Hello World 网络应用程序中， src/main/java/jakarta/tutorial/web/servlet/Greeting.java 服务程序监听 HTTP GET 请求，提取 name 请求参数作为输入，并创建 greeting 作为输出。

When the servlet container receives a request, it must determine which web component should handle the request. The servlet container does so by mapping the URL contained in the request to a web component. A URL contains the context path and, optionally, a URL pattern:
当 servlet 容器收到一个请求时，它必须确定由哪个网络组件来处理该请求。为此，Servlet 容器会将请求中包含的 URL 映射到网络组件。URL 包含上下文路径和可选的 URL 模式：

You can set the URL pattern for a servlet by using the @WebServlet annotation in the servlet source file or by using <servlet-mapping> entry in the Jakarta Servlet deployment descriptor file, the src/main/webapp/WEB-INF/web.xml. In the Greeting servlet example the @WebServlet annotation indicates that the URL pattern is /greeting. Therefore, when the servlet is deployed to a local server listening on http://localhost:8080 with the context path set to hello-servlet, it is accessed with the following URL:
您可以通过使用 servlet 源文件中的 @WebServlet 注释或 Jakarta Servlet 部署描述符文件中的 <servlet-mapping> 条目（即 src/main/webapp/WEB-INF/web.xml ）来设置 servlet 的 URL 模式。 在 Greeting servlet 示例中， @WebServlet 注释表示 URL 模式为 /greeting 。因此，当 servlet 部署到监听 http://localhost:8080 且上下文路径设置为 hello-servlet 的本地服务器上时，可通过以下 URL 进行访问：

The Hello World example will return an HTTP 400 error as response indicating a 'Bad Request'. When specifying the name as a request parameter in the following URL:
Hello World 示例将返回 HTTP 400 错误，表示 "错误请求"。在以下 URL 中指定名称作为请求参数时：

Then it will return the response Hello, Duke!.
然后会返回 Hello, Duke! 。

Build and deploy as instructed in Building, Deploying and Running The Example Projects.

In a web browser, open the following URL:

It will return the response Hello, Duke!. You can edit the name parameter into something else to get a different response.

This will return the response Hello, Joe!.

In a typical Jakarta Faces application, the model (the "M" part of MVC) is represented by a bean class. Such a bean class is in the Jakarta Faces world called a Backing Bean.

For this Hello World web application, the src/main/java/jakarta/tutorial/web/faces/Hello.java backing bean defines a name property along with a getter and setter, a greeting property along with a getter, and a submit action method which creates the greeting as output-based on name as input.

Note that a getter is required for output and that a setter is only required for input.

In a typical Jakarta Faces application, CDI is used to manage the backing beans. We’ll briefly go through the CDI annotations that are used here:

In a typical Jakarta Faces application, the view (the "V" part of MVC) is represented by a XHTML file. Such a XHTML file is in the Jakarta Faces world called a Facelets File or just Facelet. In Jakarta Faces, the view technology is pluggable and Facelets is used as the default view technology. XHTML markup is being used because it allows the framework to easily use a XML parser to find Jakarta Faces tags of interest and to generate HTML output.

For this Hello World web application, the src/main/webapp/hello.xhtml Facelet defines a form with an input field, a command button and an output field.

We’ll briefly go through the Jakarta Faces-specific XHTML tags that are used here.

The <h:…​> tags define standard HTML components. The <f:…​> tags define behavior.

The input value is via EL value expression #{hello.name} connected to the name property of the Hello backing bean via its getter and setter. The output value is via EL value expression #{hello.greeting} connected to the greeting property of the Hello backing bean via its getter. The command button is via EL method expression #{hello.submit} connected to the submit method of the Hello backing bean.

Note that for EL value expressions the physical field representing the property doesn’t need to have exactly the same name nor that it needs to exist at all. EL only looks for the getter and setter methods, not for the field.

In a typical Jakarta Faces application, the controller (the "C" part of MVC) is registered in the Jakarta Servlet deployment descriptor file, the src/main/webapp/WEB-INF/web.xml.

It basically instructs the servlet container to create an instance of jakarta.faces.webapp.FacesServlet as facesServlet during startup and to execute it when the URL pattern of the HTTP request matches *.xhtml.

Build and deploy as instructed in Building, Deploying and Running The Example Projects.

In a web browser, open the following URL:

It will show a web page with a form asking for your name. Enter your name in the input field of the form, for example 'Duke', and click Submit. This will show the text Hello, Duke! below the form.

The Jakarta Servlet deployment descriptor is represented by the WEB-INF/web.xml file which is in a Maven-based project placed in src/main/webapp folder. It must be a XML file with a <web-app> root element conform the web-app_X_Y.xsd XML schema of the https://jakarta.ee/xml/ns/jakartaee namespace.
Jakarta Servlet 部署描述符由 WEB-INF/web.xml 文件表示，该文件位于 src/main/webapp 文件夹中基于 Maven 的项目中。它必须是一个 XML 文件，其 <web-app> 根元素符合 https://jakarta.ee/xml/ns/jakartaee 命名空间的 web-app_X_Y.xsd XML 架构。

The web components in a web application share an object that represents their application context, the jakarta.servlet.ServletContext. You define context-wide initialization parameters in the web.xml file.
网络应用程序中的网络组件共享一个代表其应用程序上下文的对象，即 jakarta.servlet.ServletContext 。您可以在 web.xml 文件中定义整个上下文的初始化参数。

You can obtain them in application code via getInitParameter(String name) method of the ServletContext instance.
您可以在应用程序代码中通过 ServletContext 实例的 getInitParameter(String name) 方法获取它们。

These context parameters can be used to configure (default) application-wide variables, such as the web application’s project stage, the path to save uploaded files, the path to a more specific configuration file, the maximum size of a cache, the expiration time of a cacheable resource, the name of the tenant/theme/scheme, or even helper library specific parameters, etcetera, but never passwords. It are those variables which you’d normally define as constants in a Java class, but then without the need to recompile Java classes whenever you’d like to edit them.
这些上下文参数可用于配置（默认）应用程序范围内的变量，如网络应用程序的项目阶段、保存上传文件的路径、更具体的配置文件的路径、缓存的最大大小、可缓存资源的过期时间、租户/主题/方案的名称，甚至辅助库的具体参数等，但绝不包括密码。这些变量通常在 Java 类中定义为常量，但在编辑这些变量时无需重新编译 Java 类。

The welcome files mechanism allows you to specify a list of files that the servlet container can return as a default resource when any folder is requested which does not map to an existing web component. For example, suppose that you define two welcome files index.xhtml and index.html. So, if for example the / folder is requested, and it does not map to a web component, then it’ll search for /index.xhtml and /index.html files and return the first found one. Or if there is none, then the servlet container will continue to perform the default behavior, which is usually displaying an HTTP 404 error page. Note that this also applies to sub folders, so if for example the /foo folder is requested, then it’ll search for /foo/index.xhtml and /foo/index.html files and return the first found one. You specify welcome files in the web.xml file.
欢迎文件机制允许你指定一个文件列表，当请求的任何文件夹没有映射到现有的网络组件时，Servlet 容器可将其作为默认资源返回。例如，假设您定义了两个欢迎文件 index.xhtml 和 index.html 。因此，如果请求 / 文件夹，但它没有映射到网络组件，那么它就会搜索 /index.xhtml 和 /index.html 文件，并返回第一个找到的文件。如果没有找到，那么 servlet 容器将继续执行默认行为，通常是显示 HTTP 404 错误页面。请注意，这也适用于子文件夹，例如，如果请求 /foo 文件夹，那么它将搜索 /foo/index.xhtml 和 /foo/index.html 文件，并返回第一个找到的文件。您可以在 web.xml 文件中指定欢迎文件。

A specified welcome file must not have a leading slash (/) as it is interpreted independently of the requested folder.
指定的欢迎文件不能有前导斜线 ( / ) ，因为它的解释与所请求的文件夹无关。

When an error occurs during execution of a web application, you can have the application display a specific error page according to the type of error. In particular, you can specify a mapping between the status code returned in an HTTP response or a Java programming language exception returned by any web component and any type of error page. You specify error pages in the web.xml file.
当网络应用程序在执行过程中发生错误时，可以让应用程序根据错误类型显示特定的错误页面。特别是，您可以指定 HTTP 响应中返回的状态代码或任何网络组件返回的 Java 编程语言异常与任何类型的错误页面之间的映射。您可以在 web.xml 文件中指定错误页面。

A specified location must have a leading slash (/) as it is interpreted as an absolute path within the context of the web application deployment. The error page being placed in /WEB-INF folder is not technically required, but it is the best practice as it will prevent the client from being able to request or even bookmark them individually.
指定的位置必须有前导斜线（ / ），因为在网络应用程序部署的上下文中，它被解释为绝对路径。技术上并不要求将错误页面放在 /WEB-INF 文件夹中，但这是最好的做法，因为这样可以防止客户端单独请求或甚至将它们添加到书签中。

If your web application uses external resources, such as data sources or mail sessions, then you can specify it in web.xml and use the @javax.annotation.Resource annotation to inject it into a container-managed object of your web application.
如果您的网络应用程序使用外部资源，如数据源或邮件会话，那么您可以在 web.xml 中指定它，并使用 @javax.annotation.Resource 注解将它注入到网络应用程序的容器管理对象中。

The @Resource annotation can be specified on a class, a method, or a field. The container is responsible for instantiating and injecting references to resources declared by the @Resource annotation in container-managed objects and mapping it to the proper JNDI resources.
@Resource 注解可以在一个类、一个方法或一个字段上指定。容器负责实例化和注入对容器管理对象中由 @Resource 注解声明的资源的引用，并将其映射到适当的 JNDI 资源。

Container-managed objects are primarily those objects which you do not explicitly instantiate yourself as in new ContainerManagedObject() but basically let the container do. For example CDI managed beans in case of a CDI container, and web components in case of a servlet container. CDI managed beans are recognizable as classes having a CDI scope annotation such as @RequestScoped or @Dependent. Web components are recognizable as classes that extend or implement a class or interface of the jakarta.servlet. package, and are registered via an annotation of the jakarta.servlet.annotation. package or an entry in the web.xml file.
容器管理对象主要是指那些您不需要像 new ContainerManagedObject() 中那样显式地实例化自己的对象，而是基本上让容器来实例化的对象。例如，CDI 容器中的 CDI 托管 Bean 和 servlet 容器中的 Web 组件。CDI 托管豆可以识别为具有 CDI 作用域注解（如 @RequestScoped 或 @Dependent ）的类。网络组件可识别为扩展或实现 jakarta.servlet. 包的类或接口的类，并通过 jakarta.servlet.annotation. 包的注解或 web.xml 文件中的条目进行注册。