XPages to Java EE, Part 3: Hello, World

Mon Jan 21 14:31:00 EST 2019

Tags: javaee
  1. XPages to Java EE, Part 1: Overview
  2. XPages to Java EE, Part 2: Terminology
  3. XPages to Java EE, Part 3: Hello, World
  4. XPages to Java EE, Part 4: Application Servers
  5. XPages to Java EE, Part 5: Web Pages
  6. XPages to Java EE, Part 6: Dependencies
  7. XPages to Java EE, Part 7: MVC
  8. XPages to Java EE, Part 8: IDE Server Integration
  9. XPages to Java EE, Part 9: IDE Features Grab Bag
  10. XPages to Java EE, Part 10: Data Storage
  11. XPages to Java EE, Part 11: Mixing MVC and an API
  12. XPages to Java EE, Part 12: Container Authentication
  13. XPages to Java EE, Part 13: Why Do This, Anyway?

I expect that I'll have some more theory and explanation to get to in future posts, but I think it will be useful to run through a quick example project. Unlike with my XPages/OSGi examples, there won't be anything in this one that you wouldn't find in any old Java EE tutorial - indeed, I'll be piggybacking on some existing ones to speed things along.

Eclipse Setup

Strictly speaking, none of this tutorial requires Eclipse, so you can feel free to use IntelliJ (or the command line, or whatever), but most of us probably have Eclipse around at this point. The main thing you'll need is to ensure that you have the "Java EE"/"Enterprise Java" variant of Eclipse from their downloads page. That's been the go-to one for XPages library development all along, so you may already have it.

Additionally, you'll need at least Java 8 installed and configured. I think that recent Eclipse versions require that, so you should be fine there too.

Creating the Project

To create the project, go to File -> New -> Other..., and then chose "Maven Project":

Click Next >, and leave the following page at its defaults:

The next page asks about the "archetype" to use. In Maven terminology, an archetype is a template project that comes pre-populated with configuration information for a given project type. In our case, we'll add an archetype from outside the list - specifically, a quickstart project from Adam Bien, who is a great resource for Java EE knowledge.

To do this, click on Add Archetype... and fill in the Group Id "com.airhacks", the Artifact Id "javaee8-essentials-archetype", and Version "0.0.1":

Leave "Repository URL" blank, click OK, and then select the newly-added archetype on the original page:

After that, click Next >, which will bring you to a screen to provide Maven artifact details. Set the Group Name to "com.example" and the Artifact ID to "javaeetutorial". Leave the other fields as they are.

After that, click Finish. If all goes well, Eclipse will create the project and gussy it up with its Java EE support, resulting in a project that looks like this:

Adding a JAX-RS Resource

At this point, you have a Java EE project primed for use, but it doesn't really do anything yet. For a modern Java app, your most likely starting point is going to be JAX-RS, so we'll create an example service there. If you've created a Wink service for Domino before, this will be familiar, but slightly easier now that so much configuration is implied.

To start, expand the "Java Resources" node of the project, right-click the "src/main/resources" entry, and choose New -> Class:

Set the package to "com.example" and the class name to "HelloWorldResource". Leave everything else as-is and hit Finish:

Set the contents of the class to the following:

package com.example;

import javax.json.Json;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
import javax.ws.rs.core.MediaType;

@Path("helloworld")
public class HelloWorldResource {
	@GET
	@Produces(MediaType.APPLICATION_JSON)
	public String hello(@QueryParam("name") String name) {
		return Json.createObjectBuilder()
			.add("message", "Hello, " + name) //$NON-NLS-1$ //$NON-NLS-2$
			.build()
			.toString();
	}
}

This is pretty similar to the previous series's REST resource, but it removes the Domino references and switches from IBM Commons's JSON implementation to the relatively-new JSON-P standard. JSON-P and its companion spec JSON-B aim to bring some consistency to the world of JSON handling in Java, though their usage is far behind other implementations like Gson or Jackson. They're part of the Java EE spec, though, so they come "for free" with our project, and they're pretty good.

Running the App

At this point, we have enough to build a .war file out of the app and deploy it to a suitable app server, and that can be done a number of ways. The route we'll take for now is the Maven-focused route: providing enough configuration in the project's pom.xml to run on a chosen app server, in this case TomEE, the Java EE variant of Tomcat.

To accomplish this, open the project's pom.xml file and set its contents to:

<project xmlns="http://maven.apache.org/POM/4.0.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>com.example</groupId>
	<artifactId>javaeetutorial</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<packaging>war</packaging>
	<dependencies>
		<dependency>
			<groupId>javax</groupId>
			<artifactId>javaee-api</artifactId>
			<version>8.0</version>
			<scope>provided</scope>
		</dependency>
	</dependencies>
	<build>
		<finalName>javaeetutorial</finalName>
		<plugins>
			<plugin>
				<groupId>org.apache.tomee.maven</groupId>
				<artifactId>tomee-maven-plugin</artifactId>
				<version>8.0.0-M1</version>
				<configuration>
					<tomeeVersion>8.0.0-M1</tomeeVersion>
					<tomeeClassifier>plus</tomeeClassifier>
					<tomeeHttpPort>9091</tomeeHttpPort>
				</configuration>
			</plugin>
		</plugins>
	</build>
	<properties>
		<maven.compiler.source>1.8</maven.compiler.source>
		<maven.compiler.target>1.8</maven.compiler.target>
		<failOnMissingWebXml>false</failOnMissingWebXml>
	</properties>
</project>

Like before, there's a bit of "just paste in the XML" to Maven, but fortunately it's a much smaller bite than when we were dealing with OSGi. The addition here is to add the tomee-maven-plugin pointing to the current milestone release as of this writing.

Once you've saved this file, right-click the project in Eclipse and choose Run As -> Maven Build... (with the ellipsis):

In the resulting dialog, enter "install tomee:run" in the "Goals" field:

Click Run and let the build proceed. It will churn a bit, first compiling the project and then downloading the necessary components to run the server.

If all goes well, you should see a lot of chatter in Eclipse's output finishing (most likely) with a line about "Server startup". You should then be able to visit http://localhost:9091/javaeetutorial/resources/helloworld?name=World and see JSON output from the service:

Next Steps

At this point, you should have a working Java EE application using possibly the most important part of the stack. From here, we'll enter into the worlds of data storage, managed beans, and front-end UI toolkits.

Commenter Photo

Timothy Briley - Sun Jan 27 21:54:19 EST 2019

Jesse,

I think you might have skipped a step.

After this: "Leave "Repository URL" blank, click OK, and then select the newly-added archetype on the original page:"

You next have this: "After that, click Finish. If all goes well, Eclipse will create the project and gussy it up with its Java EE support, resulting in a project that looks like this:"

But finish isn't yet available. I believe you've skipped the dialog box where you give the project its GAV. It's been a while since I've done this, so it took me a while to figure out that "javaeetutorial in your screenshot comes from when you entered "javaeetutorial" as the artifact id in setting the GAV values.

Or is there something else I'm missing here?

Commenter Photo

Jesse Gallagher - Mon Jan 28 08:54:17 EST 2019

I sure did! I'll fix that up this morning.

New Comment