Skip to content

Commit

Permalink
Fixes #3935 - Move micro docs from website repository to docs directo…
Browse files Browse the repository at this point in the history 
…ry (#3936)
  • Loading branch information
@mnriem
mnriem committed Sep 14, 2024
1 parent 479bb39 commit 04db7f2
Show file tree
Hide file tree
Showing 4 changed files with 241 additions and 2 deletions.
4 changes: 2 additions & 2 deletions docs/src/site/markdown/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,8 +30,8 @@ distribution supports see our [Jakarta EE / Micro Profile matrix](https://piranh

* [Piranha Core Profile](coreprofile/index.html)
* [Piranha Embedded](embedded/index.html)
* [Piranha Servlet](https://piranha.cloud/servlet/index.html)
* [Piranha Server](https://piranha.cloud/server/index.html)
* [Piranha Servlet](servlet/index.html)
* [Piranha Server](server/index.html)
* [Piranha Web Profile](webprofile/index.html)

## Maven Plugin documentation
Expand Down
224 changes: 224 additions & 0 deletions docs/src/site/markdown/micro/create_a_hello_world_web_application.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,224 @@
# Create a Hello World web application

If you are looking to create a simple Hello World web application with Piranha
Micro to get started then you have come to the right place!

In 6 steps you will learn how to create the web application. They are:

1. Create the Maven POM file
1. Add the HelloWorldServlet.java file
1. Add the web.xml file
1. Add an integration test
1. Test the application
1. Deploy the application

## Create the Maven POM file

Create an empty directory to store your Maven project. Inside of that directory create the ```pom.xml``` file with the content as below.

```xml
<?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>cloud.piranha.guides.micro</groupId>
<artifactId>helloworld</artifactId>
<version>1-SNAPSHOT</version>
<packaging>war</packaging>
<name>Piranha Micro - Create a Hello World application</name>
<properties>
<piranha.distribution>micro</piranha.distribution>
<piranha.version>23.9.0</piranha.version>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<build>
<finalName>piranha-micro-helloworld</finalName>
<plugins>
<plugin>
<groupId>cloud.piranha.maven.plugins</groupId>
<artifactId>piranha-maven-plugin</artifactId>
<version>${piranha.version}</version>
<executions>
<execution>
<id>pre-integration-test</id>
<phase>pre-integration-test</phase>
<goals>
<goal>start</goal>
</goals>
</execution>
<execution>
<id>post-integration-test</id>
<phase>post-integration-test</phase>
<goals>
<goal>stop</goal>
</goals>
</execution>
</executions>
<configuration>
<distribution>${piranha.distribution}</distribution>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.10.1</version>
<configuration>
<release>17</release>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-failsafe-plugin</artifactId>
<version>3.0.0-M7</version>
<executions>
<execution>
<goals>
<goal>integration-test</goal>
<goal>verify</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-war-plugin</artifactId>
<version>3.3.2</version>
<configuration>
<failOnMissingWebXml>false</failOnMissingWebXml>
</configuration>
</plugin>
</plugins>
</build>
<dependencies>
<dependency>
<groupId>jakarta.platform</groupId>
<artifactId>jakarta.jakartaee-web-api</artifactId>
<version>10.0.0</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter</artifactId>
<version>5.9.1</version>
<scope>test</scope>
</dependency>
</dependencies>
</project>
```

## Add the Hello Servlet

Add the HelloWorldServlet.java file in the `src/main/java/helloworld` directory.

```java
package helloworld;

import java.io.IOException;
import java.io.PrintWriter;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServlet;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

public class HelloWorldServlet extends HttpServlet {

@Override
protected void doGet(HttpServletRequest request,
HttpServletResponse response) throws IOException, ServletException {
try (PrintWriter writer = response.getWriter()) {
response.setContentType("text/plain");
writer.println("Hello World!");
writer.flush();
}
}
}
```

## Add the web.xml file

Add the web.xml file to the `src/main/webapp/WEB-INF` directory.

```xml
<?xml version="1.0" encoding="UTF-8"?>

<web-app version="4.0" xmlns="http://xmlns.jcp.org/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd">
<servlet>
<servlet-name>HelloWorldServlet</servlet-name>
<servlet-class>helloworld.HelloWorldServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>HelloWorldServlet</servlet-name>
<url-pattern>/index.html</url-pattern>
</servlet-mapping>
<session-config>
<session-timeout>30</session-timeout>
</session-config>
</web-app>
```

## Add an integration test

As we want to make sure the application gets tested before we release an
integration test is added which will be executed as part of the build.

We'll add the integration test to the `src/test/java` directory.

```java
package helloworld;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import static org.junit.jupiter.api.Assertions.assertTrue;
import org.junit.jupiter.api.Test;

class HelloWorldIT {

@Test
void testHelloWorldHtml() throws Exception {
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest
.newBuilder(new URI("http://localhost:8080/helloworld/helloworld.html"))
.build();
HttpResponse<String> response = client.send(request, BodyHandlers.ofString());
assertTrue(response.body().contains("Hello World!"));
}
}
```

## Test the application

The application is setup to use JUnit to do integration testing using the
Piranha Maven plugin so when you are building the application it will also
execute an integration test validating the web application works.

To build and test the application execute the following command:

```bash
mvn install
```

## Deploy the application

To deploy your application you will need 2 pieces.

1. The Piranha Micro runtime JAR.
2. The WAR file you just produced.

For the WAR file see the `target` directory. For the Piranha Micro
distribution go to Maven Central. And then the following command line will
deploy your application:

```bash
java -jar piranha-dist-micro.jar --war-file helloworld.war
```

## Conclusion

As you can see getting started with Piranha Micro is straightforward!

8 changes: 8 additions & 0 deletions docs/src/site/markdown/micro/index.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# Piranha Micro

Piranha Micro is a distribution that bootstrap parts of itself using Maven
Central. Beyond that it delivers the same integration as Piranha Web Profile.

## Documentation

1. [Create a Hello World web application](create_a_hello_world_web_application.html)
7 changes: 7 additions & 0 deletions docs/src/site/site.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@
<links>
<item name="Core Profile" href="coreprofile/index.html" />
<item name="Embedded" href="embedded/index.html" />
<item name="Micro" href="micro/index.html" />
<item name="Server" href="server/index.html" />
<item name="Servlet" href="servlet/index.html" />
<item name="Web Profile" href="webprofile/index.html" />
Expand Down Expand Up @@ -43,6 +44,12 @@
<item name="Running Piranha Embedded with Spring Boot" href="embedded/running_piranha_embedded_with_spring_boot.html"/>
</item>
</menu>
<menu name="Piranha Micro">
<item name="Overview" href="micro/index.html"/>
<item name="Guides">
<item name="Create a Hello World web application" href="micro/create_a_hello_world_web_application.html"/>
</item>
</menu>
<menu name="Piranha Server">
<item name="Overview" href="server/index.html"/>
<item name="Guides">
Expand Down

0 comments on commit 04db7f2

Please sign in to comment.