Tutorial: Your first RESTful web service

Create a new Java Enterprise project

IntelliJ IDEA includes a dedicated wizard for creating Java Enterprise projects based on various Java EE and Jakarta EE implementations. In this tutorial, we will create a simple web application.

1. From the main menu, select File | New | Project.

2. In the New Project dialog, select Java Enterprise.

   

   For this tutorial, use Java 1.8 as the project SDK and select the REST service template. Don't select or add an application server, we will do it later. Select Maven and JUnit. Click Next to continue.

3. In the Dependencies list, you can see that the web application template includes only the JAX-RS and Servlet frameworks under Specifications. Click Next.

4. Enter a name for your project: RestGlassfishHelloWorldRestTomcatHelloWorld. Then click Finish.

IntelliJ IDEA creates the default project structure.

Explore the default project structure

IntelliJ IDEA creates a project with some boilerplate code that you can build and deploy successfully.

• pom.xml is the Project Object Model with Maven configuration information, including dependencies and plugins necessary for building the project.

  <?xml version="1.0" encoding="UTF-8"?> <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>RestGlassfishHelloWorld</artifactId> <version>1.0-SNAPSHOT</version> <name>RestGlassfishHelloWorld</name> <packaging>war</packaging> <properties> <maven.compiler.target>1.8</maven.compiler.target> <maven.compiler.source>1.8</maven.compiler.source> <junit.version>5.7.0</junit.version> </properties> <dependencies> <dependency> <groupId>javax.ws.rs</groupId> <artifactId>javax.ws.rs-api</artifactId> <version>2.1.1</version> <scope>provided</scope> </dependency> <dependency> <groupId>javax.servlet</groupId> <artifactId>javax.servlet-api</artifactId> <version>4.0.1</version> <scope>provided</scope> </dependency> <dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter-api</artifactId> <version>${junit.version}</version> <scope>test</scope> </dependency> <dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter-engine</artifactId> <version>${junit.version}</version> <scope>test</scope> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-war-plugin</artifactId> <version>3.3.0</version> </plugin> </plugins> </build> </project>
  <?xml version="1.0" encoding="UTF-8"?> <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>RestTomcatHelloWorld</artifactId> <version>1.0-SNAPSHOT</version> <name>RestTomcatHelloWorld</name> <packaging>war</packaging> <properties> <maven.compiler.target>1.8</maven.compiler.target> <maven.compiler.source>1.8</maven.compiler.source> <junit.version>5.7.0</junit.version> </properties> <dependencies> <dependency> <groupId>javax.ws.rs</groupId> <artifactId>javax.ws.rs-api</artifactId> <version>2.1.1</version> <scope>provided</scope> </dependency> <dependency> <groupId>javax.servlet</groupId> <artifactId>javax.servlet-api</artifactId> <version>4.0.1</version> <scope>provided</scope> </dependency> <dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter-api</artifactId> <version>${junit.version}</version> <scope>test</scope> </dependency> <dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter-engine</artifactId> <version>${junit.version}</version> <scope>test</scope> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-war-plugin</artifactId> <version>3.3.0</version> </plugin> </plugins> </build> </project>

• The HelloResource class is a root resource class, which uses the following JAX-RS annotations to implement the RESTful web service:

  • The @Path annotation identifies the URI for accessing this resource, relative to the application root.

  • The @GET annotation indicates that the hello() method will process HTTP GET requests to the specified URI.

  • The @Produces annotation specifies the MIME media type that the method produces and returns.

  package com.example.RestGlassfishHelloWorld; import javax.ws.rs.GET; import javax.ws.rs.Path; import javax.ws.rs.Produces; @Path("/hello-world") public class HelloResource { @GET @Produces("text/plain") public String hello() { return "Hello, World!"; } }
  package com.example.RestTomcatHelloWorld; import javax.ws.rs.GET; import javax.ws.rs.Path; import javax.ws.rs.Produces; @Path("/hello-world") public class HelloResource { @GET @Produces("text/plain") public String hello() { return "Hello, World!"; } }

• The HelloApplication class is a subclass of javax.ws.rs.core.Application, which is used to configure the environment where the application runs REST resources defined in your resource classes. The @ApplicationPath annotation identifies the URL mapping for the application.

  package com.example.RestGlassfishHelloWorld; import javax.ws.rs.ApplicationPath; import javax.ws.rs.core.Application; @ApplicationPath("/") public class HelloApplication extends Application { }
  package com.example.RestTomcatHelloWorld; import javax.ws.rs.ApplicationPath; import javax.ws.rs.core.Application; @ApplicationPath("/") public class HelloApplication extends Application { }

Use the Project tool window to browse and open files in your project or press Ctrl+Shift+N and type the name of the file.

Configure the application server

Let IntelliJ IDEA know where the GlassFishTomcat application server is located.

1. In the Settings/Preferences dialog Ctrl+Alt+S, select Build, Execution, Deployment | Application Servers.

2. Click and select Glassfish ServerTomcatTomcat Server.

3. Specify the path to the GlassFishTomcat server install location. IntelliJ IDEA detects and sets the name and version appropriately.

   

   

Create a run configuration

IntelliJ IDEA needs a run configuration to build the artifacts and deploy them to your application server.

1. From the main menu, select Run | Edit Configurations.

2. In the Run/Debug Configurations dialog, click , expand the Glassfish ServerTomcat Server node, and select Local.

3. Fix any warnings that appear at the bottom of the run configuration settings dialog.

   

   Most likely, you will need to fix the following:

   • On the Server tab, set the Server Domain to domain1.

   • On the Deployment tab, add the artifact that you want to deploy: RestGlassfishHelloWorld:war exploded RestTomcatHelloWorld:war exploded

4. On the Server tab, set the URL to point to the root resource http://localhost:8080/RestGlassfishHelloWorld-1.0-SNAPSHOT/hello-world http://localhost:8080/RestTomcatHelloWorld_war_exploded/hello-world and save the run configuration.

   

   

5. To run the configuration, press Alt+Shift+F10 and select the created application server configuration.

   Alternatively, if you have your run configuration selected in the main toolbar at the top, you can press Shift+F10 to run it.

This run configuration builds the artifacts, then starts the GlassFishTomcat server, and deploys the artifacts to the server. You should see the corresponding output in the Run tool window.

Once this is done, it opens the specified URL in your web browser.