Adding services to a server

• What you need

• 1. Create a service file

• 2. Add a blog service to server

• 3. Add the Documentation service

• 4. Run the server and services

• 5. Check DocService page

  • Using DocService after adding service methods

• What's next?

In this step, we'll add an empty blog service to the server we created in Step 1. Create a server. Also, we'll add Armeria's Documentation service for testing our blog service.

What you need

You need to have the following file obtained from previous steps. You can always download the full version, instead of creating one yourself.

• Main.java

1. Create a service file

Create a service file, BlogService.java. You can see the full version of the file here. We'll add on service methods in this class in later steps.

package example.armeria.server.blog;

import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

public final class BlogService {
  private final Map<Integer, BlogPost> blogPosts = new ConcurrentHashMap<>();
}

2. Add a blog service to server

In Step 1. Create a server, we added a dummy service just to check that a server is launched. Now, let's remove the dummy service and add an empty blog service, instead.

1. From Main.java, remove the dummy service at line 4.
   Main.java

   1static Server newServer(int port) {
   2  ...
   3  return sb.http(port)
   4           .service("/", (ctx, req) -> HttpResponse.of("Hello, Armeria!")) // Remove this
   5           .build();

2. Add our service by adding line 4.
   Main.java

   1static Server newServer(int port) {
   2  ...
   3  return sb.http(port)
   4           .annotatedService(new BlogService())   // Add this
   5           .build();
   6}

3. Add the Documentation service

This time, we'll add Armeria's Documentation service:

1. In the newServer() method, add a DocService and a request example for creating blog posts, using DocServiceBuilder.exampleRequests(). Feel free to add more examples for other service methods.

   Main.java

   1import com.linecorp.armeria.server.docs.DocService;
   2
   3public final class Main {
   4  static Server newServer(int port) {
   5    ServerBuilder sb = Server.builder();
   6    DocService docService =
   7            DocService.builder()
   8                      .exampleRequests(BlogService.class,
   9                          "createBlogPost", // Name of service method
   10                          "{\"title\":\"My first blog\", \"content\":\"Hello Armeria!\"}")
   11                      .build();

2. Inside the newServer() method, add the DocService to our server builder.

   Main.java

   1static Server newServer(int port) {
   2  ...
   3  return sb.http(port)
   4           .annotatedService(new BlogService())
   5           .serviceUnder("/docs", docService)  // Add Documentation service
   6           .build();
   7}

3. (Optional) To access the Documentation service result easily, edit the log message we added in Step 1. Create a server to the one specified below.

   Main.java

   1public static void main(String[] args) throws Exception {
   2    logger.info("Server has been started. Serving DocService at http://127.0.0.1:{}/docs",
   3                server.activeLocalPort());
   4}

4. Run the server and services

Like we did in Step 1. Create a server, build and run the service by running the main() method or using Gradle.

The server and services are launched successfully if you see this message.

Server has been started. Serving DocService at http://127.0.0.1:8080/docs

5. Check DocService page

Let's test and call our service operations, using Armeria's Documentation service.

Click the URL http://127.0.0.1:8080/docs from the log message or open the URL on a web browser. If you see the Document service page, you've launched the DocService and server successfully. We're seeing no services on the page because we're to implement service methods.

Using DocService after adding service methods

When you add service methods through later steps, you'll see a result similar to this.

To test your service methods with the Documentation service:

1. Click the createBlogPost() method link in the left panel. You can make calls to the creation method from the page opened.

   

   Note that in the REQUEST BODY section that the values specified for the DocServiceBuilder are automatically entered on the page.

   Main.java

   1static Server newServer(int port) {
   2  ServerBuilder sb = Server.builder();
   3  DocService docService =
   4    DocService.builder()
   5              .exampleRequests(
   6                BlogService.class,
   7                "createBlogPost",
   8                "{\"title\":\"My first blog\",\"content\":\"Hello Armeria!\"}")
   9              .build();

2. Click the SUBMIT button, and you'll see the blog post information returned in the right panel.

   

What's next?

In this step, we've added an empty blog service and the Documentation service to a server.

Next, at Step 4. Implement CREATE, we'll finally implement a CREATE operation to create blog posts.