Package org.dellroad.stuff.net

Interface Network

All Known Implementing Classes:
ChannelNetwork, TCPNetwork
public interface Network
Abstraction layer representing a "network" over which a local "node" can communicate with remote nodes.

Communication takes the form of sending and receiving arbitrary packets of data known as "messages". Messages are simply sequences of zero or more bytes and are represented by ByteBuffers.

In general, messages may be delayed, dropped or delivered out of order; however, some implementations may provide better guarantees.

Remote nodes are identified by Strings; the interpretation of these Strings is up to the implementation, but typically it is some form of network address.

Incoming messages, along with notifications of output queue status, are delivered to a Network.Handler specified by the application.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    Network.Handler
    Callback interface used by Network implementations.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    send(String peer, ByteBuffer msg)
    Send (or enqueue for sending) a message to a remote peer.
    void
    start(Network.Handler handler)
    Start this instance.
    void
    stop()
    Stop this instance.

  • Method Details

    • start

      void start(Network.Handler handler) throws IOException
      Start this instance.
      Parameters:
      handler - handler for notifications
      Throws:
      IllegalStateException - if already started
      IllegalArgumentException - if handler is null
      IOException - if an error occurs

    • stop

      void stop()
      Stop this instance.

      Does nothing if already stopped.

    • send

      boolean send(String peer, ByteBuffer msg)
      Send (or enqueue for sending) a message to a remote peer.

      If this method returns true, then Handler.outputQueueEmpty() is guaranteed to be invoked with parameter peer at some later point.

      Parameters:
      peer - message destination
      msg - message to send
      Returns:
      true if message was succesfully enqueued for output; false if message failed to be delivered due to local reasons, such as failure to initiate a new connection or output queue overflow
      Throws:
      IllegalArgumentException - if peer cannot be interpreted
      IllegalArgumentException - if peer or msg is null