PortForwardManager (Apache Brooklyn)

All Superinterfaces:

BrooklynObject, Configurable, Identifiable, Location, java.io.Serializable

All Known Implementing Classes:

PortForwardManagerAuthority, PortForwardManagerClient, PortForwardManagerImpl
```
@Beta
public interface PortForwardManager
extends Location
```
Acts as a registry for existing port mappings (e.g. the public endpoints for accessing specific ports on private VMs). This could be using DNAT, or iptables port-forwarding, or Docker port-mapping via the host, or any other port mapping approach. Also controls the allocation of ports via acquirePublicPort(String) (e.g. for port-mapping with DNAT, then which port to use for the public side). Implementations typically will not know anything about what the firewall/IP actually is, they just handle a unique identifier for it. To use, see PortForwardManagerLocationResolver, with code such as managementContext.getLocationRegistry().resolve("portForwardManager(scope=global)").

See Also:
for implementation notes and considerations.

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static interface PortForwardManager.AssociationListener

static class PortForwardManager.AssociationMetadata
- Nested classes/interfaces inherited from interface brooklyn.basic.BrooklynObject
  BrooklynObject.TagSupport
- Nested classes/interfaces inherited from interface brooklyn.entity.trait.Configurable
  Configurable.ConfigurationSupport

Nested Classes
Modifier and Type	Interface and Description
`static interface`	`PortForwardManager.AssociationListener`
`static class`	`PortForwardManager.AssociationMetadata`

Field Summary

Fields
Modifier and Type	Field and Description
`static ConfigKey<java.lang.Integer>`	`PORT_FORWARD_MANAGER_STARTING_PORT`
`static ConfigKey<java.lang.String>`	`SCOPE` The intention is that there is one PortForwardManager instance per "scope".

Method Summary

Methods
Modifier and Type	Method and Description
`int`	`acquirePublicPort(java.lang.String publicIpId)` Reserves a unique public port on the given publicIpId.
`int`	`acquirePublicPort(java.lang.String publicIpId, Location l, int privatePort)` Deprecated. since 0.7.0; use `acquirePublicPort(String)`, and then use `associate(String, HostAndPort, int)` or `associate(String, HostAndPort, Location, int)`
`PortMapping`	`acquirePublicPortExplicit(java.lang.String publicIpId, int port)` Deprecated. since 0.7.0; use `associate(String, HostAndPort, int)` or `associate(String, HostAndPort, Location, int)`
`void`	`addAssociationListener(PortForwardManager.AssociationListener listener, com.google.common.base.Predicate<? super PortForwardManager.AssociationMetadata> filter)` Registers a listener, which will be notified each time a new port mapping is associated.
`void`	`associate(java.lang.String publicIpId, com.google.common.net.HostAndPort publicEndpoint, int privatePort)` Records a mapping for publicIpId:privatePort to a public endpoint, such that it can subsequently be looked up using `lookup(String, int)`.
`void`	`associate(java.lang.String publicIpId, com.google.common.net.HostAndPort publicEndpoint, Location l, int privatePort)` Records a location and private port against a public endpoint (ip and port), to support `lookup(Location, int)`.
`void`	`associate(java.lang.String publicIpId, int publicPort, Location l, int privatePort)` Deprecated. Use `associate(String, HostAndPort, Location, int)`
`boolean`	`forgetPortMapping(PortMapping m)` Deprecated. since 0.7.0; this method will be internal only
`boolean`	`forgetPortMapping(java.lang.String publicIpId, int publicPort)` Clears the given port mapping, returning true if there was a match.
`boolean`	`forgetPortMappings(Location location)` Clears the port mappings associated with the given location, returning true if there were any matches.
`boolean`	`forgetPortMappings(java.lang.String publicIpId)` Clears the port mappings associated with the given publicIpId, returning true if there were any matches.
`boolean`	`forgetPublicIpHostname(java.lang.String publicIpId)` Deprecated. Use `forgetPortMapping(String, int)` or `forgetPortMappings(Location)`
`java.util.Collection<PortMapping>`	`getLocationPublicIpIds(Location l)` Deprecated. since 0.7.0; this method will be internal only
`PortMapping`	`getPortMappingWithPrivateSide(Location l, int privatePort)` Deprecated. since 0.7.0; this method will be internal only
`java.util.Collection<PortMapping>`	`getPortMappingWithPublicIpId(java.lang.String publicIpId)` Deprecated. since 0.7.0; this method will be internal only
`PortMapping`	`getPortMappingWithPublicSide(java.lang.String publicIpId, int publicPort)` Deprecated. since 0.7.0; this method will be internal only
`com.google.common.net.HostAndPort`	`getPublicHostAndPort(PortMapping m)` Deprecated. since 0.7.0; this method will be internal only
`java.lang.String`	`getPublicIpHostname(java.lang.String publicIpId)` Deprecated. Use `lookup(String, int)` or `lookup(Location, int)`
`java.lang.String`	`getScope()`
`boolean`	`isClient()` Deprecated. since 0.7.0; no need to separate client-proxy from impl
`com.google.common.net.HostAndPort`	`lookup(Location l, int privatePort)` Returns the public ip hostname and public port for use contacting the given endpoint.
`com.google.common.net.HostAndPort`	`lookup(java.lang.String publicIpId, int privatePort)` Returns the public endpoint (host and port) for use contacting the given endpoint.
`void`	`recordPublicIpHostname(java.lang.String publicIpId, java.lang.String hostnameOrPublicIpAddress)` Deprecated. Use `associate(String, HostAndPort, int)` or `associate(String, HostAndPort, Location, int)`
`void`	`removeAssociationListener(PortForwardManager.AssociationListener listener)`
`java.lang.String`	`toVerboseString()`

