javaee / tutorial

The Java EE Tutorial

⚠️This project is now part of the EE4J initiative. This repository has been archived as all activities are now happening in the corresponding Eclipse repository. See here for the overall EE4J transition status.

---

Java EE Tutorial

This repository contains the source files that are used to build the Java Platform, Enterprise Edition (Java EE) 8 Tutorial. The source files are authored in AsciiDoc. AsciiDoc is similar to original markdown but is particularly suited for user documentation. This project also uses JBake. JBake is a static site generator that is inspired from Jekyll and written in Java. JBake uses templates for the structure of the page and the body of the page is generated from AsciiDoc content.

Note that the Java EE Tutorial code examples are located in the javaee/tutorial-examples repository.

Contributing

The easiest way to contribute is by opening an issue that contains feedback and review comments. All issues will be addressed as soon as possible.

The Java EE Tutorial project is also open for contributions and your help is greatly appreciated. If you have an idea for the tutorial and want to add a section or update an existing section, then review the following links:

• Contribute
• Pull Request Acceptance Workflow
• License

Building the Java EE Tutorial

The following directions explain how to do local builds of the tutorial. Note that any changes that are pushed to the master branch automatically trigger a build of the site files and tutorial sources. The results are automatically pushed to the gh-pages branch. You can view the published site at https://javaee.github.io/tutorial/.

Pre-Requisites

• Maven
• JDK8+

Note that manually deploying the site requires password-less authentication. This is done by exporting your SSH public key into your GitHub account.

Build the Site Locally

The site is generated under target/staging. Open file:///PATH_TO_PROJECT_DIR/target/staging in a browser to view the output.

mvn generate-resources

You can also invoke the JBake plugin directly:

mvn jbake:build

Rebuild the Site on Changes

The following command builds the site and, if kept running, detects changes to the sources and incrementally renders the site. This is convenient when writing content.

mvn jbake:watch

Serve the Site locally

If a web server is required (for example, absolute paths are used), you can use the following command to start a Jetty web server at http://localhost:8820. The command also watches for changes and rebuilds incrementally.

mvn jbake:serve

Deploy the Site to Github Pages

If you want to manually push a build to the gh-pages branch, use:

mvn deploy -Ppublish-site

Produce a Zip File for Download

To produce a zip file containing the generated HTML files, use:

mvn package

When making a release on GitHub, this zip file should be added to the release.

Links

• JBake maven plugin documentation
• JBake documentation
• Freemarker documentation
• AsciiDoc User Guide
• Asciidoctor quick reference

tutorial's Issues

Errata in packaging002

In packaging002.adoc, in the example, missing to add ".class" in StoreServlet

EL -> Value and Method Expressions

Hi,

in the section of EL Value and Method Expressions,

1. in the sub section: Object Properties or Collection Elements, it is written :

The following example references the first of the customer orders, assuming that customer.orders is a List:
${customer.orders[1]} but is the second

2. in the sub section: Parameterized Method Calls, it is written :

In the following example, which is a modified tag from the guessnumber application, a random number is provided as an argument rather than from user input to the method call:

<h:inputText value="#{userNumberBean.userNumber('5')}"> which does not work with properties!

Unable to build Duke's Forest case-study

Hi, when trying to build Duke's Forest case-study example in the tutorial, I got the same error explained in issue #130 (comment)
and solved it following the solution posted in StackOverflow (as mentioned in the issue), but then I got two more errors. I could resolve the first one, but not the other one.

The first one is the following:
Failed to execute goal org.codehaus.cargo:cargo-maven2-plugin:1.7.0:redeploy (deploy) on project dukes-payment: Execution deploy of goal org.codehaus.cargo:cargo-maven2-plugin:1.7.0:redeploy failed: GlassFish admin command with args (--interactive=false --host localhost --port 4848 --user admin --passwordfile F:\Desarrollo\JakartaEE\glassfish5\glassfish\domains\password.properties deploy --force --contextroot dukes-payment F:\Desarrollo\JakartaEE\glassfish5\docs\javaee-tutorial\examples\case-studies\dukes-forest\dukes-payment\target\dukes-payment.war) failed: asadmin exited 1 -> [Help 1]

