From f8024dfe5c339f1fa8b57eac9b0e632533252bf5 Mon Sep 17 00:00:00 2001 From: Matej Novotny Date: Fri, 19 Apr 2024 13:46:31 +0200 Subject: [PATCH] WELD-2771 Prune documentation of removed JSF examples, update text for JSF numberguess example --- .../src/main/asciidoc/gettingstarted.asciidoc | 130 ++----- .../src/main/asciidoc/intro.asciidoc | 40 +- .../src/main/asciidoc/part2.asciidoc | 17 +- .../src/main/asciidoc/weldexamples.asciidoc | 359 ++++-------------- 4 files changed, 132 insertions(+), 414 deletions(-) diff --git a/docs/reference/src/main/asciidoc/gettingstarted.asciidoc b/docs/reference/src/main/asciidoc/gettingstarted.asciidoc index af3e3484901..850079dda56 100644 --- a/docs/reference/src/main/asciidoc/gettingstarted.asciidoc +++ b/docs/reference/src/main/asciidoc/gettingstarted.asciidoc @@ -5,16 +5,13 @@ endif::[] [[gettingstarted]] == Getting started with Weld -Weld comes with a number of examples. We recommend you start with -`examples/jsf/numberguess` and `examples/jsf/translator`. Numberguess is -a web (war) example containing only non-transactional managed beans. +Weld comes with several numberguess examples in various flavors based on what environment you use. +In its classic variant, it is a web (war) example containing only non-transactional managed beans. This example can be run on a wide range of servers, including WildFly, GlassFish, Apache Tomcat, Jetty, and any compliant -Jakarta EE 10 container. Translator is an enterprise (ear) example that -contains session beans. This example must be run on WildFly 27 or better, -GlassFish 7 or better, or any compliant Jakarta EE 10 container. +Jakarta EE container. -Both examples use JSF 4.0.0 as the web framework and, as such, can be +The example uses JSF as the web framework and, as such, can be found in the `examples/jsf` directory of the Weld distribution. === Prerequisites @@ -25,16 +22,18 @@ following: * the latest release of Weld, which contains the examples * Maven 3, to build and deploy the examples * optionally, a supported runtime environment (minimum versions shown) -** WildFly 27, -** GlassFish 7 or better, -** Apache Tomcat 10.1 or better (war example only), or -** Jetty 11 or better (war example only) +** WildFly, +** GlassFish, +** Apache Tomcat, or +** Jetty + +Note that the version of these runtimes need to target the same Jakarta EE version that Weld does. In the next few sections, you'll be using the Maven command (`mvn`) to invoke the Maven project file in each example to compile, assemble and deploy the example to WildFly and, for the war example, Apache Tomcat. -You can also deploy the generated artifact (war or ear) to any other -container that supports Jakarta EE 10, such as GlassFish 7. +You can also deploy the generated artifact (war) to any other +container that supports Jakarta EE, such as GlassFish. The sections below cover the steps for deploying with Maven in detail. @@ -48,15 +47,13 @@ $> cd examples/jsf/numberguess $> mvn wildfly:run ------------------------------ -The https://docs.jboss.org/wildfly/plugins/maven/latest/[Maven WildFly plugin] will run WildFly and deploy the example and the server will be automatically downloaded in the `target` directory. +The https://docs.wildfly.org/wildfly-maven-plugin/[Maven WildFly plugin] will run WildFly and deploy the example and the server will be automatically downloaded in the `target` directory. The numberguess application is available at http://localhost:8080/weld-numberguess. === Deploying to WildFly -To deploy the examples to a WildFly instance, you'll need to download -http://wildfly.org/downloads/[WildFly] first. The good -news is that there are no additional modifications you have to make to -the server. It's ready to go! +To deploy the examples to your own WildFly instance, you'll need to download https://www.wildfly.org/downloads/[WildFly] first. +The good news is that there are no additional modifications you have to make to the server. It's ready to go! After you have downloaded WildFly, extract it. You can move the extracted folder anywhere you like. Wherever it lays to rest, that's what we'll call the WildFly @@ -64,8 +61,8 @@ installation directory, or `JBOSS_HOME`. [source, console] -------------------------------- -$> unzip wildfly-27.x.y.Final.zip -$> mv wildfly-27.*/ wildfly-27 +$> unzip wildfly-31.x.y.Final.zip +$> mv wildfly-31.*/ wildfly-31 -------------------------------- In order for the build scripts to know where to deploy the example, you @@ -75,13 +72,21 @@ e.g.: [source, console] ------------------------------------- -$> export JBOSS_HOME=/path/to/wildfly-27 +$> export JBOSS_HOME=/path/to/wildfly-31 ------------------------------------- +Next up, start your WildFly server. +Assuming default configuration and Linux, you can do that with the following command (for Windows, use the `.bat` file instead): + +[source, console] +-------------------------------- +$> cd path/to/wildfly +$> ./bin/standalone.sh +-------------------------------- + You're now ready to run your first example! -Switch to the `examples/jsf/numberguess` directory and execute the Maven -`deploy` target: +Switch to the `examples/jsf/numberguess` directory in Weld repository and execute the Maven `deploy` target: [source, console] ------------------------------ @@ -89,15 +94,7 @@ $> cd examples/jsf/numberguess $> mvn wildfly:deploy ------------------------------ -NOTE: If you are using Eclipse, you should seriously consider installing the -http://tools.jboss.org[JBoss Tools] add-ons, which include a wide -variety of tooling for CDI and Jakarta EE development, as well as an -enhanced WildFly server view. - -Wait a few seconds for the application to deploy (or the application -server to start) and see if you can determine the most efficient -approach to pinpoint the random number at the local URL -http://localhost:8080/weld-numberguess. +Wait a bit for the application to deploy and see if you can determine the most efficient approach to pinpoint the random number at the local URL http://localhost:8080/weld-numberguess. [NOTE] ==== @@ -116,12 +113,13 @@ https://docs.wildfly.org/wildfly-maven-plugin/[plugin documentation]. ==== -You can also run functional tests to verify that the example works as -expected. Run: +TODO this ain't true!!! + +You can also run some simple integration tests to verify that the example works as expected. Keep the server with deployed application running and execute the following: [source, console] -------------------------------------------- -$> mvn verify -Darquillian=wildfly-managed +$> mvn verify -Pintegration-testing -------------------------------------------- You should see the following output: @@ -131,64 +129,6 @@ You should see the following output: Tests run: 2, Failures: 0, Errors: 0, Skipped: 0 ------------------------------------------------ -The second starter example, `weld-translator`, will translate your text -into Latin. (Well, not really, but the stub is there for you to -implement, at least. Good luck!) To try it out, switch to the translator -example directory and execute the deploy target: - -[source, console] ---------------------------------- -$> cd examples/jsf/translator/ear -$> mvn wildfly:run ---------------------------------- - -NOTE: The translator uses session beans, which are packaged in an EJB module -within an ear. Java EE 8 allows session beans to be deployed in war -modules, but that's a topic for a later chapter. - -Again, wait a few seconds for the application to deploy (if you're -really bored, read the log messages), and visit -http://localhost:8080/weld-translator to begin pseudo-translating. - -Again, functional tests can be running by executing: - -[source, console] --------------------------------------------- -$> cd examples/jsf/translator/ftest -$> mvn verify -Darquillian=wildfly-managed --------------------------------------------- - -=== Deploying to GlassFish - -Deploying to GlassFish should be easy and familiar, right? After all, -it's the Jakarta EE compatible implementation and Weld is the CDI -compatible implementation, meaning Weld gets bundled with GlassFish. So -yes, it's all quite easy and familiar. - -To deploy the examples to GlassFish, you'll need a GlassFish 7 release. Extract -the zip to a directory of your choice and set the `GLASSFISH_HOME` environment -variable. Switch to the `GLASSFISH_HOME` directory and start the server: - -[source, console] ----------------------------------- -$> ./bin/asadmin start-domain ----------------------------------- - -Now you can deploy the example. - -[source, console] ------------------------------- -$> ./bin/asadmin deploy /path/examples/jsf/numberguess/target/weld-numberguess.war ------------------------------- - -Once the command completes the application is available at -http://localhost:8080/weld-numberguess - -The reason the same artifact can be deployed to both WildFly and -GlassFish, without any modifications, is because all of the features -being used are part of the standard platform. And what a capable -platform it has become! - === Deploying to Apache Tomcat Servlet containers are not required to support Jakarta EE services like @@ -213,7 +153,7 @@ for more info). Let's give the Weld servlet extension a spin on Apache Tomcat. First, you'll need to download Tomcat 10.1 or later from -https://tomcat.apache.org/download-10.cgi[tomcat.apache.org] and extract +https://tomcat.apache.org/[tomcat.apache.org] and extract it. [source, console] @@ -240,7 +180,7 @@ a Windows command window: [source, console] ------------------------------------ -$> cd c:\path\to\apache-tomcat-9\bin +$> cd c:\path\to\apache-tomcat-10\bin $> start ------------------------------------ diff --git a/docs/reference/src/main/asciidoc/intro.asciidoc b/docs/reference/src/main/asciidoc/intro.asciidoc index 4cbdd783e51..3f3fbac9d98 100644 --- a/docs/reference/src/main/asciidoc/intro.asciidoc +++ b/docs/reference/src/main/asciidoc/intro.asciidoc @@ -16,42 +16,16 @@ to actually use them to build an application! A bean is exactly what you think it is. Only now, it has a true identity in the container environment. -Prior to Java EE 6, there was no clear definition of the term "bean" in -the Java EE platform. Of course, we've been calling Java classes used in -web and enterprise applications "beans" for years. There were even a -couple of different kinds of things called "beans" in EE specifications, -including EJB beans and JSF managed beans. Meanwhile, other third-party -frameworks such as Spring and Seam introduced their own ideas of what it -meant to be a "bean". What we've been missing is a common definition. - -Java EE 6 finally laid down that common definition in the Managed Beans -specification. Managed Beans are defined as container-managed objects -with minimal programming restrictions, otherwise known by the acronym -POJO (Plain Old Java Object). They support a small set of basic -services, such as resource injection, lifecycle callbacks and -interceptors. Companion specifications, such as EJB and CDI, build on -this basic model. But, _at last_, there's a uniform concept of a bean -and a lightweight component model that's aligned across the Java EE -platform. +Starting with Java EE 6 (now Jakarta) there was a common definition of beans through Managed Beans specification. Managed Beans were defined as container-managed objects with minimal programming restrictions, otherwise known by the acronym POJO (Plain Old Java Object). They support a small set of basic services, such as resource injection, lifecycle callbacks and interceptors. CDI/Weld builds on this basic model and clearly defines a uniform concept of a bean and a lightweight component model that's aligned across the Jakarta EE platform, MicroProfile specification and more. With very few exceptions, almost every concrete Java class that has a constructor with no parameters (or a constructor designated with the -annotation `@Inject`) is a bean. This includes every JavaBean and every -EJB session bean. If you've already got some JavaBeans or session beans -lying around, they're already beans—you won't need any additional -special metadata. - -The JavaBeans and EJBs you've been writing every day, up until now, have -not been able to take advantage of the new services defined by the CDI -specification. But you'll be able to use every one of them with -CDI—allowing the container to create and destroy instances of your beans -and associate them with a designated context, injecting them into other -beans, using them in EL expressions, specializing them with qualifier -annotations, even adding interceptors and decorators to them—without -modifying your existing code. At most, you'll need to add some -annotations. - -Now let's see how to create your first bean that actually uses CDI. +annotation `@Inject`) is a bean; including EJB sessions beans. If you've already got some session beans lying around, they're already beans—you won't need any additional special metadata. + +CDI container manages the lifecycle of your beans from creation to destruction. It also controls their association to designated context, injection into beans, bean availability in EL expressions, interception and decoration, specialization with qualifiers and more. +Many of these functionalities are working automatically, for some you may need to add an annotation or two. + +But enough talking, let's see how to create your first bean that actually uses CDI. === Getting our feet wet diff --git a/docs/reference/src/main/asciidoc/part2.asciidoc b/docs/reference/src/main/asciidoc/part2.asciidoc index 32e243993c5..20b02529b1e 100644 --- a/docs/reference/src/main/asciidoc/part2.asciidoc +++ b/docs/reference/src/main/asciidoc/part2.asciidoc @@ -5,20 +5,23 @@ endif::[] [[part-2]] = Getting Start with Weld, the CDI Reference Implementation -Weld, the CDI Reference Implementation (RI), can be downloaded from the +Weld, the CDI Compatible Implementation, can be downloaded from the http://weld.cdi-spec.org/download[download page]. Information about the -Weld source code repository and instructions about how to obtain and +Weld https://github.com/weld[source code repository] and instructions about how to obtain and build the source can be found on the same page. -Weld provides a complete SPI allowing Java EE containers such as +Weld provides a complete SPI allowing Jakarta EE containers such as WildFly, GlassFish and WebLogic to use Weld as their built-in CDI implementation. Weld also runs in servlet engines like Tomcat and Jetty, or even in a plain Java SE environment. -Weld comes with an extensive library of examples, which are a great -starting point from which to learn CDI. In addition, a number of -quickstarts featuring CDI can be found at the -http://www.jboss.org/developer/quickstarts.html[JBoss Developer site] +Weld comes with several examples showing various possible usages: + +* A full blow Jakarta EE server (WildFly) +* Servlets such as Tomcat or Jetty +* Standalone Java SE application + +Many more Jakarta EE examples can be seen in quickstarts of Jakarta EE servers. A good repository to browse would be https://github.com/wildfly/quickstart[WildFly Quickstarts] as it shows many more Jakarta-world technologies smoothly integrating with CDI/Weld. include::gettingstarted.asciidoc[] diff --git a/docs/reference/src/main/asciidoc/weldexamples.asciidoc b/docs/reference/src/main/asciidoc/weldexamples.asciidoc index d7729d984f9..0244f5997d5 100644 --- a/docs/reference/src/main/asciidoc/weldexamples.asciidoc +++ b/docs/reference/src/main/asciidoc/weldexamples.asciidoc @@ -21,102 +21,114 @@ examining the configuration files. All the configuration files for this example are located in `WEB-INF/`, which can be found in the `src/main/webapp` directory of the example. -First, we have the JSF 2.2 version of `faces-config.xml`. A standardized -version of Facelets is the default view handler in JSF 2.2, so there's +First, we have the JSF 4.0 version of `faces-config.xml`. A standardized +version of Facelets is the default view handler in JSF, so there's really nothing that we have to configure. Thus, the configuration consists of only the root element. [source.XML, xml] ------------------------------------------------------------------ - - - numberguess - + ------------------------------------------------------------------ There's also an empty `beans.xml` file, which tells the container to look for beans in this archive and to activate the CDI services. -Finally, some of the supported servers also need a `web.xml` which is -located in `src/main/webapp-[server]/WEB-INF`. +Finally, some supported servers also need a `web.xml` which is located in `src/main/webapp-[server]/WEB-INF`. -NOTE: This demo uses JSF 2 as the view framework, but you can use Weld with -any servlet-based web framework, such as JSF 1.2 or Wicket. +NOTE: This demo uses JSF as the view framework, but you can use Weld with any servlet-based web framework. + +TODO continue here Let's take a look at the main JSF view, `src/main/webapp/home.xhtml`. [source.XML, xml] ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> - - - -

