JarCasting
JarCasting JarCasting

portallocator-maven-plugin


License

License

Apache License Version 2.0, January 2004
Categories

Categories

Maven Build Tools
GroupId

GroupId

org.bitstrings.maven.plugins
ArtifactId

ArtifactId

portallocator-maven-plugin
Last Version

Last Version

2.0
Release Date

Release Date
Type

Type

maven-plugin
Description

Description

portallocator-maven-plugin
Project Organization

Project Organization

bitstrings.org
Source Code Management

Source Code Management

https://github.com/bitstrings/portallocator-maven-plugin

Download portallocator-maven-plugin

Filename Size
portallocator-maven-plugin-2.0.pom
portallocator-maven-plugin-2.0.jar 19 KB
portallocator-maven-plugin-2.0-sources.jar 6 KB
portallocator-maven-plugin-2.0-javadoc.jar 80 KB
Browse

How to add to project

<plugin>
    <groupId>org.bitstrings.maven.plugins</groupId>
    <artifactId>portallocator-maven-plugin</artifactId>
    <version>2.0</version>
</plugin>

Dependencies

compile (4)

Group / Artifact Type Version
org.apache.maven : maven-core jar 3.2.5
org.apache.maven : maven-plugin-api jar 3.2.5
com.google.guava : guava jar 18.0
org.apache.commons : commons-lang3 jar 3.3.2

provided (1)

Group / Artifact Type Version
org.apache.maven.plugin-tools : maven-plugin-annotations jar 3.4

test (5)

Group / Artifact Type Version
org.apache.maven.plugin-testing : maven-plugin-testing-harness jar 3.3.0
junit : junit jar 4.12
org.jmockit : jmockit jar 1.16
org.bitstrings.test : junit-clptr jar 1.1
org.apache.maven : maven-compat jar 3.2.5

Project Modules

There are no modules declared in this project.

Build Status

NOTE: There's is also a 1.x version of this plugin but it has a very different configuration.

portallocator-maven-plugin

Description

The port allocator plugin finds an available port and makes sure it is unique for the Maven execution.

Usage

<plugin>
    <groupId>org.bitstrings.maven.plugins</groupId>
    <artifactId>portallocator-maven-plugin</artifactId>
    <execution>
        <id>allocate</id>
        <goals>
            <goal>allocate</goal>
        </goals>
        <configuration>
            <ports>portName</ports>
        </configuration>
    </execution>
</plugin>

Goal allocate

Attributes

  • Requires a Maven project to be executed.
  • The goal is thread-safe and supports parallel builds.
  • Binds by default to the lifecycle phase: generate-test-resources.

Configuration

name type Since Description
portAllocators List 2.0 List of port allocators.
Short form: <portAllocators>shortForm1,shortForm2,...</portAllocators>
ports Ports 2.0 List of ports.
Short form: <ports>shortForm1,shortForm2,...</ports>
nameSeparator String 2.0 The name level separator.
Default: .
portNameSuffix String 2.0 The port name suffix.
Default: port
Example: name.port
offsetNameSuffix String 2.0 The offset name suffix.
Default: port-offset
Example: name.port-offset
writePropertiesFile File 2.0 Write ports properties file.
quiet Boolean 1.0 Set to true for no output.
Default: false

Structure portAllocators

name type Since Description
portAllocator PortAllocator 2.0 Port allocator.
Short form: <portAllocator>shortForm</portAllocator>

Structure portAllocator

name type Since Description
id String 2.0 The port allocator id.
Default: default when not set.
preferredPorts List 2.0 The preferred ports.
Default: 8090
depletedAction String 2.0 The action to take if preferred ports are depleted.
Values: continue or fail
Default: continue
permitOverride Boolean 2.0 By default allocators can not be overridden.
This is useful for multi-module projects.
Default: false
preferredPorts
name type Since Description
ports String 2.0 Allowed ports.

Structure ports

name type Since Description
portAllocatorRef String 2.0 The port allocator id to use.
Default: default
You may only use portAllocatorRef or portAllocator but not both.
portAllocator PortAllocator 2.0 Inner port allocator.
You may only use portAllocatorRef or portAllocator but not both.
port Port 2.0 The port to assign.
Short form: <port>shortForm</port>

Structure port

name type Since Description
name String 2.0 The first level name of the property.
preferredPort Integer 2.0 The preferred port if available.
offsetFrom String 2.0 Use the offset from the specified port.
setOffsetProperty Boolean 2.0 If true this will set the port offset property.
Default: false

Short form port

{name}:{preferredPort}:{offsetFrom}:{setOffsetProperty}

Short form portAllocator

{preferredPorts}:{id}:{depletedAction}

If id is omitted, then default is used.

Example - Simplest way

This is the simplest way you can assign a port. The default preferred port is 8090.

Short form

<configuration>
    <ports>tomcat</ports>
</configuration>
<configuration>
    <ports>
        <port>tomcat</port>
    </ports>
</configuration>

Long form

<configuration>
    <ports>
        <port>
            <name>tomcat</name>
        </port>
    </ports>
</configuration>

Result might be or any other port depending on availability:

tomcat.port = 8090