server.log showed this:

Caused by: javax.naming.NameNotFoundException: ForestDataSource not found
    at com.sun.enterprise.naming.impl.TransientContext.doLookup(TransientContext.java:237)
    at com.sun.enterprise.naming.impl.TransientContext.lookup(TransientContext.java:204)
    at com.sun.enterprise.naming.impl.TransientContext.lookup(TransientContext.java:208)
    at com.sun.enterprise.naming.impl.SerialContextProviderImpl.lookup(SerialContextProviderImpl.java:66)
    at com.sun.enterprise.naming.impl.LocalSerialContextProviderImpl.lookup(LocalSerialContextProviderImpl.java:114)
    at com.sun.enterprise.naming.impl.SerialContext.lookup(SerialContext.java:478)
    ... 69 more

I had to add to web.xml in "dukes-payment" project the following config:

    <data-source>
        <name>java:global/ForestDataSource</name>
        <class-name>org.apache.derby.jdbc.ClientDataSource</class-name>
        <server-name>localhost</server-name>
        <port-number>1527</port-number>
        <database-name>forest</database-name>
        <user>forest</user>
        <password>app</password>
        <property>
            <name>connectionAttributes</name>
            <value>;create=true</value>
        </property>
    </data-source>

After that, "dukes-payment" project finally deployed, but then I got the second error. It is the following:
Failed to execute goal org.codehaus.cargo:cargo-maven2-plugin:1.7.0:redeploy (deploy) on project dukes-store: Execution deploy of goal org.codehaus.cargo:cargo-maven2-plugin:1.7.0:redeploy failed: GlassFish admin command with args (--interactive=false --host localhost --port 4848 --user admin --passwordfile F:\Desarrollo\JakartaEE\glassfish5\glassfish\domains\password.properties deploy --force --contextroot dukes-store F:\Desarrollo\JakartaEE\glassfish5\docs\javaee-tutorial\examples\case-studies\dukes-forest\dukes-store\target\dukes-store.war) failed: asadmin exited 1 -> [Help 1]

server.log shows this:

