Skip to content

Commit 7b87cb3

Browse files
OndroMihOndroMih
committed
Documentation for the plugin and a test case
1 parent e5fd779 commit 7b87cb3

File tree

4 files changed

+352
-2
lines changed

4 files changed

+352
-2
lines changed

‎README.md‎

Lines changed: 258 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,259 @@
1-
Pre-requisite
1+
# Maven Embedded GlassFish Plugin
22

3-
To build this project, JDK 11 is required.
3+
A Maven plugin for managing Embedded GlassFish server instances during the build lifecycle.
4+
5+
## Quick Start
6+
7+
Run your project's main artifact on Embedded GlassFish directly from command line without modifying your `pom.xml`:
8+
9+
```bash
10+
mvn org.glassfish.embedded:embedded-glassfish-maven-plugin:7.1-SNAPSHOT:run -DglassfishVersion=7.0.25
11+
```
12+
13+
Or add the plugin to your `pom.xml`:
14+
15+
```xml
16+
<plugin>
17+
<groupId>org.glassfish.embedded</groupId>
18+
<artifactId>embedded-glassfish-maven-plugin</artifactId>
19+
<version>7.1-SNAPSHOT</version>
20+
<configuration>
21+
<glassfishVersion>7.0.25</glassfishVersion>
22+
</configuration>
23+
</plugin>
24+
```
25+
26+
Start the server with your application and wait until it stops:
27+
```bash
28+
mvn embedded-glassfish:run
29+
```
30+
31+
## Prerequisites
32+
33+
- JDK 11 or higher
34+
- Maven 3.6.3 or higher
35+
36+
## Basic Usage
37+
38+
### Command Line
39+
40+
Start server in background:
41+
```bash
42+
mvn embedded-glassfish:start
43+
```
44+
45+
Deploy application:
46+
```bash
47+
mvn embedded-glassfish:deploy
48+
```
49+
50+
Stop server:
51+
```bash
52+
mvn embedded-glassfish:stop
53+
```
54+
55+
### Integration Testing
56+
57+
```xml
58+
<plugin>
59+
<groupId>org.glassfish.embedded</groupId>
60+
<artifactId>embedded-glassfish-maven-plugin</artifactId>
61+
<version>7.1-SNAPSHOT</version>
62+
<executions>
63+
<execution>
64+
<id>start-server</id>
65+
<phase>pre-integration-test</phase>
66+
<goals>
67+
<goal>start</goal>
68+
<goal>deploy</goal>
69+
</goals>
70+
</execution>
71+
<execution>
72+
<id>stop-server</id>
73+
<phase>post-integration-test</phase>
74+
<goals>
75+
<goal>undeploy</goal>
76+
<goal>stop</goal>
77+
</goals>
78+
</execution>
79+
</executions>
80+
</plugin>
81+
```
82+
83+
## Goals Overview
84+
85+
| Goal | Description | Default Phase |
86+
|------|-------------|---------------|
87+
| [`start`](#start) | Starts an Embedded GlassFish server | pre-integration-test |
88+
| [`stop`](#stop) | Stops the Embedded GlassFish server | post-integration-test |
89+
| [`deploy`](#deploy) | Deploys an application to the server | pre-integration-test |
90+
| [`undeploy`](#undeploy) | Undeploys an application from the server | post-integration-test |
91+
| [`run`](#run) | Starts server and keeps it running | none |
92+
| [`admin`](#admin) | Executes admin commands | none |
93+
94+
## Configuration
95+
96+
### Basic Configuration
97+
98+
```xml
99+
<plugin>
100+
<groupId>org.glassfish.embedded</groupId>
101+
<artifactId>embedded-glassfish-maven-plugin</artifactId>
102+
<version>7.1-SNAPSHOT</version>
103+
<configuration>
104+
<port>8080</port>
105+
<app>${project.build.directory}/${project.build.finalName}.war</app>
106+
</configuration>
107+
</plugin>
108+
```
109+
110+
- `port` - HTTP port number for the server (default: 8080)
111+
- `app` - Path to the application artifact to deploy (default: main artifact)
112+
113+
### Automatic Artifact Deployment
114+
115+
The plugin automatically detects and deploys your project's main artifact without requiring explicit configuration:
116+
117+
```xml
118+
<plugin>
119+
<groupId>org.glassfish.embedded</groupId>
120+
<artifactId>embedded-glassfish-maven-plugin</artifactId>
121+
<version>7.1-SNAPSHOT</version>
122+
<configuration>
123+
<!-- Main artifact automatically deployed if no <app> parameter specified -->
124+
</configuration>
125+
</plugin>
126+
```
127+
128+
**Note:** Currently assumes WAR packaging. For other artifact types, specify the `app` parameter explicitly.
129+
130+
### Admin Commands
131+
132+
Execute administrative commands on the running server:
133+
134+
```xml
135+
<plugin>
136+
<groupId>org.glassfish.embedded</groupId>
137+
<artifactId>embedded-glassfish-maven-plugin</artifactId>
138+
<version>7.1-SNAPSHOT</version>
139+
<configuration>
140+
<commands>
141+
<command>set configs.config.server-config.network-config.protocols.protocol.http-listener.http.websockets-support-enabled=true</command>
142+
<command>create-jdbc-resource --connectionpoolid mypool jdbc/myresource</command>
143+
</commands>
144+
</configuration>
145+
</plugin>
146+
```
147+
148+
Command line usage:
149+
```bash
150+
mvn embedded-glassfish:admin -Dcommands="set server.monitoring-service.module-monitoring-levels.web-container=HIGH"
151+
```
152+
153+
## Configuration Reference
154+
155+
### Server Configuration
156+
- `configFile` - Custom domain configuration file
157+
- `glassfishVersion` - GlassFish version to use
158+
- `port` - HTTP port number (default: 8080)
159+
- `ports` - Map of port configurations
160+
- `serverID` - Server identifier (default: "maven")
161+
162+
### Application Deployment
163+
- `app` - Path to application artifact to deploy (defaults to `${project.build.directory}/${project.build.finalName}.war`)
164+
- `contextRoot` - Application context root
165+
- `name` - Application name (default: "myapp")
166+
167+
### Advanced Configuration
168+
- `bootstrapProperties` - Bootstrap properties
169+
- `glassfishProperties` - GlassFish server properties
170+
- `instanceRoot` - Server instance root directory
171+
172+
## Goal Reference
173+
174+
### start
175+
Starts an Embedded GlassFish server with the configured parameters.
176+
177+
**Default Phase:** pre-integration-test
178+
179+
**Configuration:**
180+
- Uses all server configuration parameters (serverID, port, glassfishProperties, etc.)
181+
182+
**Example:**
183+
```bash
184+
mvn embedded-glassfish:start
185+
```
186+
187+
### stop
188+
Stops the Embedded GlassFish server and cleans up resources.
189+
190+
**Default Phase:** post-integration-test
191+
192+
**Configuration:**
193+
- `serverID` - Server identifier to stop (default: "maven")
194+
195+
**Example:**
196+
```bash
197+
mvn embedded-glassfish:stop
198+
```
199+
200+
### deploy
201+
Deploys an application to the running Embedded GlassFish server.
202+
203+
**Default Phase:** pre-integration-test
204+
205+
**Configuration:**
206+
- `app` - Application path (auto-detects if not specified)
207+
- `name` - Application name (default: "myapp")
208+
- `contextRoot` - Web application context root
209+
- `deploymentParams` - Additional deployment parameters
210+
211+
**Example:**
212+
```bash
213+
mvn embedded-glassfish:deploy -Dapp=target/myapp.war
214+
```
215+
216+
### undeploy
217+
Undeploys an application from the Embedded GlassFish server.
218+
219+
**Default Phase:** post-integration-test
220+
221+
**Configuration:**
222+
- `name` - Application name to undeploy (default: "myapp")
223+
- `undeploymentParams` - Additional undeployment parameters
224+
225+
**Example:**
226+
```bash
227+
mvn embedded-glassfish:undeploy -Dname=myapp
228+
```
229+
230+
### run
231+
Starts the server, deploys applications, and runs interactively. Allows redeployment by pressing Enter or exit by typing 'X'.
232+
233+
**Default Phase:** none (manual execution)
234+
235+
**Configuration:**
236+
- Combines all server and deployment configurations
237+
- Executes all configured admin and deploy goals
238+
239+
**Example:**
240+
```bash
241+
mvn embedded-glassfish:run
242+
```
243+
244+
### admin
245+
Executes administrative commands on the running server.
246+
247+
**Default Phase:** pre-integration-test
248+
249+
**Configuration:**
250+
- `commands` - Array of admin commands to execute
251+
252+
**Example:**
253+
```bash
254+
mvn embedded-glassfish:admin -Dcommands="create-jdbc-resource --connectionpoolid mypool jdbc/myresource"
255+
```
256+
257+
## License
258+
259+
Eclipse Public License v. 2.0

‎src/it/start-admin-commands/invoker.properties‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
#
2+
# Copyright (c) 2022, 2023 Contributors to Eclipse Foundation. All rights reserved.
3+
#
4+
# This program and the accompanying materials are made available under the
5+
# terms of the Eclipse Public License v. 2.0, which is available at
6+
# http://www.eclipse.org/legal/epl-2.0.
7+
#
8+
# This Source Code may also be made available under the following Secondary
9+
# Licenses when the conditions for such availability set forth in the
10+
# Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
11+
# version 2 with the GNU Classpath Exception, which is available at
12+
# https://www.gnu.org/software/classpath/license.html.
13+
#
14+
# SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
15+
#
16+
17+
invoker.goals=test
18+

‎src/it/start-admin-commands/pom.xml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
<?xml version="1.0"?>
2+
<!--
3+
4+
Copyright (c) 2022, 2023 Contributors to Eclipse Foundation. All rights reserved.
5+
6+
This program and the accompanying materials are made available under the
7+
terms of the Eclipse Public License v. 2.0, which is available at
8+
http://www.eclipse.org/legal/epl-2.0.
9+
10+
This Source Code may also be made available under the following Secondary
11+
Licenses when the conditions for such availability set forth in the
12+
Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
13+
version 2 with the GNU Classpath Exception, which is available at
14+
https://www.gnu.org/software/classpath/license.html.
15+
16+
SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
17+
18+
-->
19+
<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">
20+
<modelVersion>4.0.0</modelVersion>
21+
22+
<groupId>org.glassfish.embedded.embedded-glassfish-maven-plugin.its</groupId>
23+
<artifactId>start</artifactId>
24+
<version>@project.version@</version>
25+
<packaging>pom</packaging>
26+
27+
<build>
28+
<plugins>
29+
<plugin>
30+
<groupId>org.glassfish.embedded</groupId>
31+
<artifactId>embedded-glassfish-maven-plugin</artifactId>
32+
<version>@project.version@</version>
33+
<executions>
34+
<execution>
35+
<phase>test</phase>
36+
<goals>
37+
<goal>start</goal>
38+
<goal>admin</goal>
39+
<goal>stop</goal>
40+
</goals>
41+
<configuration>
42+
<port>8081</port>
43+
<commands>
44+
<command>set configs.config.server-config.network-config.protocols.protocol.http-listener.http.websockets-support-enabled=true</command>
45+
<command>set configs.config.server-config.thread-pools.thread-pool.http-thread-pool.max-thread-pool-size=200</command>
46+
</commands>
47+
</configuration>
48+
</execution>
49+
</executions>
50+
</plugin>
51+
</plugins>
52+
</build>
53+
</project>

‎src/it/start-admin-commands/postbuild.groovy‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
/*
2+
Copyright (c) 2022, 2023 Contributors to Eclipse Foundation. All rights reserved.
3+
4+
This program and the accompanying materials are made available under the
5+
terms of the Eclipse Public License v. 2.0, which is available at
6+
http://www.eclipse.org/legal/epl-2.0.
7+
8+
This Source Code may also be made available under the following Secondary
9+
Licenses when the conditions for such availability set forth in the
10+
Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
11+
version 2 with the GNU Classpath Exception, which is available at
12+
https://www.gnu.org/software/classpath/license.html.
13+
14+
SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
15+
*/
16+
17+
String [] buildLog = new File(basedir, 'build.log')
18+
19+
startedLines = buildLog.grep(~/^INFO: Ran command.*SUCCESS.*/)
20+
21+
assert startedLines.size() == 2: 'Expected messages about running admin commands in build log'
22+
true
23+

0 commit comments

Comments
 (0)