Methods inherited from interface brooklyn.location.Location
containsLocation, getAllConfig, getChildren, getConfig, getConfig, getDisplayName, getExtension, getId, getParent, hasConfig, hasExtension, setParent

Methods inherited from interface brooklyn.basic.BrooklynObject
getCatalogItemId, getTagSupport, tags

Methods inherited from interface brooklyn.entity.trait.Configurable
config, setConfig

- Field Detail
  - SCOPE
```
static final ConfigKey<java.lang.String> SCOPE
```
    The intention is that there is one PortForwardManager instance per "scope". If you use global, then it will be a shared instance (for that management context). If you pass in your own name (e.g. "docker-fjie3") then it will shared with just any other places that use that same location spec (e.g. portForwardManager(scope=docker-fjie3)).
  - PORT_FORWARD_MANAGER_STARTING_PORT
```
@Beta
static final ConfigKey<java.lang.Integer> PORT_FORWARD_MANAGER_STARTING_PORT
```
- Method Detail
  - getScope
```
java.lang.String getScope()
```
  - acquirePublicPort
```
int acquirePublicPort(java.lang.String publicIpId)
```
    Reserves a unique public port on the given publicIpId.
    Often followed by associate(String, HostAndPort, int) or associate(String, HostAndPort, Location, int) to enable lookup(String, int) or lookup(Location, int) respectively.
  - associate
```
void associate(java.lang.String publicIpId,
             com.google.common.net.HostAndPort publicEndpoint,
             Location l,
             int privatePort)
```
    Records a location and private port against a public endpoint (ip and port), to support lookup(Location, int).
    Superfluous if acquirePublicPort(String, Location, int) was used, but strongly recommended if acquirePublicPortExplicit(String, int) was used e.g. if the location is not known ahead of time.
  - associate
```
void associate(java.lang.String publicIpId,
             com.google.common.net.HostAndPort publicEndpoint,
             int privatePort)
```
    Records a mapping for publicIpId:privatePort to a public endpoint, such that it can subsequently be looked up using lookup(String, int).
  - addAssociationListener
```
@Beta
void addAssociationListener(PortForwardManager.AssociationListener listener,
                               com.google.common.base.Predicate<? super PortForwardManager.AssociationMetadata> filter)
```
    Registers a listener, which will be notified each time a new port mapping is associated. See associate(String, HostAndPort, int) and associate(String, HostAndPort, Location, int).
  - removeAssociationListener
```
@Beta
void removeAssociationListener(PortForwardManager.AssociationListener listener)
```
  - lookup
```
com.google.common.net.HostAndPort lookup(Location l,
                                       int privatePort)
```
    Returns the public ip hostname and public port for use contacting the given endpoint.
    Will return null if:
    - No publicPort is associated with this location and private port.
    - No publicIpId is associated with this location and private port.
    - No publicIpHostname is recorded against the associated publicIpId.
    Conceivably this may have to be access-location specific.
    See Also:
    recordPublicIpHostname(String, String)
  - lookup
```
com.google.common.net.HostAndPort lookup(java.lang.String publicIpId,
                                       int privatePort)
```
    Returns the public endpoint (host and port) for use contacting the given endpoint. Expects a previous call to associate(String, HostAndPort, int), to register the endpoint. Will return null if there has not been a public endpoint associated with this pairing.
  - forgetPortMapping
```
boolean forgetPortMapping(java.lang.String publicIpId,
                        int publicPort)
```
    Clears the given port mapping, returning true if there was a match.
  - forgetPortMappings
```
boolean forgetPortMappings(Location location)
```
    Clears the port mappings associated with the given location, returning true if there were any matches.
  - forgetPortMappings
```
boolean forgetPortMappings(java.lang.String publicIpId)
```
    Clears the port mappings associated with the given publicIpId, returning true if there were any matches.
  - toVerboseString
```
java.lang.String toVerboseString()
```
    Specified by:
    
    toVerboseString in interface Location
    
    Returns:
    meta-data about the location (usually a long line, or a small number of lines).
  - acquirePublicPort
