Interface Packet

All Known Implementing Classes:
BasePacket, EmptyPacket
public interface Packet
Represents the main communication entrypoint for the CloudNet network. Every data which is sent over the network must implement this class in order to indicate that. A packet contains 3 objects, 2 of them are required:
  1. The channel id of the channel to send the packet to, for later identification. (Required)
  2. The data buf, representing the content of the packet which gets transferred. (Required)
  3. The query unique id for identification of the query when a network component responds. (Optional)

A packet channel id must be unique within the network and represents the first identification point when receiving a packet. Each listener for packets, registered via the packet listener registry, uses the id to identify all listeners which must get called in order to process the packet. Later identification in more detail can be made by reading from the content of the buffer.

The query unique id of the packet is only set in two cases, either if the packet sender expects a response from the component to which the packet got sent, or if the packet is a response to a query, in which case the packet unique id should be -1.

Since:
4.0

  • Method Details

    • empty

      @NonNull static @NonNull Packet empty()
      Get a jvm static implementation of a packet which holds no content and is designed to catch read/write activity on those packets by throwing an exception. Normally used by the query manager to complete futures which timed out.
      Returns:
      a jvm static instance of an empty packet.

    • constructResponse

      @NonNull @NonNull Packet constructResponse(@NonNull @NonNull DataBuf content)
      Constructs a new packet as a response to this packet. This is used for query communication where responding to a query is very common. The resulting packet will
      1. have a packet id set to -1 for query identification.
      2. have the same query unique id as this packet has.
      3. have the given content buffer as the content set.
      Parameters:
      content - the content of the response to this packet.
      Returns:
      a new packet representing a response to this packet.
      Throws:
      NullPointerException - if the given content is null.

    • uniqueId

      @Nullable @Nullable UUID uniqueId()
      Get the unique id of this packet. The unique id of the packet is only set when this packet is a query packet and expects a response. In this case the response to this packet should have the packet id set to -1 and the same query unique id as this packet has. Normally a response is constructed by constructResponse(DataBuf).
      Returns:
      the unique id of this packet, or null if this packet is not a query packet.

    • uniqueId

      @Internal void uniqueId(@Nullable @Nullable UUID uniqueId)
      Sets the unique id of this packet. If the unique id is set and the packet is sent the packet will be handled as a query packet. This method should not be used directly to set or change the unique id of a packet. The unique id handling is made by the query manager used to send the packet as a query.
      Parameters:
      uniqueId - the new unique id of this packet or null if this packet is not a query packet.

    • channel

      int channel()
      Get the channel id to which this packet was sent. Listeners can be registered to that channel and will be notified if a packet was received for the specified channel. Each packet id should be unique within the whole network.
      Returns:
      the channel id to which this packet was sent.

    • prioritized

      boolean prioritized()
      Get if this packet is prioritized. If a packet is marked as high priority, it will instantly get handled on the receiving component without getting queued.

      This option should be used with care, as each thread which will normally read from the channel will be blocked with the packet handling of this packet. Blocking the handler thread too long will cause other packets to be delayed for no visible reason.

      Returns:
      if this packet is prioritized.

    • readable

      boolean readable()
      Get if this packet still has readable bytes left. Useful to verify that from a packet can actually be read instead of running into exceptions because the end of the buffer has been reached.
      Returns:
      true if this packet still has data to read, false otherwise.

    • content

      @NonNull @NonNull DataBuf content()
      Get the content of this packet. This method call always returns the same buffer to the caller, handling the buffer release and transactional reading is crucial to not run into exceptions when multiple handlers are handling the same packet.
      Returns:
      the content of this packet.

    • creation

      @NonNull @NonNull Instant creation()
      Get an epoch timestamp of the creation time of this packet. When the packet is created by a decoder, the time will be used as the creation millis. There is no guarantee for this time to be the exact same time as when the packet gets sent to the component, nor when a listener first received the packet.
      Returns:
      the creation timestamp of this packet.