Author: veithen
Date: Sat Sep 29 10:54:55 2012
New Revision: 1391779
URL: http://svn.apache.org/viewvc?rev=1391779&view=rev
Log:
Improved the usability of the foreground mode and added documentation.
Added:
axis/axis1/java/trunk/maven/maven-axis-server-plugin/src/site/apt/
axis/axis1/java/trunk/maven/maven-axis-server-plugin/src/site/apt/index.apt
axis/axis1/java/trunk/maven/maven-axis-server-plugin/src/site/apt/usage.apt.vm
Modified:
axis/axis1/java/trunk/maven/maven-axis-server-plugin/src/main/java/org/apache/axis/tools/maven/server/StartServerMojo.java
axis/axis1/java/trunk/maven/maven-axis-server-plugin/src/site/site.xml
Modified:
axis/axis1/java/trunk/maven/maven-axis-server-plugin/src/main/java/org/apache/axis/tools/maven/server/StartServerMojo.java
URL:
http://svn.apache.org/viewvc/axis/axis1/java/trunk/maven/maven-axis-server-plugin/src/main/java/org/apache/axis/tools/maven/server/StartServerMojo.java?rev=1391779&r1=1391778&r2=1391779&view=diff
==============================================================================
---
axis/axis1/java/trunk/maven/maven-axis-server-plugin/src/main/java/org/apache/axis/tools/maven/server/StartServerMojo.java
(original)
+++
axis/axis1/java/trunk/maven/maven-axis-server-plugin/src/main/java/org/apache/axis/tools/maven/server/StartServerMojo.java
Sat Sep 29 10:54:55 2012
@@ -91,17 +91,30 @@ public class StartServerMojo extends Abs
* server has been started and the services are deployed. This is useful
if one wants to
* manually test some services deployed on the server or if one wants to
run the integration
* tests from an IDE. The flag should only be set using the command line,
but not in the POM.
- * <p>
- * Note: this feature is implemented using a flag (instead of a distinct
goal) to make sure that
- * the server is configured in exactly the same way as in a normal
integration test execution.
*
* @parameter expression="${axis.server.foreground}" default-value="false"
*/
+ // Note: this feature is implemented using a flag (instead of a distinct
goal) to make sure that
+ // the server is configured in exactly the same way as in a normal
integration test execution.
private boolean foreground;
+ /**
+ * Specifies an alternate port number that will override {@link #port} if
{@link #foreground} is
+ * set to <code>true</code>. This parameter should be used if the port
number configured with
+ * the {@link #port} parameter is allocated dynamically. This makes it
easier to run integration
+ * tests from an IDE. For more information, see the <a
href="usage.html">usage
+ * documentation</a>.
+ *
+ * @parameter
+ */
+ private int foregroundPort = -1;
+
protected void doExecute() throws MojoExecutionException,
MojoFailureException {
Log log = getLog();
+ // Determine the port to be used
+ int actualPort = foreground && foregroundPort != -1 ? foregroundPort :
port;
+
// Select WSDD files
List deployments = new ArrayList();
List undeployments = new ArrayList();
@@ -149,7 +162,7 @@ public class StartServerMojo extends Abs
}
// Prepare a work directory where the server can create a
server-config.wsdd file
- File workDir = new File(workDirBase, String.valueOf(port));
+ File workDir = new File(workDirBase, String.valueOf(actualPort));
if (workDir.exists()) {
try {
FileUtils.deleteDirectory(workDir);
@@ -182,7 +195,7 @@ public class StartServerMojo extends Abs
// Start the server
List args = new ArrayList();
args.add("-p");
- args.add(String.valueOf(port));
+ args.add(String.valueOf(actualPort));
args.add("-w");
args.add(workDir.getAbsolutePath());
if (jwsDirs != null && jwsDirs.length > 0) {
@@ -191,13 +204,13 @@ public class StartServerMojo extends Abs
}
try {
AdminClient adminClient = new AdminClient(true);
- adminClient.setTargetEndpointAddress(new URL("http://localhost:"; +
port + "/axis/services/AdminService"));
+ adminClient.setTargetEndpointAddress(new URL("http://localhost:"; +
actualPort + "/axis/services/AdminService"));
startJavaProcess(
- "Server on port " + port,
+ "Server on port " + actualPort,
"org.apache.axis.server.standalone.StandaloneAxisServer",
(String[])args.toArray(new String[args.size()]),
workDir,
- new AxisServerStartAction(port, adminClient,
+ new AxisServerStartAction(actualPort, adminClient,
(File[])deployments.toArray(new
File[deployments.size()]),
isDebug() || foreground ? Integer.MAX_VALUE :
20000),
new AxisServerStopAction(adminClient,
@@ -207,6 +220,7 @@ public class StartServerMojo extends Abs
}
if (foreground) {
+ log.info("Server started in foreground mode. Press CRTL-C to
stop.");
Object lock = new Object();
synchronized (lock) {
try {
Added:
axis/axis1/java/trunk/maven/maven-axis-server-plugin/src/site/apt/index.apt
URL:
http://svn.apache.org/viewvc/axis/axis1/java/trunk/maven/maven-axis-server-plugin/src/site/apt/index.apt?rev=1391779&view=auto
==============================================================================
--- axis/axis1/java/trunk/maven/maven-axis-server-plugin/src/site/apt/index.apt
(added)
+++ axis/axis1/java/trunk/maven/maven-axis-server-plugin/src/site/apt/index.apt
Sat Sep 29 10:54:55 2012
@@ -0,0 +1,38 @@
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+ ------------
+ Introduction
+ ------------
+
+maven-axis-server-plugin
+
+ The purpose of the maven-axis-server-plugin is to automatically start and
stop a stand-alone Axis server (and other processes)
+ during integration test phases of a Maven project. This enables end-to-end
automation of integration tests.
+
+* Goals Overview
+
+ The plugin has the following goals:
+
+ * {{{./start-server-mojo.html}axis-server:start-server}} starts a
stand-alone Axis server instance in a separate JVM during
+ the <<<pre-integration-test>>> phase. It also deploys Web services on that
instance.
+
+ * {{{./start-process-mojo.html}axis-server:start-process}} starts an
arbitrary process during the <<<pre-integration-test>>>
+ phase. This can e.g. be used to start a mock Web service.
+
+ * {{{./stop-all-mojo.html}axis-server:stop-all}} stops all processes started
by <<<axis-server:start-server>>> and
+ <<<axis-server:start-process>>>. It is executed during the
<<<post-integration-test>>> phase.
\ No newline at end of file
Added:
axis/axis1/java/trunk/maven/maven-axis-server-plugin/src/site/apt/usage.apt.vm
URL:
http://svn.apache.org/viewvc/axis/axis1/java/trunk/maven/maven-axis-server-plugin/src/site/apt/usage.apt.vm?rev=1391779&view=auto
==============================================================================
---
axis/axis1/java/trunk/maven/maven-axis-server-plugin/src/site/apt/usage.apt.vm
(added)
+++
axis/axis1/java/trunk/maven/maven-axis-server-plugin/src/site/apt/usage.apt.vm
Sat Sep 29 10:54:55 2012
@@ -0,0 +1,238 @@
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+ -----
+ Usage
+ -----
+
+Usage
+
+* Automating tests that require a running Axis server instance
+
+ Test that require a running Axis server instance should be executed in the
+ <<<integration-test>>> phase instead of the <<<test>>> phase. That means that
+ you need to configure an execution of the
{{{http://maven.apache.org/plugins/maven-failsafe-plugin}maven-failsafe-plugin}}
+ (we'll see that later) and prevent the
{{{http://maven.apache.org/plugins/maven-surefire-plugin}maven-surefire-plugin}}
+ from executing these tests in the <<<test>>> phase. There are several ways
+ this can be done. One is to follow the naming convention recommended by
+ the maven-failsafe-plugin, i.e. to ensure that all integration test cases
+ match one of the following patterns: <<<IT*.java>>>, <<<*IT.java>>> or
<<<*ITCase.java>>>.
+ The other option is to completely skip the execution of
+ the maven-surefire-plugin plugin. To do this, add the following configuration
+ to your POM:
+
+--------------------------------------------------------------------------------
+ <plugin>
+ <artifactId>maven-surefire-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>default-test</id>
+ <configuration>
+ <skip>true</skip>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+--------------------------------------------------------------------------------
+
+ The Axis server needs to listen on a TCP port to receive HTTP requests.
+ When using a continuous integration tool, it is important to ensure that
builds
+ (of different projects or different branches of the same project) can be
+ executed concurrently on the same host without interfering with each other.
+ That implies that one should avoid hard coded port numbers and instead
allocate
+ ports dynamically during the build.
+ The <<<reserve-network-port>>> goal of the
+
{{{http://mojo.codehaus.org/build-helper-maven-plugin/}build-helper-maven-plugin}}
+ provides the necessary feature to achieve this:
+
+--------------------------------------------------------------------------------
+ <plugin>
+ <groupId>org.codehaus.mojo</groupId>
+ <artifactId>build-helper-maven-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>reserve-network-port</id>
+ <goals>
+ <goal>reserve-network-port</goal>
+ </goals>
+ <phase>pre-integration-test</phase>
+ <configuration>
+ <portNames>
+ <portName>axisServerPort</portName>
+ </portNames>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+--------------------------------------------------------------------------------
+
+ This execution will allocate a TCP port and store the port number in the
+ <<<axisServerPort>>> property for later use. We are now ready to configure
+ the Axis server instance:
+
+--------------------------------------------------------------------------------
+ <plugin>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>maven-axis-server-plugin</artifactId>
+ <version>${project.version}</version>
+ <executions>
+ <execution>
+ <id>start-server</id>
+ <goals>
+ <goal>start-server</goal>
+ </goals>
+ <configuration>
+ <port>${axisServerPort}</port>
+ <wsdds>
+ <wsdd>
+
<directory>${project.build.directory}/wsdd</directory>
+ </wsdd>
+ </wsdds>
+ </configuration>
+ </execution>
+ <execution>
+ <id>stop-server</id>
+ <goals>
+ <goal>stop-all</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+--------------------------------------------------------------------------------
+
+ Note the reference to the <<<axisServerPort>>> property set by the
build-helper-maven-plugin.
+ Also note the <<<wsdds>>> option that specifies the location of the WSDD
files for the
+ Web services to deploy. These files are typically generated using the
+ {{{../wsdl2java/index.html}maven-wsdl2java-plugin}}.
+
+ The maven-axis-server-plugin assumes that
<<<org.apache.axis.server.standalone.StandaloneAxisServer>>> class
+ (not to be confused with the old
<<<org.apache.axis.transport.http.SimpleAxisServer>>> class)
+ is in the class path. Therefore, you need to add the relevant dependency to
your project:
+
+--------------------------------------------------------------------------------
+ <dependency>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>axis-standalone-server</artifactId>
+ <version>${project.version}</version>
+ <scope>test</scope>
+ </dependency>
+--------------------------------------------------------------------------------
+
+ Obviously the integration tests also need to know the port number of the
+ Axis server. The easiest way is to provide that information using a system
+ property, as shown in the following sample configuration for the
maven-failsafe-plugin:
+
+--------------------------------------------------------------------------------
+ <plugin>
+ <artifactId>maven-failsafe-plugin</artifactId>
+ <executions>
+ <execution>
+ <goals>
+ <goal>integration-test</goal>
+ <goal>verify</goal>
+ </goals>
+ <configuration>
+ <includes>
+ <include>**/*Test.java</include>
+ </includes>
+ <systemPropertyVariables>
+
<axisServerPort>${axisServerPort}</axisServerPort>
+ </systemPropertyVariables>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+--------------------------------------------------------------------------------
+
+* Running integration tests manually in an IDE
+
+ The approach described in the previous section is designed to automatically
execute
+ integration tests during the Maven build. However, from time to time you may
want
+ to execute some of these tests manually in your favorite IDE, for debugging
purposes or to
+ develop new test cases. With most modern IDEs, running a test case is easy;
the tricky part is
+ to start the Axis server instance with which these test cases will interact.
+ Obviously you could set up the Axis server manually, but this is time
consuming
+ and doesn't allow you to leverage all the effort you put into setting up your
+ Maven project. Instead it would be much simpler if you could just run the
Maven build
+ and suspend the execution of the build after the execution of the
<<<start-server>>> goal.
+ This would give you a fully configured Axis server instance that you can use
to execute
+ the test cases from within your IDE.
+
+ This use case is supported by the <<<start-server>>> goal. Simply set the
+ <<<axis.server.foreground>>> property on the command line:
+
+--------------------------------------------------------------------------------
+mvn clean integration-test -Daxis.server.foreground=true
+--------------------------------------------------------------------------------
+
+ If you configured your Maven project following the best practices described
in the
+ previous section, then this will still start the Axis server on a
dynamically allocated
+ port. This is undesirable because you would have to configure your IDE to
+ pass the relevant system property (<<<axisServerPort>>> in the sample
configuration)
+ to your test cases, and in addition you would have to constantly update that
+ configuration because the port number changes every time you restart the
Axis server.
+ You have two options to avoid this. One is to override the port number on
the command line:
+
+--------------------------------------------------------------------------------
+mvn clean integration-test -Daxis.server.foreground=true -DaxisServerPort=8080
+--------------------------------------------------------------------------------
+
+ The other option is to add a <<<foregroundPort>>> property with the port
number
+ to the configuration of the <<<start-server>>> goal:
+
+--------------------------------------------------------------------------------
+ <plugin>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>maven-axis-server-plugin</artifactId>
+ <version>${project.version}</version>
+ <executions>
+ <execution>
+ <id>start-server</id>
+ <goals>
+ <goal>start-server</goal>
+ </goals>
+ <configuration>
+ <port>${axisServerPort}</port>
+ <foregroundPort>8080</foregroundPort>
+ ...
+ </configuration>
+ </execution>
+ <execution>
+ <id>stop-server</id>
+ <goals>
+ <goal>stop-all</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+--------------------------------------------------------------------------------
+
+ If you now run the <<<start-server>>> goal in foreground mode, it will
automatically
+ choose the alternate port number you have specified.
+
+ In addition to that configuration you should also write your integration
test cases
+ such that they fall back to the specified port number if the relevant system
property
+ is not set. For the sample configuration used here, that means that to
determine the
+ port number, the following code should be used:
+
+--------------------------------------------------------------------------------
+System.getProperty("axisServerPort", "8080")
+--------------------------------------------------------------------------------
+
+ If you set up your project like that, then no additional configuration is
required
+ in your IDE and you only need to pass the <<<axis.server.foreground>>>
property
+ to Maven.
\ No newline at end of file
Modified: axis/axis1/java/trunk/maven/maven-axis-server-plugin/src/site/site.xml
URL:
http://svn.apache.org/viewvc/axis/axis1/java/trunk/maven/maven-axis-server-plugin/src/site/site.xml?rev=1391779&r1=1391778&r2=1391779&view=diff
==============================================================================
--- axis/axis1/java/trunk/maven/maven-axis-server-plugin/src/site/site.xml
(original)
+++ axis/axis1/java/trunk/maven/maven-axis-server-plugin/src/site/site.xml Sat
Sep 29 10:54:55 2012
@@ -22,6 +22,7 @@
<menu name="Overview">
<item name="Introduction" href="index.html"/>
<item name="Goals" href="plugin-info.html"/>
+ <item name="Usage" href="usage.html"/>
</menu>
</body>
</project>