Grave:   enterprise.deployment.util.application.fail
Grave:   Exception while deploying the app [dukes-store]
Grave:   Exception during lifecycle processing
java.lang.IllegalStateException: Application validation fails for given application [dukes-store] for jndi-name [java:global/jms/OrderQueue]
	at com.sun.enterprise.deployment.util.ApplicationValidator.accept(ApplicationValidator.java:113)
	at com.sun.enterprise.deployment.BundleDescriptor.visit(BundleDescriptor.java:641)
	at com.sun.enterprise.deployment.archivist.ApplicationFactory.openWith(ApplicationFactory.java:235)
	at org.glassfish.javaee.core.deployment.DolProvider.processDOL(DolProvider.java:197)
	at org.glassfish.javaee.core.deployment.DolProvider.load(DolProvider.java:231)
	at org.glassfish.javaee.core.deployment.DolProvider.load(DolProvider.java:97)
	at com.sun.enterprise.v3.server.ApplicationLifecycle.loadDeployer(ApplicationLifecycle.java:881)
	at com.sun.enterprise.v3.server.ApplicationLifecycle.setupContainerInfos(ApplicationLifecycle.java:821)
	at com.sun.enterprise.v3.server.ApplicationLifecycle.deploy(ApplicationLifecycle.java:378)
	at com.sun.enterprise.v3.server.ApplicationLifecycle.deploy(ApplicationLifecycle.java:219)
	at org.glassfish.deployment.admin.DeployCommand.execute(DeployCommand.java:491)
	at com.sun.enterprise.v3.admin.CommandRunnerImpl$2$1.run(CommandRunnerImpl.java:540)
	at com.sun.enterprise.v3.admin.CommandRunnerImpl$2$1.run(CommandRunnerImpl.java:536)
	at java.security.AccessController.doPrivileged(Native Method)
	at javax.security.auth.Subject.doAs(Subject.java:360)
	at com.sun.enterprise.v3.admin.CommandRunnerImpl$2.execute(CommandRunnerImpl.java:535)
	at com.sun.enterprise.v3.admin.CommandRunnerImpl$3.run(CommandRunnerImpl.java:566)
	at com.sun.enterprise.v3.admin.CommandRunnerImpl$3.run(CommandRunnerImpl.java:558)
	at java.security.AccessController.doPrivileged(Native Method)
	at javax.security.auth.Subject.doAs(Subject.java:360)
	at com.sun.enterprise.v3.admin.CommandRunnerImpl.doCommand(CommandRunnerImpl.java:557)
	at com.sun.enterprise.v3.admin.CommandRunnerImpl.doCommand(CommandRunnerImpl.java:1465)
	at com.sun.enterprise.v3.admin.CommandRunnerImpl.access$1300(CommandRunnerImpl.java:110)
	at com.sun.enterprise.v3.admin.CommandRunnerImpl$ExecutionContext.execute(CommandRunnerImpl.java:1847)
	at com.sun.enterprise.v3.admin.CommandRunnerImpl$ExecutionContext.execute(CommandRunnerImpl.java:1723)
	at org.glassfish.admin.rest.resources.admin.CommandResource.executeCommand(CommandResource.java:408)
	at org.glassfish.admin.rest.resources.admin.CommandResource.execCommandSimpInMultOut(CommandResource.java:235)
	at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
	at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
	at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
	at java.lang.reflect.Method.invoke(Method.java:498)
	at org.glassfish.jersey.server.model.internal.ResourceMethodInvocationHandlerFactory.lambda$static$0(ResourceMethodInvocationHandlerFactory.java:76)
	at org.glassfish.jersey.server.model.internal.AbstractJavaResourceMethodDispatcher$1.run(AbstractJavaResourceMethodDispatcher.java:148)
	at org.glassfish.jersey.server.model.internal.AbstractJavaResourceMethodDispatcher.invoke(AbstractJavaResourceMethodDispatcher.java:191)
	at org.glassfish.jersey.server.model.internal.JavaResourceMethodDispatcherProvider$ResponseOutInvoker.doDispatch(JavaResourceMethodDispatcherProvider.java:200)
	at org.glassfish.jersey.server.model.internal.AbstractJavaResourceMethodDispatcher.dispatch(AbstractJavaResourceMethodDispatcher.java:103)
	at org.glassfish.jersey.server.model.ResourceMethodInvoker.invoke(ResourceMethodInvoker.java:493)
	at org.glassfish.jersey.server.model.ResourceMethodInvoker.apply(ResourceMethodInvoker.java:415)
	at org.glassfish.jersey.server.model.ResourceMethodInvoker.apply(ResourceMethodInvoker.java:104)
	at org.glassfish.jersey.server.ServerRuntime$1.run(ServerRuntime.java:277)
	at org.glassfish.jersey.internal.Errors$1.call(Errors.java:272)
	at org.glassfish.jersey.internal.Errors$1.call(Errors.java:268)
	at org.glassfish.jersey.internal.Errors.process(Errors.java:316)
	at org.glassfish.jersey.internal.Errors.process(Errors.java:298)
	at org.glassfish.jersey.internal.Errors.process(Errors.java:268)
	at org.glassfish.jersey.process.internal.RequestScope.runInScope(RequestScope.java:289)
	at org.glassfish.jersey.server.ServerRuntime.process(ServerRuntime.java:256)
	at org.glassfish.jersey.server.ApplicationHandler.handle(ApplicationHandler.java:703)
	at org.glassfish.jersey.grizzly2.httpserver.GrizzlyHttpContainer.service(GrizzlyHttpContainer.java:377)
	at org.glassfish.admin.rest.adapter.JerseyContainerCommandService$3.service(JerseyContainerCommandService.java:174)
	at org.glassfish.admin.rest.adapter.RestAdapter.service(RestAdapter.java:179)
	at com.sun.enterprise.v3.services.impl.ContainerMapper$HttpHandlerCallable.call(ContainerMapper.java:463)
	at com.sun.enterprise.v3.services.impl.ContainerMapper.service(ContainerMapper.java:168)
	at org.glassfish.grizzly.http.server.HttpHandler.runService(HttpHandler.java:206)
	at org.glassfish.grizzly.http.server.HttpHandler.doHandle(HttpHandler.java:180)
	at org.glassfish.grizzly.http.server.HttpServerFilter.handleRead(HttpServerFilter.java:242)
	at org.glassfish.grizzly.filterchain.ExecutorResolver$9.execute(ExecutorResolver.java:119)
	at org.glassfish.grizzly.filterchain.DefaultFilterChain.executeFilter(DefaultFilterChain.java:284)
	at org.glassfish.grizzly.filterchain.DefaultFilterChain.executeChainPart(DefaultFilterChain.java:201)
	at org.glassfish.grizzly.filterchain.DefaultFilterChain.execute(DefaultFilterChain.java:133)
	at org.glassfish.grizzly.filterchain.DefaultFilterChain.process(DefaultFilterChain.java:112)
	at org.glassfish.grizzly.ProcessorExecutor.execute(ProcessorExecutor.java:77)
	at org.glassfish.grizzly.nio.transport.TCPNIOTransport.fireIOEvent(TCPNIOTransport.java:539)
	at org.glassfish.grizzly.strategies.AbstractIOStrategy.fireIOEvent(AbstractIOStrategy.java:112)
	at org.glassfish.grizzly.strategies.WorkerThreadIOStrategy.run0(WorkerThreadIOStrategy.java:117)
	at org.glassfish.grizzly.strategies.WorkerThreadIOStrategy.access$100(WorkerThreadIOStrategy.java:56)
	at org.glassfish.grizzly.strategies.WorkerThreadIOStrategy$WorkerThreadRunnable.run(WorkerThreadIOStrategy.java:137)
	at org.glassfish.grizzly.threadpool.AbstractThreadPool$Worker.doWork(AbstractThreadPool.java:593)
	at org.glassfish.grizzly.threadpool.AbstractThreadPool$Worker.run(AbstractThreadPool.java:573)
	at java.lang.Thread.run(Thread.java:748)

