The JVM Fanboy Blog 

WildFly & Nashorn part 1: Hello world!

by vincent


Posted on Thursday Sep 15, 2016 at 12:46AM in Nashorn


Red-Hat released version 10.1 of their WildFly application server recently.

WildFly is Red-Hat's open-source Java Enterprise Edition application server, which implements the Java EE 7 Full and Web Profile standards. This is a huge difference with the popular Apache TomCat server, which only implements the Servlet Container part of the Java EE specs (but, note that there's also the TomEE project, which makes TomCat a full Java EE application server. Likewise, I should also mention that there's a distribution of WildFly available that only implements the Servlet Container standard!)

As far as I can tell, version 10 of WildFly is not yet Java EE certified by Oracle. The last certified version seems to be WildFly 8. Still, it's definitely one of the more interesting application servers on the market, though.

Introducing Undertow and Undertow.js

Undertow is the name of the HTTP server that powers WildFly. It is a separate project written in Java and Java applications can embed it themselves. Noteworthy is that Undertow is implemented using NIO , the high-performance non-blocking I/O API that was introduced back in Java 7.

On top of Undertow runs Undertow.js, also a seperate project, which we will concentrate on in this article. Undertow.js makes many WildFly capabilities available to server-side JavaScript scripts that run on Oracle Nashorn.

Since WildFly is implemented using Undertow and comes with Undertow.js, getting server-side Nashorn server-side JavaScript scripts to work is a relatively easy process. Undertow.js offers some convenient wrappers around Java objects and therefore, sharing and using DataSource objects to query databases, retrieving and using Java objects, etc. couldn't be much easier. Also, since WildFly, in its developer-friendly standalone mode, automatically reloads modified Nashorn scripts, changes to scripts are active immediately.

WildFly 10.1 comes with undertow-js version 1.0.2.Final, released in February 2016, which is the version I will concentrate on. Note, there's a newer Beta version on GitHub though.

Let's do the Hello World example

I plan to do more parts in this series, where we will examine more exciting Undertow.js features and will write my own tutorial code. But for now, let's get started by creating the Hello World example that I "borrowed" from the Undertow.js docs.

Download and configure WildFly 10.1

I'll assume you will run WildFly for development purposes only, on the same machine as your Java development environment. As WildFly is complex software, I'll not describe configuring WildFly with security in mind. Do not run WildFly on a server without studying the Administrator Guide.

While WildFly has extended run modes, we will concentrate on the easy-to-use and developer-friendly Standalone-mode. In this mode we have just one instance of WidFly, that runs both the administration module and the applications.

  • From the official website download page, download the latest Java EE7 Full & Web Distribution.
  • Unzip the ZIP or TGZ file to a convenient location
  • Navigate to the "bin" subdirectory.
    On Windows machines, run "standalone.bat". On Linux, run "./standalone.sh"
    Windows screenshot of WildFly that is starting
  • If everything goes as planned, you'll see messages printed to the console with the URLs of the HTTP management interface and Administration Console.

    On my machine the Administration Console URL is http://127.0.0.1:9990.

    You should also see a message that the WildFly has been started.

  • Before you can access the Administration Console, we will have to create a user that can access it.
    • In a new terminal window (or Command Window on Windows), from the same "bin" subdirectory, run the add-user.bat (Windows) or ./add-user.sh (Linux) script.
    • When prompted, type "a" (Management User) and press enter
    • Enter your username you wish to use as login and press enter
    • Enter a password and press enter, try to follow the recommendations. If you don't, you will be reminded and asked if you are really sure to continue (don't blame them when your password is hacked!)
    • Re-enter password and press enter
    • Leave the groups list empty, just press enter
    • If you made no mistakes, answer "yes" and press enter when asked if entered info is correct
    • When asked if user is going to be used to connect to another process, enter "no" and press enter
    • Then press any key to continue. A user that can login to the Administrator panel will now have been created.
  • Now you should be able to log in to the Administrator console
    • In your favorite browser, enter the URL that is shown in the terminal window (the one that runs WildFly). This is probably "http://127.0.0.1:9990"
    • When prompted enter the username and password you chose in the previous step.
    • The Management page of the Administration Console should now appear.

