Skip to content

Latest commit

 

History

History
250 lines (196 loc) · 8.04 KB

udp-server.adoc

File metadata and controls

250 lines (196 loc) · 8.04 KB
Raw

UDP Server

Reactor Netty provides the easy-to-use and easy-to-configure UdpServer. It hides most of the Netty functionality that is required to create a UDP server and adds Reactive Streams backpressure.

Starting and Stopping

To start a UDP server, a UdpServer instance has to be created and configured. By default, the host is configured to be localhost and the port is 12012. The following example shows how to create and start a UDP server:

./../../reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/udp/server/create/Application.java
link:./../../reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/udp/server/create/Application.java[role=include]

  1. Creates a UdpServer instance that is ready for configuring.

  2. Starts the server in a blocking fashion and waits for it to finish initializing.

The returned Connection offers a simple server API, including disposeNow(), which shuts the server down in a blocking fashion.

Host and Port

In order to serve on a specific host and port, you can apply the following configuration to the UDP server:

./../../reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/udp/server/address/Application.java
link:./../../reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/udp/server/address/Application.java[role=include]

  1. Configures the UDP server host

  2. Configures the UDP server port

Eager Initialization

By default, the initialization of the UdpServer resources happens on demand. This means that the bind operation absorbs the extra time needed to initialize and load:

  • the event loop group

  • the native transport libraries (when native transport is used)

When you need to preload these resources, you can configure the UdpServer as follows:

./../../reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/udp/server/warmup/Application.java
link:./../../reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/udp/server/warmup/Application.java[role=include]

  1. Initialize and load the event loop group and the native transport libraries

Writing Data

To send data to the remote peer, you must attach an I/O handler. The I/O handler has access to UdpOutbound, to be able to write data. The following example shows how to send hello:

./../../reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/udp/server/send/Application.java
link:./../../reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/udp/server/send/Application.java[role=include]

  1. Sends a hello string to the remote peer

Consuming Data

To receive data from a remote peer, you must attach an I/O handler. The I/O handler has access to UdpInbound, to be able to read data. The following example shows how to consume data:

./../../reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/udp/server/read/Application.java
link:./../../reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/udp/server/read/Application.java[role=include]

  1. Receives data from the remote peer

Lifecycle Callbacks

The following lifecycle callbacks are provided to let you extend the UdpServer:

Callback Description

doOnBind

Invoked when the server channel is about to bind.

doOnBound

Invoked when the server channel is bound.

doOnChannelInit

Invoked when initializing the channel.

doOnUnbound

Invoked when the server channel is unbound.

The following example uses the doOnBound and doOnChannelInit callbacks:

./../../reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/udp/server/lifecycle/Application.java
link:./../../reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/udp/server/lifecycle/Application.java[role=include]

  1. Netty pipeline is extended with LineBasedFrameDecoder when the server channel is bound.

  2. Netty pipeline is extended with LoggingHandler when initializing the channel.

Connection Configuration

This section describes three kinds of configuration that you can use at the UDP level:

Channel Options

By default, the UDP server is configured with the following options:

./../../reactor-netty-core/src/main/java/reactor/netty/udp/UdpServerBind.java
link:./../../reactor-netty-core/src/main/java/reactor/netty/udp/UdpServerBind.java[role=include]

If you need additional options or need to change the current options, you can apply the following configuration:

./../../reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/udp/server/channeloptions/Application.java
link:./../../reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/udp/server/channeloptions/Application.java[role=include]

For more information about Netty channel options, see the following links:

wire-logger.adoc

Event Loop Group

By default, the UDP server uses “Event Loop Group,” where the number of the worker threads equals the number of processors available to the runtime on initialization (but with a minimum value of 4). When you need a different configuration, you can use one of the LoopResource#create methods.

The default configuration for the “Event Loop Group” is the following:

./../../reactor-netty-core/src/main/java/reactor/netty/ReactorNetty.java
link:./../../reactor-netty-core/src/main/java/reactor/netty/ReactorNetty.java[role=include]

If you need changes to these settings, you can apply the following configuration:

./../../reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/udp/server/eventloop/Application.java
link:./../../reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/udp/server/eventloop/Application.java[role=include]

Metrics

The UDP server supports built-in integration with Micrometer. It exposes all metrics with a prefix of reactor.netty.udp.server.

The following table provides information for the UDP server metrics:

metric name type description

reactor.netty.udp.server.data.received

DistributionSummary

Amount of the data received, in bytes

reactor.netty.udp.server.data.sent

DistributionSummary

Amount of the data sent, in bytes

reactor.netty.udp.server.errors

Counter

Number of errors that occurred

These additional metrics are also available:

The following example enables that integration:

./../../reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/udp/server/metrics/Application.java
link:./../../reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/udp/server/metrics/Application.java[role=include]

  1. Enables the built-in integration with Micrometer

When UDP server metrics are needed for an integration with a system other than Micrometer or you want to provide your own integration with Micrometer, you can provide your own metrics recorder, as follows:

./../../reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/udp/server/metrics/custom/Application.java
link:./../../reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/udp/server/metrics/custom/Application.java[role=include]

  1. Enables UDP server metrics and provides ChannelMetricsRecorder implementation.

Unix Domain Sockets

The UdpServer supports Unix Domain Datagram Sockets (UDS) when native transport is in use.

The following example shows how to use UDS support:

./../../reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/udp/server/uds/Application.java
link:./../../reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/udp/server/uds/Application.java[role=include]

  1. Specifies DomainSocketAddress that will be used