Example - Preferred port

Short form

<configuration>
    <ports>
        <port>wildfly:8080</port>
    </ports>
</configuration>
<configuration>
    <ports>wildfly:8080</ports>
</configuration>

Long form

<configuration>
    <ports>
        <port>
            <name>wildfly</name>
            <preferredPort>8080</preferredPort>
        </port>
    </ports>
</configuration>

Example - Write the ports to a properties file

Short form

<configuration>
    <writePropertiesFile>${project.build.directory}/ports.properties</writePropertiesFile>
    <ports>tomcat,hsqldb</ports>
</configuration>
<configuration>
    <writePropertiesFile>${project.build.directory}/ports.properties</writePropertiesFile>
    <ports>
        tomcat,
        hsqldb
    </ports>
</configuration>
<configuration>
    <writePropertiesFile>${project.build.directory}/ports.properties</writePropertiesFile>
    <ports>
        <port>tomcat</port>
        <port>hsqldb</port>
    </ports>
</configuration>

Long form

<configuration>
    <writePropertiesFile>${project.build.directory}/ports.properties</writePropertiesFile>
    <ports>
        <port>
            <name>tomcat</name>
        </port>
        <port>
            <name>hsqldb</name>
        </port>
    </ports>
</configuration>

Example - Register a port allocator

Short form

<configuration>
    <portAllocators>9090</portAllocators>
</configuration>
<configuration>
    <portAllocators>
        <portAllocator>9090</portAllocators>
    </portAllocators>
</configuration>

Long form

<configuration>
    <portAllocators>
        <portAllocator>
            <preferredPorts>9090</preferredPorts>
        </portAllocator>
    </portAllocators>
</configuration>

Two things:

  1. Unless you set permitOverride to true, you can register port allocators in the parent without worrying about re-registering in child modules.
  2. The can override the default allocator by using <id>default</id> or omit the id.
<configuration>
    <portAllocators>
        <portAllocator>
            <id>pool-1</id>
            <preferredPorts>
                <ports>8080-9090</ports>
                <depletedAction>fail</depletedAction>
            </preferredPorts>
        </portAllocator>
    </portAllocators>
</configuration>

This allocator will try to assign ports from 8080 to 9090, otherwise fail.

<configuration>
    <ports>
        <portAllocatorRef>pool-1</portAllocatorRef>
        <port>
            <name>wildfly</name>
            <offsetBasePort>8080</offsetBasePort>
        </port>
        <port>hsqldb</port>
    </ports>
</configuration>

Use the pool-1 port allocator.

Register multiple port allocator

<configuration>
    <portAllocators>
        8080-8999;9090-9099::fail,
        10000-10999;12000;12002;12004;13000:pool1,
        11000-11100:pool2:fail
    </portAllocators>
</configuration>
  1. Overrides default port allocator and fail if it can't allocate a port between 8080-8999 or 9090-9099.
  2. Create a new port allocator pool1 with an availability range of 10000-10999 and a set of specific ports: 12000,12002,12004,13000.
  3. Create a new port allocator pool2 and fail if it can't allocate a port between 11000-11100.

Notice: When using the short form with portAllocators you enumerate preferred ports using ;.

Example - Port offset

<configuration>
    <ports>
        <port>
            <name>name1</name>"
            <preferredPort>8096</preferredPort>
            <setOffsetProperty>true</setOffsetProperty>
        </port>
        <port>
            <name>name2</name>
            <preferredPort>8090</preferredPort>
            <offsetFrom>name1</offsetFrom>
        </port>
    </ports>
</configuration>

Using offsetFrom forces the allocation the being the preferredPort + offsetFrom.

i.e.:

if
    name1.port = 8096
    name1.port-offset = 0
then
    name2.port = 8090

if
    name1.port = 8100
    name1.port-offset = 4
then
    name2.port = 8094

This can be useful with wildfly for example, because you can use an offset that is applied for all ports.

Examples

<configuration>
    <ports>
        wildfly-http:8080::true,
        wildfly-https:8443:wildfly-http,
        wildfly-jndi:8888:wildfly-http,
        hsqldb
    </ports>
</configuration>
<configuration>
    <ports>
        <portAllocator>9090</portAllocator>
        <port>wildfly-http</port>
        <port>wildfly-https</port>
        <port>wildfly-jndi</port>
        <port>hsqldb</port>
    </ports>
</configuration>
<configuration>
    <portAllocators>8080;8085;9090:custom</portAllocators>
    <ports>
        <portAllocatorRef>custom</portAllocatorRef>
        <port>http</port>
        <port>https</port>
        <port>hsqldb</port>
    </ports>
</configuration>
<executions>
    <execution>
        <id>allocators</id>
        <goals>
            <goal>allocate</goal>
        </goals>
        <configuration>
            <portAllocators>9000-9100</portAllocators>
        </configuration>
    </execution>
</executions>

<executions>
    <execution>
        <id>allocate-ports</id>
        <goals>
            <goal>allocate</goal>
        </goals>
        <configuration>
            <ports>portA,portB,portC</ports>
        </configuration>
    </execution>
</executions>

Versions

Version
2.0
1.1
1.0