Develop the server-side JavaScript code

  • I'll be using Oracle NetBeans to create a new Java Web > Web Application project called "undertowjs_test".

  • We won't be deploying to WildFly using NetBeans IDE (the reason will be explained later), so I just accepted my default TomCat server.
  • On the last screen, do not choose any framework and finish the wizard.
  • In your project's "Web Pages" folder, add a new JavaScript file "main.js"
  • Enter the following code:

    
    $undertow
        .onGet("/hello",
            {headers: {"content-type": "text/plain"}},
            [function ($exchange) {
                return "Hello World";
            }])
    
    

  • Some notes:

    • It creates the "/hello" endpoint and responds with a hardcoded plain text response when a HTTP GET request is received.
    • The "$undertow" object instance is created and made globally available automatically by undertow.js
    • The "$exchange" variable is not used in this example, but can be used to communicate with the server (do things like redirect, set HTTP response codes, retrieve cookies, read query parameters, etc. ). In the next part of this series I will more throughly describe it. For now take a look at the documentation if you want more information.
    • Like normal Java EE applications, endpoints are created relative to the application's context path. So in this case the endpoint will actually be "/undertowjs_test/hello"
  • Since WildFly can also serve JavaScript files for the browser, it can not know which JavaScript files are meant for the server-side Nashorn interpreter and which scripts will be served to the front-end. Therefore, you'll need to create a text file with a fixed filename to tell undertow.js which JavaScript files it should start server-side on server startup. To do this, in the Web Page's WEB-INF directory, create a new empty file and call it "undertow-scripts.conf"

  • Call the file "undertow-scripts.conf" and enter the following single line and save the file:

    
    main.js
    
    

    • Note: Since we stored main.js in the Web Pages directory, you do not need to add any path to the filename. Also note that scripts mentioned in this file are considered server-only JavaScript files. Download requests for these files will be refused.
  • Now let's build the WAR file

Deploy the WAR file to WildFly

  • Return to the browser, and in the WildFly Management start screen, click on the "Deployments" tab at the top of the screen. Then click the "Add" button.

  • In the dialog that appears, select "Upload new deployment" and click Next

  • A new dialog appears to select the WAR file. Click on "Choose File" and navigate to your NetBeans IDE "undertowjs_test" project' folder. In this directory, a "dist" subdirectory should exist where the "undertowjs_test.war" WAR file is stored. Select that file and click Next.

  • On the final screen, check the settings and click Finish. I'd recommend to keep the "Runtime name" the same as "Name".

  • If everything went well, a popup should appear for a short time telling the deployment was successful.
  • WildFly's http interface runs on 8080 at default. Now you should be able to visit the endpoint created by your Nashorn script. Visit "http://localhost:8080/undertowjs_test/hello"
  • Hopefully you'll get the "Hello World" message now

  • If you get a "Not Found" message instead, double-check you stored "undertow-scripts.conf" in the WEB-INF directory and that the file contains one line with " main.js". I've noticed WildFly will not produce errors when there are errros in undertow-scripts.conf file. If you detect an error, correct it, rebuild the project, on the WildFly Deployments tab, click "undertowjs_test" project and click on the arrow next to the name and choose "Replace", then try the URL again in the browser.

Override the server-side script directory

An interesting feature of WildFly, that I believe is only available when the server is running on Standalone mode, is that you can override the path where Undertow looks for the server-side script files.

This is very handy when developing the scripts. Since you can point WildFly to your project's workspace directory, you can immediately check changes after saving the file in NetBeans IDE (or any other editor). On each request, Undertow.js checks if the file has changed. If this is the case, the JavaScript file is automatically re-compiled by Nashorn and re-run immediately.

  • Create a new Empty File in the Web Pages' WEB-INF directory and call it "undertow-external-mounts.conf"
  • Enter the full path to your NetBeans project's "web" subdirectory of your project's source directory (the directory containing the "main.js" file.

    In my case on my Windows machine, it contains this:

    C:\Users\Vincent\Documents\NetBeansProjects\undertowjs_test\web
  • Re-build the WAR file and replace the deployment, see above for instructions on how to replace the previous deployment.
  • Now in NetBeans IDE, change the code a little bit and save the file. For instance, I've changed the message to a random quote from one of my all-time favorite B-movies:

    
    $undertow
        .onGet("/hello",
            {headers: {"content-type": "text/plain"}},
            [function ($exchange) {
                return "I am Torgo. I take care of the place while the Master is away.";
            }])
    

  • When refreshing the page in the browser, you should immediately see this change, without doing any re-deployment.

For the next part I will try to come up with more interesting examples that really demonstrate the power of undertow.js. I hope you agree WildFly is a very interesting server and its undertow.js component deserves much more attention.



No one has commented yet.
Comments are closed for this entry.