1 /*
2 * Copyright 2012 The Netty Project
3 *
4 * The Netty Project licenses this file to you under the Apache License,
5 * version 2.0 (the "License"); you may not use this file except in compliance
6 * with the License. You may obtain a copy of the License at:
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations
14 * under the License.
15 */
16 package io.netty5.channel;
17
18 import io.netty5.buffer.api.Buffer;
19 import io.netty5.buffer.api.BufferAllocator;
20
21 /**
22 * Enables a {@link ChannelHandler} to interact with its {@link ChannelPipeline}
23 * and other handlers. Among other things a handler can notify the next {@link ChannelHandler} in the
24 * {@link ChannelPipeline} as well as modify the {@link ChannelPipeline} it belongs to dynamically.
25 *
26 * <h3>Notify</h3>
27 *
28 * You can notify the closest handler in the same {@link ChannelPipeline} by calling one of the various methods
29 * provided here.
30 * Please refer to {@link ChannelPipeline} to understand how an event flows.
31 *
32 * <h3>Modifying a pipeline</h3>
33 *
34 * You can get the {@link ChannelPipeline} your handler belongs to by calling
35 * {@link #pipeline()}. A non-trivial application could insert, remove, or
36 * replace handlers in the pipeline dynamically at runtime.
37 *
38 * <h3>Retrieving for later use</h3>
39 *
40 * You can keep the {@link ChannelHandlerContext} for later use, such as
41 * triggering an event outside the handler methods, even from a different thread.
42 * <pre>
43 * public class MyHandler extends {@link ChannelHandler} {
44 *
45 * <b>private {@link ChannelHandlerContext} ctx;</b>
46 *
47 * public void handlerAdded({@link ChannelHandlerContext} ctx) {
48 * <b>this.ctx = ctx;</b>
49 * }
50 *
51 * public void login(String username, password) {
52 * ctx.write(new LoginMessage(username, password));
53 * }
54 * ...
55 * }
56 * </pre>
57 *
58 * <h3>A handler can have more than one context</h3>
59 *
60 * Please note that a {@link ChannelHandler} instance can be added to more than
61 * one {@link ChannelPipeline}. It means a single {@link ChannelHandler}
62 * instance can have more than one {@link ChannelHandlerContext} and therefore
63 * the single instance can be invoked with different
64 * {@link ChannelHandlerContext}s if it is added to one or more
65 * {@link ChannelPipeline}s more than once.
66 *
67 * <h3>Additional resources worth reading</h3>
68 * <p>
69 * Please refer to the {@link ChannelHandler}, and
70 * {@link ChannelPipeline} to find out more about inbound and outbound operations,
71 * what fundamental differences they have, how they flow in a pipeline, and how to handle
72 * the operation in your application.
73 */
74 public interface ChannelHandlerContext extends ChannelInboundInvoker, ChannelOutboundInvoker {
75
76 /**
77 * Return the {@link Channel} which is bound to the {@link ChannelHandlerContext}.
78 */
79 default Channel channel() {
80 return pipeline().channel();
81 }
82
83 /**
84 * The unique name of the {@link ChannelHandlerContext}.The name was used when then {@link ChannelHandler}
85 * was added to the {@link ChannelPipeline}. This name can also be used to access the registered
86 * {@link ChannelHandler} from the {@link ChannelPipeline}.
87 */
88 String name();
89
90 /**
91 * The {@link ChannelHandler} that is bound this {@link ChannelHandlerContext}.
92 */
93 ChannelHandler handler();
94
95 /**
96 * Return {@code true} if the {@link ChannelHandler} which belongs to this context was removed
97 * from the {@link ChannelPipeline}.
98 */
99 boolean isRemoved();
100
101 @Override
102 ChannelHandlerContext fireChannelRegistered();
103
104 @Override
105 ChannelHandlerContext fireChannelUnregistered();
106
107 @Override
108 ChannelHandlerContext fireChannelActive();
109
110 @Override
111 ChannelHandlerContext fireChannelInactive();
112
113 @Override
114 ChannelHandlerContext fireChannelShutdown(ChannelShutdownDirection direction);
115
116 @Override
117 ChannelHandlerContext fireChannelExceptionCaught(Throwable cause);
118
119 @Override
120 ChannelHandlerContext fireChannelInboundEvent(Object evt);
121
122 @Override
123 ChannelHandlerContext fireChannelRead(Object msg);
124
125 @Override
126 ChannelHandlerContext fireChannelReadComplete();
127
128 @Override
129 ChannelHandlerContext fireChannelWritabilityChanged();
130
131 @Override
132 ChannelHandlerContext read();
133
134 @Override
135 ChannelHandlerContext flush();
136
137 /**
138 * Return the assigned {@link ChannelPipeline}
139 */
140 ChannelPipeline pipeline();
141
142 /**
143 * Return the assigned {@link BufferAllocator} which will be used to allocate {@link Buffer}s.
144 */
145 default BufferAllocator bufferAllocator() {
146 return channel().bufferAllocator();
147 }
148 }