/*
* Copyright (C) 2012-2015 DataStax Inc.
*
* Licensed 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 com.datastax.driver.core;
import io.netty.bootstrap.Bootstrap;
import io.netty.buffer.PooledByteBufAllocator;
import io.netty.channel.ChannelOption;
import io.netty.channel.EventLoopGroup;
import io.netty.channel.socket.SocketChannel;
import io.netty.util.HashedWheelTimer;
import io.netty.util.Timer;
import java.util.concurrent.ThreadFactory;
/**
* A set of hooks that allow clients to customize the driver's underlying Netty layer.
* <p/>
* Clients that need to hook into the driver's underlying Netty layer can
* subclass this class and provide the necessary customization by overriding
* its methods.
* <p/>
* Typically, clients would register this class with {@link Cluster#builder()}:
* <p/>
* <pre>
* NettyOptions nettyOptions = ...
* Cluster cluster = Cluster.builder()
* .addContactPoint(...)
* .withNettyOptions(nettyOptions)
* .build();
* </pre>
* <p/>
* <strong>Extending the NettyOptions API</strong>
* <p/>
* Contrary to other driver options, the options available in this class should
* be considered as advanced features and as such, <em>they should only be
* modified by expert users</em>.
* <p/>
* <strong>A misconfiguration introduced by the means of this API can have unexpected results
* and cause the driver to completely fail to connect.</strong>
* <p/>
* Moreover, since versions 2.0.9 and 2.1.4 (see JAVA-538),
* the driver is available in two different flavors: with a standard Maven dependency on Netty,
* or with a "shaded" (internalized) Netty dependency.
* <p/>
* Given that NettyOptions API exposes Netty classes ({@link SocketChannel}, etc.),
* <em>it should only be extended by clients using the non-shaded
* version of driver</em>.
* <p/>
* <strong>Extending this API with shaded Netty classes is not supported,
* and in particular for OSGi applications, it is likely that such a configuration would lead to
* compile and/or runtime errors.</strong>
*
* @since 2.0.10
*/
public class NettyOptions {
/**
* The default instance of {@link NettyOptions} to use.
*/
public static final NettyOptions DEFAULT_INSTANCE = new NettyOptions();
/**
* Return the {@code EventLoopGroup} instance to use.
* <p/>
* This hook is invoked only once at {@link Cluster} initialization;
* the returned instance will be kept in use throughout the cluster lifecycle.
* <p/>
* Typically, implementors would return a newly-created instance;
* it is however possible to re-use a shared instance, but in this
* case implementors should also override {@link #onClusterClose(EventLoopGroup)}
* to prevent the shared instance to be closed when the cluster is closed.
* <p/>
* The default implementation returns a new instance of {@code io.netty.channel.epoll.EpollEventLoopGroup}
* if {@link NettyUtil#isEpollAvailable() epoll is available},
* or {@code io.netty.channel.nio.NioEventLoopGroup} otherwise.
*
* @param threadFactory The {@link ThreadFactory} to use when creating a new {@code EventLoopGroup} instance;
* The driver will provide its own internal thread factory here.
* It is safe to ignore it and use another thread factory. Note however that for optimal
* performance it is recommended to use a factory that returns
* {@link io.netty.util.concurrent.FastThreadLocalThread} instances (such as Netty's
* {@link java.util.concurrent.Executors.DefaultThreadFactory}).
* @return the {@code EventLoopGroup} instance to use.
*/
public EventLoopGroup eventLoopGroup(ThreadFactory threadFactory) {
return NettyUtil.newEventLoopGroupInstance(threadFactory);
}
/**
* Return the specific {@code SocketChannel} subclass to use.
* <p/>
* This hook is invoked only once at {@link Cluster} initialization;
* the returned instance will then be used each time the driver creates a new {@link Connection}
* and configures a new instance of {@link Bootstrap} for it.
* <p/>
* The default implementation returns {@code io.netty.channel.epoll.EpollSocketChannel} if {@link NettyUtil#isEpollAvailable() epoll is available},
* or {@code io.netty.channel.socket.nio.NioSocketChannel} otherwise.
*
* @return The {@code SocketChannel} subclass to use.
*/
public Class<? extends SocketChannel> channelClass() {
return NettyUtil.channelClass();
}
/**
* Hook invoked each time the driver creates a new {@link Connection}
* and configures a new instance of {@link Bootstrap} for it.
* <p/>
* This hook is guaranteed to be called <em>after</em> the driver has applied all
* {@link SocketOptions}s.
* <p/>
* This is a good place to add extra {@link io.netty.channel.ChannelHandler ChannelOption}s to the boostrap; e.g.
* plug a custom {@link io.netty.buffer.ByteBufAllocator ByteBufAllocator} implementation:
* <p/>
* <pre>
* ByteBufAllocator myCustomByteBufAllocator = ...
*
* public void afterBootstrapInitialized(Bootstrap bootstrap) {
* bootstrap.option(ChannelOption.ALLOCATOR, myCustomByteBufAllocator);
* }
* </pre>
* <p/>
* Note that the default implementation of this method configures a pooled {@code ByteBufAllocator} (Netty 4.0
* defaults to unpooled). If you override this method to set unrelated options, make sure you call
* {@code super.afterBootstrapInitialized(bootstrap)}.
*
* @param bootstrap the {@link Bootstrap} being initialized.
*/
public void afterBootstrapInitialized(Bootstrap bootstrap) {
// In Netty 4.1.x, pooled will be the default, so this won't be necessary anymore
bootstrap.option(ChannelOption.ALLOCATOR, PooledByteBufAllocator.DEFAULT);
}
/**
* Hook invoked each time the driver creates a new {@link Connection}
* and initializes the {@link SocketChannel channel}.
* <p/>
* This hook is guaranteed to be called <em>after</em> the driver has registered
* all its internal channel handlers, and applied the configured {@link SSLOptions}, if any.
* <p/>
* This is a good place to add extra {@link io.netty.channel.ChannelHandler ChannelHandler}s
* to the channel's pipeline; e.g. to add a custom SSL handler to the beginning of the handler chain,
* do the following:
* <p/>
* <pre>
* ChannelPipeline pipeline = channel.pipeline();
* SSLEngine myCustomSSLEngine = ...
* SslHandler myCustomSSLHandler = new SslHandler(myCustomSSLEngine);
* pipeline.addFirst("ssl", myCustomSSLHandler);
* </pre>
* <p/>
* Note: if you intend to provide your own SSL implementation,
* do not enable the driver's built-in {@link SSLOptions} at the same time.
*
* @param channel the {@link SocketChannel} instance, after being initialized by the driver.
* @throws Exception if this methods encounters any errors.
*/
public void afterChannelInitialized(SocketChannel channel) throws Exception {
//noop
}
/**
* Hook invoked when the cluster is shutting down after a call to {@link Cluster#close()}.
* <p/>
* This is guaranteed to be called only after all connections have been individually
* closed, and their channels closed, and only once per {@link EventLoopGroup} instance.
* <p/>
* This gives the implementor a chance to close the {@link EventLoopGroup} properly, if required.
* <p/>
* The default implementation initiates a {@link EventLoopGroup#shutdownGracefully() graceful shutdown}
* of the passed {@link EventLoopGroup}, then waits uninterruptibly for the shutdown to complete or timeout.
* <p/>
* Implementation note: if the {@link EventLoopGroup} instance is being shared, or used for other purposes than to
* coordinate Netty events for the current cluster, then it should not be shut down here;
* subclasses would have to override this method accordingly to take the appropriate action.
*
* @param eventLoopGroup the event loop group used by the cluster being closed
*/
public void onClusterClose(EventLoopGroup eventLoopGroup) {
eventLoopGroup.shutdownGracefully().syncUninterruptibly();
}
/**
* Return the {@link Timer} instance used by Read Timeouts and Speculative Execution.
* <p/>
* This hook is invoked only once at {@link Cluster} initialization;
* the returned instance will be kept in use throughout the cluster lifecycle.
* <p/>
* Typically, implementors would return a newly-created instance;
* it is however possible to re-use a shared instance, but in this
* case implementors should also override {@link #onClusterClose(Timer)}
* to prevent the shared instance to be closed when the cluster is closed.
* <p/>
* The default implementation returns a new instance created by {@link HashedWheelTimer#HashedWheelTimer(ThreadFactory)}.
*
* @param threadFactory The {@link ThreadFactory} to use when creating a new {@link HashedWheelTimer} instance;
* The driver will provide its own internal thread factory here.
* It is safe to ignore it and use another thread factory. Note however that for optimal
* performance it is recommended to use a factory that returns
* {@link io.netty.util.concurrent.FastThreadLocalThread} instances (such as Netty's
* {@link java.util.concurrent.Executors.DefaultThreadFactory}).
* @return the {@link Timer} instance to use.
*/
public Timer timer(ThreadFactory threadFactory) {
return new HashedWheelTimer(threadFactory);
}
/**
* Hook invoked when the cluster is shutting down after a call to {@link Cluster#close()}.
* <p/>
* This is guaranteed to be called only after all connections have been individually
* closed, and their channels closed, and only once per {@link Timer} instance.
* <p/>
* This gives the implementor a chance to close the {@link Timer} properly, if required.
* <p/>
* The default implementation calls a {@link Timer#stop()} of the passed {@link Timer} instance.
* <p/>
* Implementation note: if the {@link Timer} instance is being shared, or used for other purposes than to
* schedule actions for the current cluster, than it should not be stopped here;
* subclasses would have to override this method accordingly to take the appropriate action.
*
* @param timer the timer used by the cluster being closed
*/
public void onClusterClose(Timer timer) {
timer.stop();
}
}