Grave:   Exception while deploying the app [dukes-store] : Application validation fails for given application [dukes-store] for jndi-name [java:global/jms/OrderQueue]

Note: I'm using NetBeans 8.2, GlassFish 5 (included in Java EE 8 download zip) and JDK 1.8.0_191.

JSF-Adding Components to a Page Using HTML Tag Library Tags

Adding Components to a Page Using HTML Tag Library Tags

in the section: Laying Out Components with the h:panelGrid and h:panelGroup Tags, it's written:
The example h:panelGrid tag has only one cell of data (but it has 2), so an h:panelGroup tag is not needed.

Create an asciidoc index to generate a PDF

Since the current tutorial is currently composed of many distinct asciidoc documents, we cannot use the asciidoctor tool chain to generate a PDF.

We should create an index.adoc with include directives to all documents in order to create a single asciidoctor document that can be used to generate a PDF.

This file shouldn't be outside of src/main/jbake/content so that it's not included in the jbake output.

The asciidoctor maven plugin can be use to render the PDF, see https://github.com/asciidoctor/asciidoctor-maven-examples/tree/master/asciidoctor-pdf-example

Code in tutorial not found

Hello,

I am following this tutorial: https://javaee.github.io/tutorial/security-api005.html
I do not see the the folder for this example in the java_ee_sdk-8 folder like the other examples, well most of the examples. The web-page mentions this path: tut-install/examples/security/security-api/custom-identity-store but there is not a security-api folder in my java_ee_sdk-8 folder.