```
@Deprecated
int acquirePublicPort(java.lang.String publicIpId,
                               Location l,
                               int privatePort)
```
    Deprecated. since 0.7.0; use acquirePublicPort(String), and then use associate(String, HostAndPort, int) or associate(String, HostAndPort, Location, int)
    
    Reserves a unique public port for the purpose of forwarding to the given target, associated with a given location for subsequent lookup purpose.
    If already allocated, returns the previously allocated.
  - acquirePublicPortExplicit
```
@Deprecated
PortMapping acquirePublicPortExplicit(java.lang.String publicIpId,
                                               int port)
```
    Deprecated. since 0.7.0; use associate(String, HostAndPort, int) or associate(String, HostAndPort, Location, int)
    
    Returns old mapping if it existed, null if it is new.
  - associate
```
@Deprecated
void associate(java.lang.String publicIpId,
                        int publicPort,
                        Location l,
                        int privatePort)
```
    Deprecated. Use associate(String, HostAndPort, Location, int)
    
    Records a location and private port against a publicIp and public port, to support lookup(Location, int).
    Superfluous if acquirePublicPort(String, Location, int) was used, but strongly recommended if acquirePublicPortExplicit(String, int) was used e.g. if the location is not known ahead of time.
  - recordPublicIpHostname
```
@Deprecated
void recordPublicIpHostname(java.lang.String publicIpId,
                                     java.lang.String hostnameOrPublicIpAddress)
```
    Deprecated. Use associate(String, HostAndPort, int) or associate(String, HostAndPort, Location, int)
    
    Records a public hostname or address to be associated with the given publicIpId for lookup purposes.
    Conceivably this may have to be access-location specific.
  - getPublicIpHostname
```
@Deprecated
java.lang.String getPublicIpHostname(java.lang.String publicIpId)
```
    Deprecated. Use lookup(String, int) or lookup(Location, int)
    
    Returns a recorded public hostname or address.
  - forgetPublicIpHostname
```
@Deprecated
boolean forgetPublicIpHostname(java.lang.String publicIpId)
```
    Deprecated. Use forgetPortMapping(String, int) or forgetPortMappings(Location)
    
    Clears a previous call to recordPublicIpHostname(String, String).
  - isClient
```
@Deprecated
boolean isClient()
```
    Deprecated. since 0.7.0; no need to separate client-proxy from impl
    
    Returns true if this implementation is a client which is immutable/safe for serialization i.e. it delegates to something on an entity or location elsewhere.
  - getPortMappingWithPublicSide
```
@Deprecated
PortMapping getPortMappingWithPublicSide(java.lang.String publicIpId,
                                                  int publicPort)
```
    Deprecated. since 0.7.0; this method will be internal only
    
    Returns the port mapping for a given publicIpId and public port.
  - getPortMappingWithPublicIpId
```
@Deprecated
java.util.Collection<PortMapping> getPortMappingWithPublicIpId(java.lang.String publicIpId)
```
    Deprecated. since 0.7.0; this method will be internal only
    
    Returns the subset of port mappings associated with a given public IP ID.
  - forgetPortMapping
```
@Deprecated
boolean forgetPortMapping(PortMapping m)
```
    Deprecated. since 0.7.0; this method will be internal only
    
    See Also:
    #forgetPortMapping(String, int)} and {@link #forgetPortMappings(Location)}
  - getPublicHostAndPort
```
@Deprecated
com.google.common.net.HostAndPort getPublicHostAndPort(PortMapping m)
```
    Deprecated. since 0.7.0; this method will be internal only
    
    Returns the public host and port for use accessing the given mapping.
    Conceivably this may have to be access-location specific.
  - getLocationPublicIpIds
```
@Deprecated
java.util.Collection<PortMapping> getLocationPublicIpIds(Location l)
```
    Deprecated. since 0.7.0; this method will be internal only
    
    Returns the subset of port mappings associated with a given location.
  - getPortMappingWithPrivateSide
```
@Deprecated
PortMapping getPortMappingWithPrivateSide(Location l,
                                                   int privatePort)
```
    Deprecated. since 0.7.0; this method will be internal only
    
    Returns the mapping to a given private port, or null if none.

Interface PortForwardManager

Nested Class Summary

Nested classes/interfaces inherited from interface brooklyn.basic.BrooklynObject

Nested classes/interfaces inherited from interface brooklyn.entity.trait.Configurable

Field Summary

Method Summary

Methods inherited from interface brooklyn.location.Location

Methods inherited from interface brooklyn.basic.BrooklynObject

Methods inherited from interface brooklyn.entity.trait.Configurable

Field Detail

SCOPE

PORT_FORWARD_MANAGER_STARTING_PORT

Method Detail

getScope

acquirePublicPort

associate

associate

addAssociationListener

removeAssociationListener

lookup

lookup

forgetPortMapping

forgetPortMappings

forgetPortMappings

toVerboseString

acquirePublicPort

acquirePublicPortExplicit

associate

recordPublicIpHostname

getPublicIpHostname

forgetPublicIpHostname

isClient

getPortMappingWithPublicSide

getPortMappingWithPublicIpId

forgetPortMapping

getPublicHostAndPort

getLocationPublicIpIds

getPortMappingWithPrivateSide