io.netty.bootstrap

Class ChannelInitializerExtension

java.lang.Object

io.netty.bootstrap.ChannelInitializerExtension

public abstract class ChannelInitializerExtension
extends Object

A channel initializer extension make it possible to enforce rules and apply modifications across multiple, disconnected uses of Netty within the same JVM process.

For instance, application-level firewall rules can be injected into all uses of Netty within an application, without making changes to such uses that are otherwise outside the purview of the application code, such as 3rd-party libraries.

Channel initializer extensions are not enabled by default, because of their power to influence Netty pipelines across libraries, frameworks, and use-cases. Extensions must be explicitly enabled by setting the "io.netty.bootstrap.extensions" to serviceload.

All channel initializer extensions that are available on the classpath will be service-loaded and used by all AbstractBootstrap subclasses.

Note that this feature will not work for Netty uses that are shaded and relocated into other libraries. The classes in a relocated Netty library are technically distinct and incompatible types. This means the service-loader in non-relocated Netty will not see types from a relocated Netty, and vice versa.

Field Summary

Fields

Modifier and Type	Field and Description
static String	EXTENSIONS_SYSTEM_PROPERTY The name of the system property that control initializer extensions.

Constructor Summary

Constructors

Constructor and Description
ChannelInitializerExtension()

Method Summary

Modifier and Type	Method and Description
void	postInitializeClientChannel(Channel channel) Called by Bootstrap after the initialization of the given client channel.
void	postInitializeServerChildChannel(Channel channel) Called by ServerBootstrap after the initialization of the given child channel.
void	postInitializeServerListenerChannel(ServerChannel channel) Called by ServerBootstrap after the initialization of the given server listener channel.
double	priority() Get the "priority" of this extension.

Methods inherited from class java.lang.Object

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

Field Detail

EXTENSIONS_SYSTEM_PROPERTY

public static final String EXTENSIONS_SYSTEM_PROPERTY

The name of the system property that control initializer extensions.

These extensions can potentially be a security liability, so they are disabled by default.

To enable the extensions, application operators can explicitly opt in by setting this system property to the value serviceload. This will enable all the extensions that are available through the service loader mechanism.

To load and log (at INFO level) all available extensions without actually running them, set this system property to the value log.

See Also:

Constant Field Values

Constructor Detail

ChannelInitializerExtension

public ChannelInitializerExtension()

Method Detail

priority

public double priority()

Get the "priority" of this extension. If multiple extensions are avilable, then they will be called in their priority order, from lowest to highest.

Implementers are encouraged to pick a number between -100.0 and 100.0, where extensions that have no particular opinion on their priority are encouraged to return 0.0.

Extensions with lower priority will get called first, while extensions with greater priority may be able to observe the effects of extensions with lesser priority.

Note that if multiple extensions have the same priority, then their relative order will be unpredictable. As such, implementations should always take into consideration that other extensions might be called before or after them.

Override this method to specify your own priority. The default implementation just returns 0.

Returns:

The priority.

postInitializeClientChannel

public void postInitializeClientChannel(Channel channel)

Called by Bootstrap after the initialization of the given client channel.

The method is allowed to modify the handlers in the pipeline, the channel attributes, or the channel options. The method must refrain from doing any I/O, or from closing the channel.

Override this method to add your own callback logic. The default implementation does nothing.

Parameters:

channel - The channel that was initialized.

postInitializeServerListenerChannel

public void postInitializeServerListenerChannel(ServerChannel channel)

Called by ServerBootstrap after the initialization of the given server listener channel. The listener channel is responsible for invoking the accept(2) system call, and for producing child channels.

The method is allowed to modify the handlers in the pipeline, the channel attributes, or the channel options. The method must refrain from doing any I/O, or from closing the channel.

Override this method to add your own callback logic. The default implementation does nothing.

Parameters:

channel - The channel that was initialized.

postInitializeServerChildChannel

public void postInitializeServerChildChannel(Channel channel)

Called by ServerBootstrap after the initialization of the given child channel. A child channel is a newly established connection from a client to the server.

The method is allowed to modify the handlers in the pipeline, the channel attributes, or the channel options. The method must refrain from doing any I/O, or from closing the channel.

Override this method to add your own callback logic. The default implementation does nothing.

Parameters:

channel - The channel that was initialized.