Also, it maybe helpful to note that the previous tutorial I was reading had the same problem (examples not found). The tutorial I am referring to is located here: https://javaee.github.io/tutorial/security-api004.html

Thank-you for reading this. I hope I did not run afoul of the "contributing guidelines". Feel free to modify and use this post as you would like.

translate this tutorial to others languages?

Has there been working to translate this tutorial to others languages?
I would be interested to translate to French (or at least start this project)

Syntax highlighting

It's great to see the tutorial soruces on AsciiDoc. I wonder if they could have syntax highlighting on code examples.

I saw code snippets are marked [source,oac_no_warn] (https://raw.githubusercontent.com/javaee/tutorial/238bb05e545cbba2e58ba9a039337fcc88de77e2/src/main/jbake/content/jsf-ajax011.adoc). Any reason for not specifying the actual language? Is it due to the import from FrameMaker?

Can we (the community) help in any way to get this for Java EE 8 release?

Unable to build locally

Local build is failing with below error -

Failed to execute goal com.blazebit:jbake-maven-plugin:1.0.0:build (default-cli) on project javaee-tutorial: Failure when running: org/apache/commons/lang3/ArrayUtils: org.apache.commons.lang3.ArrayUtils -> [Help 1]
[ERROR]

Unable to deploy

I'm try to learn Java EE 8, I have followed the official guide at https://javaee.github.io/tutorial/webapp003.html but I have this problem:

[DeployerRedeployMojo] Resolved container artifact org.codehaus.cargo:cargo-core-container-glassfish:jar:1.4.4 for container glassfish5x
------------------------------------------------------------------------
BUILD FAILURE
------------------------------------------------------------------------
Total time: 4.730s
Finished at: Mon Oct 09 16:16:40 CEST 2017
Final Memory: 18M/183M
------------------------------------------------------------------------
Failed to execute goal org.codehaus.cargo:cargo-maven2-plugin:1.4.4:redeploy (deploy) on project hello1: Execution deploy of goal org.codehaus.cargo:cargo-maven2-plugin:1.4.4:redeploy failed: Cannot create configuration. There's no registered configuration for the parameters (container [id = [glassfish5x], type = [installed]], configuration type [existing]). Actually there are no valid types registered for this configuration. Maybe you've made a mistake spelling it? -> [Help 1]

To see the full stack trace of the errors, re-run Maven with the -e switch.
Re-run Maven using the -X switch to enable full debug logging.

For more information about the errors and possible solutions, please read the following articles:
[Help 1] http://cwiki.apache.org/confluence/display/MAVEN/PluginExecutionException

This error is the same for glassfish 5 and 4.1.1. If I deploy manually the war package it's work; so I think the problem is the communication between maven and the glassfish server...
I get the same problem for NetBeans 8.2 and from command line.

Linking to fontawesome causes issue when browsing offline

Without internet connection, including link to fontawesome:

<script src="https://use.fontawesome.com/96c4d89611.js"></script>

makes navigation difficult as the pages is not rendered immediatelly.

Possible wrong technology versions in the Java EE Tutorial

Looks like the version of a few technologies in the Java EE Tutorial don't match the technology version described in the Java EE Overview.

For example, the tutorial mentions the following:

The Java EE 8 platform requires JavaMail 1.5.

The Java EE 8 platform requires Java Persistence API 2.1.

The Java EE 8 platform requires Java API for WebSocket 1.0.

Typo in pom.xml maven enforcer message

https://github.com/javaee/tutorial/blob/master/pom.xml#L80

The "or lower" clause is incorrect.

Navigation rules

Section link:

#{LoginForm.logon} should replaced by:

#{LoginForm.login}