net.i2p.data

## Class Lease

- java.lang.Object
- - net.i2p.data.DataStructureImpl
  - - net.i2p.data.Lease

- All Implemented Interfaces:
    Serializable, DataStructure
  Direct Known Subclasses:
    Lease2, MetaLease

      public class Lease
      extends DataStructureImpl

  Authorization grant proving a router/tunnel may receive messages for a destination.

  Lease represents the fundamental routing authorization in I2P:

  - Authorization: Proves specific router can receive messages
  - Time-Bound: Valid only for specified time period
  - Destination-Specific: Authorizes service for particular destination
  - Tunnel Endpoint: Identifies specific tunnel on gateway router

  Key Components:

  - Gateway: `Hash` identifying the router hosting the tunnel
  - Tunnel ID: `TunnelId` identifying specific tunnel on gateway
  - End Time: `long` timestamp when lease expires

  Authorization Model:

  - Proof of Authority: Destination authorizes specific router
  - Time Limitation: Authorization expires after set duration
  - Tunnel Specificity: Authorizes particular tunnel, not all tunnels
  - Renewable: Leases can be refreshed before expiration

  Usage in LeaseSet:

  - Multiple Leases: Destinations typically have several concurrent leases
  - Load Balancing: Multiple leases distribute message load
  - Redundancy: Backup tunnels if primary becomes unavailable
  - Mobility: Leases updated as destination moves between routers

  Network Operations:

  - Message Routing: Routers use leases to forward messages
  - Tunnel Selection: Senders choose from available leases
  - Expiration Handling: Leases removed when they expire
  - LeaseSet Publication: Leases published to network database

  Security Considerations:

  - Verification: Verify lease authenticity via LeaseSet signature
  - Expiration: Ensure leases are still valid before use
  - Gateway Trust: Verify gateway router is trusted
  - Tunnel Security: Ensure tunnel endpoint is secure

  Performance Aspects:

  - Efficient Lookup: Hash-based gateway identification
  - Quick Expiration: Timestamp comparison for validity checks
  - Compact Storage: Minimal data structure for network transmission
  - Fast Comparison: Optimized equals() and hashCode() methods

  Related Structures:

  - `LeaseSet` - Container for multiple leases
  - `Lease2` - Enhanced version with 4-byte timestamps
  - `MetaLease` - References other LeaseSets instead of tunnels
  - `TunnelId` - Tunnel identifier on gateway router
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected long` | `_end`
    `protected Hash` | `_gateway`
    `protected TunnelId` | `_tunnelId`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Lease()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(Object object)`
    `long` | `getEndTime()` Gets the lease end time.
    `Hash` | `getGateway()` Retrieve the router at which the destination can be contacted
    `TunnelId` | `getTunnelId()` Tunnel on the gateway to communicate with
    `int` | `hashCode()`
    `boolean` | `isExpired()` has this lease already expired?
    `boolean` | `isExpired(long fudgeFactor)` has this lease already expired (giving allowing up the fudgeFactor milliseconds for clock skew)?
    `void` | `readBytes(InputStream in)` Load up the current object with data from the given stream.
    `void` | `setEndDate(long date)` Sets the lease end date.
    `void` | `setGateway(Hash ident)` Configure the router at which the destination can be contacted
    `void` | `setTunnelId(TunnelId id)` Configure the tunnel on the gateway to communicate with
    `String` | `toString()`
    `void` | `writeBytes(OutputStream out)` Write out the data structure to the stream, using the format defined in the I2P data structure specification.

    - ### Methods inherited from class net.i2p.data.DataStructureImpl

      `calculateHash, fromBase64, fromByteArray, read, toBase64, toByteArray`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### _end

          protected long _end

    - #### _gateway

          protected Hash _gateway

    - #### _tunnelId

          protected TunnelId _tunnelId

  - ### Constructor Detail

    - #### Lease

          public Lease()

  - ### Method Detail

    - #### equals

          public boolean equals(Object object)

      Overrides:
        `equals` in class `Object`

    - #### getEndTime

          public long getEndTime()

      Gets the lease end time.

    - #### getGateway

          public Hash getGateway()

      Retrieve the router at which the destination can be contacted
      Returns:
        identity of the router acting as a gateway

    - #### getTunnelId

          public TunnelId getTunnelId()

      Tunnel on the gateway to communicate with
      Returns:
        tunnel ID

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### isExpired

          public boolean isExpired()

      has this lease already expired?

    - #### isExpired

          public boolean isExpired(long fudgeFactor)

      has this lease already expired (giving allowing up the fudgeFactor milliseconds for clock skew)?

    - #### readBytes

          public void readBytes(InputStream in)
                         throws DataFormatException,
                                IOException

      Description copied from interface: `DataStructure`
      Load up the current object with data from the given stream. Data loaded this way must match the I2P data structure specification. Warning - many classes will throw IllegalStateException if data is already set.
      Parameters:
        `in` - stream to read from
      Throws:
        `DataFormatException` - if the data is improperly formatted
        `IOException` - if there was a problem reading the stream

    - #### setEndDate

          public void setEndDate(long date)

      Sets the lease end date.

    - #### setGateway

          public void setGateway(Hash ident)

      Configure the router at which the destination can be contacted
      Parameters:
        `ident` - router acting as the gateway

    - #### setTunnelId

          public void setTunnelId(TunnelId id)

      Configure the tunnel on the gateway to communicate with
      Parameters:
        `id` - tunnel ID

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### writeBytes

          public void writeBytes(OutputStream out)
                          throws DataFormatException,
                                 IOException

      Description copied from interface: `DataStructure`
      Write out the data structure to the stream, using the format defined in the I2P data structure specification.
      Parameters:
        `out` - stream to write to
      Throws:
        `DataFormatException` - if the data was incomplete or not yet ready to be written
        `IOException` - if there was a problem writing to the stream