Package com.frostwire.jlibtorrent

Interface AlertListener

public interface AlertListener
Callback interface for receiving notifications from the bittorrent session.

AlertListener is the primary mechanism for applications to receive real-time notifications about torrent activity, errors, and network events from jlibtorrent. The listener pattern allows asynchronous event handling without polling, making it ideal for responsive user interfaces and server applications.

Alert-Based Event System:

Instead of synchronous method calls, jlibtorrent uses an event-driven alert system. The native libtorrent session generates alerts (events) which are queued and dispatched to registered listeners. This decouples the fast network processing thread from your application logic, enabling both high performance and clean architecture.

Basic Usage: 

 // Create listener for torrent completion events only
 AlertListener listener = new AlertListener() {
     public int[] types() {
         // Only listen to torrent finished alerts
         return new int[] {AlertType.TORRENT_FINISHED.swig()};
     }

     public void alert(Alert<?> alert) {
         TorrentFinishedAlert a = (TorrentFinishedAlert) alert;
         System.out.println("Download complete: " + a.handle().name());
         // Notify user, update UI, etc.
     }
 };

 // Register with session manager
 sm.addListener(listener);

Listening to Multiple Event Types: 

 AlertListener listener = new AlertListener() {
     public int[] types() {
         // Listen to multiple alert types
         return new int[] {
             AlertType.TORRENT_FINISHED.swig(),
             AlertType.TORRENT_ERROR.swig(),
             AlertType.PEER_DISCONNECTED.swig()
         };
     }

     public void alert(Alert<?> alert) {
         switch (alert.type()) {
             case TORRENT_FINISHED:
                 handleFinished((TorrentFinishedAlert) alert);
                 break;
             case TORRENT_ERROR:
                 handleError((TorrentErrorAlert) alert);
                 break;
             case PEER_DISCONNECTED:
                 handleDisconnect((PeerDisconnectedAlert) alert);
                 break;
         }
     }
 };

 sm.addListener(listener);

Listening to All Alerts: 

 // Listen to every alert type
 AlertListener universalListener = new AlertListener() {
     public int[] types() {
         return null;  // null means listen to ALL alert types
     }

     public void alert(Alert<?> alert) {
         System.out.println("Alert: " + alert.type() + " - " + alert.message());
         // Debugging, monitoring, or comprehensive event handling
     }
 };

 sm.addListener(universalListener);

Common Alert Types and Patterns: 

 // Torrent lifecycle
 AlertType.ADD_TORRENT           // Torrent added to session
 AlertType.TORRENT_FINISHED      // Download complete
 AlertType.TORRENT_REMOVED       // Torrent removed from session
 AlertType.TORRENT_ERROR         // Torrent encountered an error

 // Network activity
 AlertType.PEER_CONNECTED        // New peer connection established
 AlertType.PEER_DISCONNECTED     // Peer connection lost
 AlertType.STATE_UPDATE          // Periodic torrent status snapshot

 // Metadata and DHT
 AlertType.METADATA_RECEIVED     // Metadata fetched from magnet link
 AlertType.DHT_BOOTSTRAP         // DHT network ready

 // Statistics
 AlertType.SESSION_STATS         // Session-wide statistics update

Thread Safety and Performance:

  • Alert callbacks are invoked from jlibtorrent's internal alert-processing thread
  • Keep alert handlers fast - don't block or do expensive I/O in alert()
  • Use thread-safe collections if accessing shared state from alert callbacks
  • Consider queuing work for a thread pool instead of handling in alert()
  • Use Collections.synchronizedList() or CopyOnWriteArrayList for thread-safe storage

Alert Type Filtering Best Practices: 

 // GOOD: Filter specific types you care about
 public int[] types() {
     return new int[] {
         AlertType.TORRENT_FINISHED.swig(),
         AlertType.STATE_UPDATE.swig()
     };
 }
 // Avoids processing irrelevant alerts, reduces GC pressure

 // LESS EFFICIENT: Listen to everything
 public int[] types() {
     return null;  // Process every single alert
 }
 // Use only for debugging or monitoring all activity

Handling Type-Unsafe Casts: 

 public void alert(Alert<?> alert) {
     // Always verify the alert type before casting
     if (alert.type() == AlertType.TORRENT_FINISHED) {
         TorrentFinishedAlert a = (TorrentFinishedAlert) alert;
         // Now safe to use type-specific methods
     }
 }

Multiple Listeners: 

 // Register multiple independent listeners
 sm.addListener(listener1);  // Handles UI updates
 sm.addListener(listener2);  // Handles database logging
 sm.addListener(listener3);  // Handles notifications

 // Each receives the same alerts independently
 // Order of invocation is not guaranteed
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    alert(Alert<?> alert)
    Invoked when an alert matching this listener's type filter is generated.
    int[]
    types()
    List of alert types this listener wants to receive.

  • Method Details

    • types

      int[] types()
      List of alert types this listener wants to receive.

      Returning specific types filters alerts before they reach your handler, improving performance by avoiding unnecessary callback invocations. Return null to receive all alert types.

      Returns:
      array of alert type codes (from AlertType.X.swig()), or null for all types

    • alert

      void alert(Alert<?> alert)
      Invoked when an alert matching this listener's type filter is generated.

      This method is called from jlibtorrent's internal alert-processing thread, so implementations should be fast and thread-safe. Do not block on I/O, network operations, or locks held by other threads processing alerts.

      Parameters:
      alert - the alert event with type-specific information