PortForwardManager (Apache Brooklyn)

All Known Implementing Classes:

PortForwardManagerAuthority, PortForwardManagerClient
```
@Beta
public interface PortForwardManager
```
Records port mappings against public IP addresses with given identifiers.
To use, create a new authoritative instance (e.g. PortForwardManagerAuthority) which will live in one canonical place, then set config to be a client (e.g. PortForwardManagerClient which delegates to the primary instance) so the authority is shared among all communicating parties but only persisted in one place.
One Location side (e.g. a software process in a VM) can request (acquirePublicPort(String, Location, int)) an unused port on a firewall / public IP address. It may then go on actually to talk to that firewall/IP to provision the forwarding rule.
Subsequently the other side can use this class lookup(Location, int) if it knows the location and private port it wishes to talk to.
Implementations typically will not know anything about what the firewall/IP actually is, they just handle a unique identifier for it. It is recommended, however, to recordPublicIpHostname(String, String) an accessible hostname with the identifier. This is required in order to use lookup(Location, int).

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)` Reserves a unique public port for the purpose of forwarding to the given target, associated with a given location for subsequent lookup purpose.
`PortMapping`	`acquirePublicPortExplicit(java.lang.String publicIpId, int port)` Returns old mapping if it existed, null if it is new.
`void`	`associate(java.lang.String publicIpId, int publicPort, Location l, int privatePort)` Records a location and private port against a publicIp and public port, to support `lookup(Location, int)`.
`boolean`	`forgetPortMapping(PortMapping m)`
`PortMapping`	`forgetPortMapping(java.lang.String publicIpId, int publicPort)` Clears the given port mapping, returning the mapping if there was one.
`boolean`	`forgetPublicIpHostname(java.lang.String publicIpId)` Clears a previous call to `recordPublicIpHostname(String, String)`.
`java.util.Collection<PortMapping>`	`getLocationPublicIpIds(Location l)` Returns the subset of port mappings associated with a given location.
`PortMapping`	`getPortMappingWithPrivateSide(Location l, int privatePort)` Returns the mapping to a given private port, or null if none.
`java.util.Collection<PortMapping>`	`getPortMappingWithPublicIpId(java.lang.String publicIpId)` Returns the subset of port mappings associated with a given public IP ID.
`PortMapping`	`getPortMappingWithPublicSide(java.lang.String publicIpId, int publicPort)` Returns the port mapping for a given publicIpId and public port.
`com.google.common.net.HostAndPort`	`getPublicHostAndPort(PortMapping m)` Returns the public host and port for use accessing the given mapping.
`java.lang.String`	`getPublicIpHostname(java.lang.String publicIpId)` Returns a recorded public hostname or address.
`boolean`	`isClient()` Returns true if this implementation is a client which is immutable/safe for serialization i.e.
`com.google.common.net.HostAndPort`	`lookup(Location l, int privatePort)` Returns the public ip hostname and public port for use contacting the given endpoint.
`void`	`recordPublicIpHostname(java.lang.String publicIpId, java.lang.String hostnameOrPublicIpAddress)` Records a public hostname or address to be associated with the given publicIpId for lookup purposes.

- Method Detail
  - acquirePublicPort
```
int acquirePublicPort(java.lang.String publicIpId)
```
    Reserves a unique public port on the given publicIpId.
    Often followed by associate(String, int, Location, int) to enable lookup(Location, int).
  - acquirePublicPortExplicit
```
PortMapping acquirePublicPortExplicit(java.lang.String publicIpId,
                                    int port)
```
    Returns old mapping if it existed, null if it is new.
  - getPortMappingWithPublicSide
```
PortMapping getPortMappingWithPublicSide(java.lang.String publicIpId,
                                       int publicPort)
```
    Returns the port mapping for a given publicIpId and public port.
  - getPortMappingWithPublicIpId
```
java.util.Collection<PortMapping> getPortMappingWithPublicIpId(java.lang.String publicIpId)
```
    Returns the subset of port mappings associated with a given public IP ID.
  - forgetPortMapping
```
PortMapping forgetPortMapping(java.lang.String publicIpId,
                            int publicPort)
```
    Clears the given port mapping, returning the mapping if there was one.
  - forgetPortMapping
```
boolean forgetPortMapping(PortMapping m)
```
    See Also:
    forgetPortMapping(String, int)
  - recordPublicIpHostname
```
void recordPublicIpHostname(java.lang.String publicIpId,
                          java.lang.String hostnameOrPublicIpAddress)
```
    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
```
java.lang.String getPublicIpHostname(java.lang.String publicIpId)
```
    Returns a recorded public hostname or address.
  - forgetPublicIpHostname
```
boolean forgetPublicIpHostname(java.lang.String publicIpId)
```
    Clears a previous call to recordPublicIpHostname(String, String).
  - getPublicHostAndPort
```
com.google.common.net.HostAndPort getPublicHostAndPort(PortMapping m)
```
    Returns the public host and port for use accessing the given mapping.
    Conceivably this may have to be access-location specific.
  - acquirePublicPort
```
int acquirePublicPort(java.lang.String publicIpId,
                    Location l,
                    int privatePort)
```
    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.
  - 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)
  - associate
```
void associate(java.lang.String publicIpId,
             int publicPort,
             Location l,
             int privatePort)
```
    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.
  - getLocationPublicIpIds
```
java.util.Collection<PortMapping> getLocationPublicIpIds(Location l)
```
    Returns the subset of port mappings associated with a given location.
  - getPortMappingWithPrivateSide
```
PortMapping getPortMappingWithPrivateSide(Location l,
                                        int privatePort)
```
    Returns the mapping to a given private port, or null if none.
  - isClient
```
boolean isClient()
```
    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.

Interface PortForwardManager

Method Summary

Method Detail

acquirePublicPort

acquirePublicPortExplicit

getPortMappingWithPublicSide

getPortMappingWithPublicIpId

forgetPortMapping

forgetPortMapping

recordPublicIpHostname

getPublicIpHostname

forgetPublicIpHostname

getPublicHostAndPort

acquirePublicPort

lookup

associate

getLocationPublicIpIds

getPortMappingWithPrivateSide

isClient