Enum Class PortmapTransport

java.lang.Object

java.lang.Enum<PortmapTransport>

com.frostwire.jlibtorrent.PortmapTransport

All Implemented Interfaces:

Serializable, Comparable<PortmapTransport>, Constable

public enum PortmapTransport
extends Enum<PortmapTransport>

Transport protocol for automatic port mapping on home routers.

PortmapTransport specifies which protocol to use when automatically opening ports on the router to enable incoming BitTorrent peer connections. Both UPnP and NAT-PMP are zero-configuration protocols that allow applications to request port forwarding without manual router configuration.

Understanding Port Mapping Protocols:

 Without Port Mapping:
   - You connect to peers (outgoing works through NAT)
   - Peers cannot connect to you (incoming blocked by NAT/firewall)
   - Result: Reduced connectivity, slower downloads, lower upload opportunities

 With Port Mapping (UPnP or NAT-PMP):
   - Router automatically forwards incoming TCP port to your application
   - Router automatically forwards incoming UDP port to your application
   - Peers can initiate connections to you
   - Result: Full connectivity, faster downloads, enabled seeding
 

NAT-PMP (Network Address Translation Port Mapping Protocol):

• Standard: RFC 6886 (Apple protocol, widely supported)
• Discovery: Uses multicast on local network (224.0.0.1:5350)
• Routers: Apple AirPort, many modern routers
• Setup Time: Usually 1-2 seconds
• Simplicity: Simpler than UPnP, less overhead
• Lease Time: Port mappings expire and must be renewed (typically 1 hour)

UPnP (Universal Plug and Play):

• Standard: IETF standard (widely deployed)
• Discovery: Uses SSDP multicast on local network
• Routers: Almost all modern home routers support UPnP
• Setup Time: Usually 2-5 seconds (more complex than NAT-PMP)
• Complexity: More feature-rich but higher overhead
• Lease Time: Typically 30 minutes to 1 hour (must be renewed)

Comparison Table:

Transport Protocol Comparison

Feature	NAT-PMP	UPnP
Standard	RFC 6886 (Apple)	IETF / IEC
Typical Port Time	1-2 seconds	2-5 seconds
Router Support	Good (Apple, some others)	Excellent (most routers)
Lease Renewal	Required (~1 hour)	Required (~30 min)
Complexity	Simpler	More features
Security Notes	More minimal API	Broader functionality

Configuring Port Mapping:

 // Typically handled automatically by SessionManager/SettingsPack
 // These enums appear in PortmapAlert and PortmapErrorAlert

 sm.addListener(new AlertListener() {
     public int[] types() {
         return new int[] {
             AlertType.PORTMAP_ALERT.swig(),
             AlertType.PORTMAP_ERROR_ALERT.swig()
         };
     }

     public void alert(Alert<?> alert) {
         if (alert instanceof PortmapAlert) {
             PortmapAlert a = (PortmapAlert) alert;
             PortmapTransport transport = a.mapTransport();
             System.out.println("Port mapped via " + transport);
             // transport is either NAT_PMP or UPNP
         } else if (alert instanceof PortmapErrorAlert) {
             PortmapErrorAlert a = (PortmapErrorAlert) alert;
             PortmapTransport transport = a.mapTransport();
             System.err.println("Failed to map port via " + transport);
         }
     }
 });
 

Port Mapping Behavior:

 Startup:
   1. jlibtorrent detects available routers on local network
   2. Tries configured transport (UPnP first by default)
   3. Requests port mapping with timeout
   4. On success: PortmapAlert is generated with port number
   5. On failure: PortmapErrorAlert generated, may try next protocol

 Periodic:
   - Port leases must be renewed before expiration
   - jlibtorrent automatically re-maps before lease expires
   - If router becomes unavailable, mapping is cleaned up

 Shutdown:
   - jlibtorrent sends unmapping request to router
   - Router removes the port forwarding rule
 

When Port Mapping Fails:

• Router doesn't support UPnP/NAT-PMP: Manual port forwarding in router settings
• Router has UPnP disabled: Enable in router configuration
• Firewall blocking: Allow UPnP/NAT-PMP in firewall
• No router found: Check network connection
• Port already in use: Change listening port in settings

Settings for Port Mapping:

 SettingsPack settings = new SettingsPack();

 // Enable port mapping (usually enabled by default)
 settings.setBoolean("enable_upnp", true);    // Try UPnP
 settings.setBoolean("enable_natpmp", true);  // Try NAT-PMP

 // Port mapping retry settings
 settings.setInteger("natpmp_tick_interval", 120);  // Re-map every 2 minutes
 settings.setInteger("upnp_lsd_timeout", 250);      // UPnP discovery timeout

 sm.applySettings(settings);
 

Performance Impact:

• Initial port mapping takes 1-5 seconds (done at startup)
• Minimal overhead once established (just periodic renewal)
• Improves connectivity significantly (incoming connections possible)
• Worth enabling for most applications (home networks, servers)

See Also:

• - Which ports (TCP/UDP) are mapped
• - Configure port mapping settings

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Enum

Enum.EnumDesc<E extends Enum<E>>

Enum Constant Summary

Enum Constants

Enum Constant	Description
NAT_PMP	NAT-PMP (Network Address Translation Port Mapping Protocol).
UPNP	UPnP (Universal Plug and Play).

Method Summary

Modifier and Type	Method	Description
static PortmapTransport	fromSwig(int swigValue)
int	swig()
static PortmapTransport	valueOf(String name)	Returns the enum constant of this class with the specified name.
static PortmapTransport[]	values()	Returns an array containing the constants of this enum class, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Details

NAT_PMP

public static final PortmapTransport NAT_PMP

NAT-PMP (Network Address Translation Port Mapping Protocol). Simpler, faster, requires RFC 6886 compatible router (Apple AirPort, some modern routers).

UPNP

public static final PortmapTransport UPNP

UPnP (Universal Plug and Play). More widely supported by home routers, but slightly more overhead.

Method Details

values

public static PortmapTransport[] values()

Returns an array containing the constants of this enum class, in the order they are declared.

Returns:

an array containing the constants of this enum class, in the order they are declared

valueOf

public static PortmapTransport valueOf(String name)

Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum class has no constant with the specified name

NullPointerException - if the argument is null

swig

public int swig()

fromSwig

public static PortmapTransport fromSwig(int swigValue)