Package io.github.mahmoudimus.http2

Class FrameWriter

java.lang.Object
io.github.mahmoudimus.http2.FrameWriter
public final class FrameWriter extends Object
Writes HTTP/2 frames to a blocking stream. Each call builds its frames in memory and hands them to the stream in one write, so frames from different threads never interleave as long as callers serialize their calls (this class does no locking; hold a lock, or give one thread the job of writing). Nothing is flushed until flush().

Arguments that would produce a frame the protocol forbids, including a payload larger than the peer's SETTINGS_MAX_FRAME_SIZE, are rejected with IllegalArgumentException before anything is written. writeHeaders(int, byte[], boolean) and writePushPromise(int, int, byte[]) split long field blocks into CONTINUATION frames; DATA is never split, because how much may be sent is a flow-control decision for the caller.

  • Constructor Summary

    Constructors
    Constructor
    Description
    FrameWriter(OutputStream out)
    Creates a writer for the supplied output stream.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    flush()
    Flushes buffered output to the underlying stream.
    int
    maxFrameSize()
    Returns the current frame payload limit.
    void
    setMaxFrameSize(int maxFrameSize)
    The largest payload the peer accepts: its SETTINGS_MAX_FRAME_SIZE (16384 until it says otherwise).
    void
    writeClientPreface()
    Writes the client connection preface; a client then sends its SETTINGS.
    void
    writeData(int streamId, byte[] data, int offset, int length, boolean endStream)
    One DATA frame, unpadded.
    void
    writeFrame(Frame frame)
    Writes one frame exactly as given.
    void
    writeGoAway(int lastStreamId, ErrorCode error, byte[] debugData)
    Writes a connection shutdown frame.
    void
    writeHeaders(int streamId, byte[] fieldBlock, boolean endStream)
    A complete field block: one HEADERS frame, followed by CONTINUATION frames if it is too long for one.
    void
    writePing(boolean ack, long opaqueData)
    Writes a connection PING.
    void
    writePushPromise(int streamId, int promisedStreamId, byte[] fieldBlock)
    A complete PUSH_PROMISE field block, with CONTINUATION frames as needed.
    void
    writeRstStream(int streamId, ErrorCode error)
    Terminates one stream.
    void
    writeSettings(Http2Settings settings)
    Writes the settings that differ from the protocol defaults.
    void
    writeSettings(Map<Integer,Long> values)
    Writes the supplied setting identifiers and values.
    void
    writeSettingsAck()
    Acknowledges the peer SETTINGS.
    void
    writeWindowUpdate(int streamId, int increment)
    Returns flow-control credit to the peer.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • FrameWriter

      public FrameWriter(OutputStream out)
      Creates a writer for the supplied output stream.
      Parameters:
      out - the non-null stream to write

  • Method Details

    • setMaxFrameSize

      public void setMaxFrameSize(int maxFrameSize)
      The largest payload the peer accepts: its SETTINGS_MAX_FRAME_SIZE (16384 until it says otherwise).
      Parameters:
      maxFrameSize - the maximum payload size from 2^14 to 2^24-1 octets

    • maxFrameSize

      public int maxFrameSize()
      Returns the current frame payload limit.
      Returns:
      the maximum payload size in octets

    • writeClientPreface

      public void writeClientPreface() throws IOException
      Writes the client connection preface; a client then sends its SETTINGS.
      Throws:
      IOException - if writing to the underlying stream fails

    • writeFrame

      public void writeFrame(Frame frame) throws IOException
      Writes one frame exactly as given. A HEADERS or PUSH_PROMISE without END_HEADERS must be followed by its CONTINUATION frames, with nothing in between.
      Parameters:
      frame - the frame to serialize
      Throws:
      IOException - if writing to the underlying stream fails

    • writeData

      public void writeData(int streamId, byte[] data, int offset, int length, boolean endStream) throws IOException
      One DATA frame, unpadded.
      Parameters:
      streamId - the nonzero stream identifier
      data - the content byte array
      offset - the first byte to send
      length - the number of bytes to send
      endStream - whether this frame ends the stream
      Throws:
      IOException - if writing to the underlying stream fails

    • writeHeaders

      public void writeHeaders(int streamId, byte[] fieldBlock, boolean endStream) throws IOException
      A complete field block: one HEADERS frame, followed by CONTINUATION frames if it is too long for one.
      Parameters:
      streamId - the nonzero stream identifier
      fieldBlock - the complete HPACK-encoded field block
      endStream - whether the HEADERS frame ends the stream
      Throws:
      IOException - if writing to the underlying stream fails

    • writePushPromise

      public void writePushPromise(int streamId, int promisedStreamId, byte[] fieldBlock) throws IOException
      A complete PUSH_PROMISE field block, with CONTINUATION frames as needed.
      Parameters:
      streamId - the nonzero stream identifier
      promisedStreamId - the nonzero identifier of the promised stream
      fieldBlock - the complete HPACK-encoded field block
      Throws:
      IOException - if writing to the underlying stream fails

    • writeSettings

      public void writeSettings(Http2Settings settings) throws IOException
      Writes the settings that differ from the protocol defaults.
      Parameters:
      settings - the local settings to advertise
      Throws:
      IOException - if writing to the underlying stream fails

    • writeSettings

      public void writeSettings(Map<Integer,Long> values) throws IOException
      Writes the supplied setting identifiers and values.
      Parameters:
      values - the settings to advertise
      Throws:
      IOException - if writing to the underlying stream fails

    • writeSettingsAck

      public void writeSettingsAck() throws IOException
      Acknowledges the peer SETTINGS.
      Throws:
      IOException - if writing to the underlying stream fails

    • writePing

      public void writePing(boolean ack, long opaqueData) throws IOException
      Writes a connection PING.
      Parameters:
      ack - whether to acknowledge a peer PING
      opaqueData - the eight opaque octets as a big-endian long
      Throws:
      IOException - if writing to the underlying stream fails

    • writeGoAway

      public void writeGoAway(int lastStreamId, ErrorCode error, byte[] debugData) throws IOException
      Writes a connection shutdown frame.
      Parameters:
      lastStreamId - the last peer-initiated stream that might have been processed
      error - the shutdown error code
      debugData - diagnostic bytes, or null for none
      Throws:
      IOException - if writing to the underlying stream fails

    • writeRstStream

      public void writeRstStream(int streamId, ErrorCode error) throws IOException
      Terminates one stream.
      Parameters:
      streamId - the nonzero stream identifier
      error - the termination error code
      Throws:
      IOException - if writing to the underlying stream fails

    • writeWindowUpdate

      public void writeWindowUpdate(int streamId, int increment) throws IOException
      Returns flow-control credit to the peer.
      Parameters:
      streamId - the stream identifier, or 0 for the connection
      increment - the positive credit in octets
      Throws:
      IOException - if writing to the underlying stream fails

    • flush

      public void flush() throws IOException
      Flushes buffered output to the underlying stream.
      Throws:
      IOException - if writing to the underlying stream fails