/*
* Copyright 2012 The Netty Project
*
* The Netty Project licenses this file to you under the Apache License,
* version 2.0 (the "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at:
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations
* under the License.
*/
package io.netty.channel;
import io.netty.buffer.ByteBufAllocator;
import io.netty.channel.socket.SocketChannelConfig;
import java.nio.ByteBuffer;
import java.nio.channels.WritableByteChannel;
import java.util.Map;
A set of configuration properties of a Channel
. Please down-cast to more specific configuration type such as SocketChannelConfig
or use setOptions(Map<ChannelOption<?>,?>)
to set the transport-specific properties:
Channel
ch = ...; SocketChannelConfig
cfg = (SocketChannelConfig
) ch.getConfig();
cfg.setTcpNoDelay(false);
Option map
An option map property is a dynamic write-only property which allows the configuration of a Channel
without down-casting its associated ChannelConfig
. To update an option map, please call setOptions(Map<ChannelOption<?>,?>)
. All ChannelConfig
has the following options:
More options are available in the sub-types of ChannelConfig
. For example, you can configure the parameters which are specific to a TCP/IP socket as explained in SocketChannelConfig
.
/**
* A set of configuration properties of a {@link Channel}.
* <p>
* Please down-cast to more specific configuration type such as
* {@link SocketChannelConfig} or use {@link #setOptions(Map)} to set the
* transport-specific properties:
* <pre>
* {@link Channel} ch = ...;
* {@link SocketChannelConfig} cfg = <strong>({@link SocketChannelConfig}) ch.getConfig();</strong>
* cfg.setTcpNoDelay(false);
* </pre>
*
* <h3>Option map</h3>
*
* An option map property is a dynamic write-only property which allows
* the configuration of a {@link Channel} without down-casting its associated
* {@link ChannelConfig}. To update an option map, please call {@link #setOptions(Map)}.
* <p>
* All {@link ChannelConfig} has the following options:
*
* <table border="1" cellspacing="0" cellpadding="6">
* <tr>
* <th>Name</th><th>Associated setter method</th>
* </tr><tr>
* <td>{@link ChannelOption#CONNECT_TIMEOUT_MILLIS}</td><td>{@link #setConnectTimeoutMillis(int)}</td>
* </tr><tr>
* <td>{@link ChannelOption#WRITE_SPIN_COUNT}</td><td>{@link #setWriteSpinCount(int)}</td>
* </tr><tr>
* <td>{@link ChannelOption#WRITE_BUFFER_WATER_MARK}</td><td>{@link #setWriteBufferWaterMark(WriteBufferWaterMark)}</td>
* </tr><tr>
* <td>{@link ChannelOption#ALLOCATOR}</td><td>{@link #setAllocator(ByteBufAllocator)}</td>
* </tr><tr>
* <td>{@link ChannelOption#AUTO_READ}</td><td>{@link #setAutoRead(boolean)}</td>
* </tr>
* </table>
* <p>
* More options are available in the sub-types of {@link ChannelConfig}. For
* example, you can configure the parameters which are specific to a TCP/IP
* socket as explained in {@link SocketChannelConfig}.
*/
public interface ChannelConfig {
Return all set ChannelOption
's. /**
* Return all set {@link ChannelOption}'s.
*/
Map<ChannelOption<?>, Object> getOptions();
Sets the configuration properties from the specified Map
. /**
* Sets the configuration properties from the specified {@link Map}.
*/
boolean setOptions(Map<ChannelOption<?>, ?> options);
Return the value of the given ChannelOption
/**
* Return the value of the given {@link ChannelOption}
*/
<T> T getOption(ChannelOption<T> option);
Sets a configuration property with the specified name and value.
To override this method properly, you must call the super class:
public boolean setOption(ChannelOption<T> option, T value) {
if (super.setOption(option, value)) {
return true;
}
if (option.equals(additionalOption)) {
....
return true;
}
return false;
}
Returns: true
if and only if the property has been set
/**
* Sets a configuration property with the specified name and value.
* To override this method properly, you must call the super class:
* <pre>
* public boolean setOption(ChannelOption<T> option, T value) {
* if (super.setOption(option, value)) {
* return true;
* }
*
* if (option.equals(additionalOption)) {
* ....
* return true;
* }
*
* return false;
* }
* </pre>
*
* @return {@code true} if and only if the property has been set
*/
<T> boolean setOption(ChannelOption<T> option, T value);
Returns the connect timeout of the channel in milliseconds. If the Channel
does not support connect operation, this property is not used at all, and therefore will be ignored. Returns: the connect timeout in milliseconds. 0
if disabled.
/**
* Returns the connect timeout of the channel in milliseconds. If the
* {@link Channel} does not support connect operation, this property is not
* used at all, and therefore will be ignored.
*
* @return the connect timeout in milliseconds. {@code 0} if disabled.
*/
int getConnectTimeoutMillis();
Sets the connect timeout of the channel in milliseconds. If the Channel
does not support connect operation, this property is not used at all, and therefore will be ignored. Params: - connectTimeoutMillis – the connect timeout in milliseconds.
0
to disable.
/**
* Sets the connect timeout of the channel in milliseconds. If the
* {@link Channel} does not support connect operation, this property is not
* used at all, and therefore will be ignored.
*
* @param connectTimeoutMillis the connect timeout in milliseconds.
* {@code 0} to disable.
*/
ChannelConfig setConnectTimeoutMillis(int connectTimeoutMillis);
Deprecated: Use MaxMessagesRecvByteBufAllocator
Returns the maximum number of messages to read per read loop. a channelRead()
event. If this value is greater than 1, an event loop might attempt to read multiple times to procure multiple messages.
/**
* @deprecated Use {@link MaxMessagesRecvByteBufAllocator}
* <p>
* Returns the maximum number of messages to read per read loop.
* a {@link ChannelInboundHandler#channelRead(ChannelHandlerContext, Object) channelRead()} event.
* If this value is greater than 1, an event loop might attempt to read multiple times to procure multiple messages.
*/
@Deprecated
int getMaxMessagesPerRead();
Deprecated: Use MaxMessagesRecvByteBufAllocator
Sets the maximum number of messages to read per read loop.
If this value is greater than 1, an event loop might attempt to read multiple times to procure multiple messages.
/**
* @deprecated Use {@link MaxMessagesRecvByteBufAllocator}
* <p>
* Sets the maximum number of messages to read per read loop.
* If this value is greater than 1, an event loop might attempt to read multiple times to procure multiple messages.
*/
@Deprecated
ChannelConfig setMaxMessagesPerRead(int maxMessagesPerRead);
Returns the maximum loop count for a write operation until WritableByteChannel.write(ByteBuffer)
returns a non-zero value. It is similar to what a spin lock is used for in concurrency programming. It improves memory utilization and write throughput depending on the platform that JVM runs on. The default value is 16
. /**
* Returns the maximum loop count for a write operation until
* {@link WritableByteChannel#write(ByteBuffer)} returns a non-zero value.
* It is similar to what a spin lock is used for in concurrency programming.
* It improves memory utilization and write throughput depending on
* the platform that JVM runs on. The default value is {@code 16}.
*/
int getWriteSpinCount();
Sets the maximum loop count for a write operation until WritableByteChannel.write(ByteBuffer)
returns a non-zero value. It is similar to what a spin lock is used for in concurrency programming. It improves memory utilization and write throughput depending on the platform that JVM runs on. The default value is 16
. Throws: - IllegalArgumentException – if the specified value is
0
or less than 0
/**
* Sets the maximum loop count for a write operation until
* {@link WritableByteChannel#write(ByteBuffer)} returns a non-zero value.
* It is similar to what a spin lock is used for in concurrency programming.
* It improves memory utilization and write throughput depending on
* the platform that JVM runs on. The default value is {@code 16}.
*
* @throws IllegalArgumentException
* if the specified value is {@code 0} or less than {@code 0}
*/
ChannelConfig setWriteSpinCount(int writeSpinCount);
Returns ByteBufAllocator
which is used for the channel to allocate buffers. /**
* Returns {@link ByteBufAllocator} which is used for the channel
* to allocate buffers.
*/
ByteBufAllocator getAllocator();
Set the ByteBufAllocator
which is used for the channel to allocate buffers. /**
* Set the {@link ByteBufAllocator} which is used for the channel
* to allocate buffers.
*/
ChannelConfig setAllocator(ByteBufAllocator allocator);
Returns RecvByteBufAllocator
which is used for the channel to allocate receive buffers. /**
* Returns {@link RecvByteBufAllocator} which is used for the channel to allocate receive buffers.
*/
<T extends RecvByteBufAllocator> T getRecvByteBufAllocator();
Set the RecvByteBufAllocator
which is used for the channel to allocate receive buffers. /**
* Set the {@link RecvByteBufAllocator} which is used for the channel to allocate receive buffers.
*/
ChannelConfig setRecvByteBufAllocator(RecvByteBufAllocator allocator);
Returns true
if and only if ChannelHandlerContext.read()
will be invoked automatically so that a user application doesn't need to call it at all. The default value is true
. /**
* Returns {@code true} if and only if {@link ChannelHandlerContext#read()} will be invoked automatically so that
* a user application doesn't need to call it at all. The default value is {@code true}.
*/
boolean isAutoRead();
Sets if ChannelHandlerContext.read()
will be invoked automatically so that a user application doesn't need to call it at all. The default value is true
. /**
* Sets if {@link ChannelHandlerContext#read()} will be invoked automatically so that a user application doesn't
* need to call it at all. The default value is {@code true}.
*/
ChannelConfig setAutoRead(boolean autoRead);
Deprecated: Auto close will be removed in a future release. Returns true
if and only if the Channel
will be closed automatically and immediately on write failure. The default is false
.
/**
* @deprecated Auto close will be removed in a future release.
*
* Returns {@code true} if and only if the {@link Channel} will be closed automatically and immediately on
* write failure. The default is {@code false}.
*/
@Deprecated
boolean isAutoClose();
Deprecated: Auto close will be removed in a future release. Sets whether the Channel
should be closed automatically and immediately on write failure. The default is false
.
/**
* @deprecated Auto close will be removed in a future release.
*
* Sets whether the {@link Channel} should be closed automatically and immediately on write failure.
* The default is {@code false}.
*/
@Deprecated
ChannelConfig setAutoClose(boolean autoClose);
Returns the high water mark of the write buffer. If the number of bytes queued in the write buffer exceeds this value, Channel.isWritable()
will start to return false
. /**
* Returns the high water mark of the write buffer. If the number of bytes
* queued in the write buffer exceeds this value, {@link Channel#isWritable()}
* will start to return {@code false}.
*/
int getWriteBufferHighWaterMark();
Sets the high water mark of the write buffer. If the number of bytes queued in the write buffer exceeds this value, Channel.isWritable()
will start to return false
.
/**
* <p>
* Sets the high water mark of the write buffer. If the number of bytes
* queued in the write buffer exceeds this value, {@link Channel#isWritable()}
* will start to return {@code false}.
*/
ChannelConfig setWriteBufferHighWaterMark(int writeBufferHighWaterMark);
Returns the low water mark of the write buffer. Once the number of bytes queued in the write buffer exceeded the high water mark and then dropped down below this value, Channel.isWritable()
will start to return true
again. /**
* Returns the low water mark of the write buffer. Once the number of bytes
* queued in the write buffer exceeded the
* {@linkplain #setWriteBufferHighWaterMark(int) high water mark} and then
* dropped down below this value, {@link Channel#isWritable()} will start to return
* {@code true} again.
*/
int getWriteBufferLowWaterMark();
Sets the low water mark of the write buffer. Once the number of bytes queued in the write buffer exceeded the high water mark and then dropped down below this value, Channel.isWritable()
will start to return true
again.
/**
* <p>
* Sets the low water mark of the write buffer. Once the number of bytes
* queued in the write buffer exceeded the
* {@linkplain #setWriteBufferHighWaterMark(int) high water mark} and then
* dropped down below this value, {@link Channel#isWritable()} will start to return
* {@code true} again.
*/
ChannelConfig setWriteBufferLowWaterMark(int writeBufferLowWaterMark);
Returns MessageSizeEstimator
which is used for the channel to detect the size of a message. /**
* Returns {@link MessageSizeEstimator} which is used for the channel
* to detect the size of a message.
*/
MessageSizeEstimator getMessageSizeEstimator();
Set the MessageSizeEstimator
which is used for the channel to detect the size of a message. /**
* Set the {@link MessageSizeEstimator} which is used for the channel
* to detect the size of a message.
*/
ChannelConfig setMessageSizeEstimator(MessageSizeEstimator estimator);
Returns the WriteBufferWaterMark
which is used for setting the high and low water mark of the write buffer. /**
* Returns the {@link WriteBufferWaterMark} which is used for setting the high and low
* water mark of the write buffer.
*/
WriteBufferWaterMark getWriteBufferWaterMark();
Set the WriteBufferWaterMark
which is used for setting the high and low water mark of the write buffer. /**
* Set the {@link WriteBufferWaterMark} which is used for setting the high and low
* water mark of the write buffer.
*/
ChannelConfig setWriteBufferWaterMark(WriteBufferWaterMark writeBufferWaterMark);
}