Guess a number...

- -
- - - -
- -
- I'm thinking of a number between - #{game.smallest} - and #{game.biggest}. - You have #{game.remainingGuesses} guesses remaining. -
- -
- Your guess: - - -
-
- -
- - - + xmlns:ui="jakarta.faces.facelets" + xmlns:h="jakarta.faces.html" + xmlns:f="jakarta.faces.core"> + + + + numberguess + + + +
+

Guess a number...

+ + + +
+ + + +
+ + +
+ I'm thinking of a number between #{game.smallest} and #{game.biggest}. You have + #{game.remainingGuesses} guesses remaining. +
+ + + +
+ Your guess: + + +
+
+ +
+ + +
+ +
+ + ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -<1> Facelets is the built-in templating language for JSF. Here we are -wrapping our page in a template which defines the layout. - -<2> There are a number of messages which can be sent to the user, "Higher!", +<1> There are a number of messages which can be sent to the user, "Higher!", "Lower!" and "Correct!" -<3> As the user guesses, the range of numbers they can guess gets smaller - +<2> As the user guesses, the range of numbers they can guess gets smaller - this sentence changes to make sure they know the number range of a valid guess. -<4> This input field is bound to a bean property using a value expression. +<3> This input field is bound to a bean property using a value expression. -<5> A validator binding is used to make sure the user doesn't accidentally +<4> A validator binding is used to make sure the user doesn't accidentally input a number outside of the range in which they can guess - if the validator wasn't here, the user might use up a guess on an out of bounds number. -<6> And, of course, there must be a way for the user to send their guess to +<5> And, of course, there must be a way for the user to send their guess to the server. Here we bind to an action method on the bean. -The example consists of 4 classes, the first two of which are -qualifiers. First, there is the `@Random` qualifier, used for injecting -a random number: +The example consists of 4 classes, two of which are qualifiers. +First, there is the `@Random` qualifier, used for injecting a random number: [source.JAVA, java] -------------------------------------------- @@ -185,7 +197,7 @@ retrieving a random number from the `@Random You'll notice that we've also added the `@Named` annotation to this class. This annotation is only required when you want to make the bean -accessible to a JSF view via EL (i.e., #\{game}). +accessible to a JSF view via EL (i.e., `#\{game}`). [source.JAVA, java] ------------------------------------------------------------------------------------------------- @@ -298,12 +310,11 @@ does not provide the CDI services. For your convenience we provide a single jar suitable for running Weld in any servlet container (including Jetty), `weld-servlet-shaded`. -NOTE: You must also include the jars for JSF, EL, and the common annotations, -all of which are provided by the Java EE platform (a Java EE application server). +NOTE: You must also include the jars for JSF, EL, and the common annotations, all of which are provided by the Java EE platform (a Jakarta EE application server). Second, we need to explicitly specify the servlet listener in `web.xml`, again because the container isn't doing this stuff for you. The servlet -listener boots Weld and controls it's interaction with requests. +listener boots Weld and controls its interaction with requests. [source.XML, xml] ------------------------------------------------------------------------------- @@ -684,8 +695,7 @@ public class NumberGuessFrame extends javax.swing.JFrame { <3> This application is started in the prescribed Weld SE way, by observing the `ContainerInitialized` event. -<4> This method initializes all of the Swing components. Note the use of the -`msgGenerator` here. +<4> This method initializes all the Swing components. Note the use of the `msgGenerator` here. <5> `guessButtonActionPerformed` is called when the 'Guess' button is clicked, and it does the following: @@ -706,216 +716,7 @@ guesses). game, refreshes the messages in the UI and sets the button's label based on the game state. -=== The translator example in depth - -The translator example will take any sentences you enter, and translate -them to Latin. (Well, not really, but the stub is there for you to -implement, at least. Good luck!) - -The translator example is built as an EAR and contains EJBs. As a -result, it's structure is more complex than the numberguess example. - -NOTE: Java EE 7, which bundles EJB 3.2, allows you to package EJBs in a WAR, -which will make this structure much simpler! Still, there are other -advantages of using an EAR. - -First, let's take a look at the EAR aggregator project, which is located -in the example's `ear` directory. Maven automatically generates the -`application.xml` for us from this plugin configuration: - -[source.XML, xml] ---------------------------------------------------------------------- - - org.apache.maven.plugins - maven-ear-plugin - - - - org.jboss.weld.examples.jsf.translator - weld-jsf-translator-war - /weld-translator - - - - ---------------------------------------------------------------------- - -This configuration overrides the web context path, resulting in this -application URL: http://localhost:8080/weld-translator. - -[NOTE] -==== - -If you weren't using Maven to generate these files, you would need -`META-INF/application.xml`: - -[source.XML, xml] ------------------------------------------------------------------- - - - weld-jsf-translator-ear - The Weld JSF translator example (ear) - - - - weld-translator.war - /weld-translator - - - - weld-translator.jar - - ------------------------------------------------------------------- -==== - -Next, let's look at the WAR, which is located in the example's `war` -directory. Just as in the numberguess example, we have a -`faces-config.xml` for JSF 2.2 and a `web.xml` (to activate JSF) under -WEB-INF, both sourced from `src/main/webapp/WEB-INF`. - -More interesting is the JSF view used to translate text. Just as in the -numberguess example we have a template, which surrounds the form -(omitted here for brevity): - -[source.XML, xml] ------------------------------------------------------------------------------------------------------- - - - - - - - - - - - -
- Your text - - Translation -
- - - -
-
- -
- - ------------------------------------------------------------------------------------------------------- - -The user can enter some text in the left-hand text area, and hit the -translate button to see the result to the right. - -Finally, let's look at the EJB module, which is located in the example's -`ejb` directory. In `src/main/resources/META-INF` there is just an empty -`beans.xml`, used to mark the archive as containing beans. - -NOTE: The `beans.xml` file is no longer required for CDI enablement as of CDI -1.1. CDI is automatically enabled for archives which don't contain -`beans.xml` but contain one or more bean classes with a _bean defining -annotation_, as described in section -ifndef::generate-index-link[<<_implicit_bean_archive>>] -ifdef::generate-index-link[link:ee.html#_implicit_bean_archive[Implicit bean archive]] -. - -We've saved the most interesting bit for last, the code! The project has -two simple beans, `SentenceParser` and `TextTranslator` and two session -beans, `TranslatorControllerBean` and `SentenceTranslator`. You should -be getting quite familiar with what a bean looks like by now, so we'll -just highlight the most interesting bits here. - -Both `SentenceParser` and `TextTranslator` are dependent beans, and -`TextTranslator` uses constructor injection: - -[source.JAVA, java] ------------------------------------------------------------------- -public class TextTranslator implements Serializable { - - private SentenceParser sentenceParser; - - @EJB private Translator translator; - - @Inject public TextTranslator(SentenceParser sentenceParser) { - this.sentenceParser = sentenceParser; - } - - public String translate(String text) { - StringBuilder sb = new StringBuilder(); - for (String sentence: sentenceParser.parse(text)) { - sb.append(translator.translate(sentence)).append(". "); - } - return sb.toString().trim(); - } - -} ------------------------------------------------------------------- - -`TextTranslator` uses the simple bean (really just a plain Java class!) -`SentenceParser` to parse the sentence and then calls on the stateless -bean with the local business interface `Translator` to perform the -translation. That's where the magic happens. Of course, we couldn't -develop a full translator, but it's convincing enough to anyone who -doesn't understand Latin! - -[source.JAVA, java] --------------------------------------------------------- -@Stateless -public class SentenceTranslator implements Translator { - - public String translate(String sentence) { - return "Lorem ipsum dolor sit amet"; - } - -} --------------------------------------------------------- - -Finally, there is UI orientated controller. This is a request scoped, -named, stateful session bean, which injects the translator. It collects -the text from the user and dispatches it to the translator. The bean -also has getters and setters for all the fields on the page. - -[source.JAVA, java] ------------------------------------------------------------------------ -@Stateful -@RequestScoped -@Named("translator") -public class TranslatorControllerBean implements TranslatorController { - - @Inject private TextTranslator translator; - - private String inputText; - - private String translatedText; - - public void translate() { - translatedText = translator.translate(inputText); - } - - public String getText() { - return inputText; - } - - public void setText(String text) { - this.inputText = text; - } - - public String getTranslatedText() { - return translatedText; - } - - @Remove public void remove() {} - -} ------------------------------------------------------------------------ - That concludes our short tour of the Weld starter examples. For more information on Weld, please visit http://weld.cdi-spec.org/. + +If you want to browse more Jakarta EE examples which leverage CDI technologies, there is a fair amount of them among https://github.com/wildfly/quickstart[WildFly Quickstarts].