1 /*
2 * Copyright 2015 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.handler.codec.dns;
17
18 import io.netty5.util.ReferenceCounted;
19 import io.netty5.util.internal.UnstableApi;
20
21 /**
22 * The superclass which contains core information concerning a {@link DnsQuery} and a {@link DnsResponse}.
23 */
24 @UnstableApi
25 public interface DnsMessage extends ReferenceCounted {
26
27 /**
28 * Returns the {@code ID} of this DNS message.
29 */
30 int id();
31
32 /**
33 * Sets the {@code ID} of this DNS message.
34 */
35 DnsMessage setId(int id);
36
37 /**
38 * Returns the {@code opCode} of this DNS message.
39 */
40 DnsOpCode opCode();
41
42 /**
43 * Sets the {@code opCode} of this DNS message.
44 */
45 DnsMessage setOpCode(DnsOpCode opCode);
46
47 /**
48 * Returns the {@code RD} (recursion desired} field of this DNS message.
49 */
50 boolean isRecursionDesired();
51
52 /**
53 * Sets the {@code RD} (recursion desired} field of this DNS message.
54 */
55 DnsMessage setRecursionDesired(boolean recursionDesired);
56
57 /**
58 * Returns the {@code Z} (reserved for future use) field of this DNS message.
59 */
60 int z();
61
62 /**
63 * Sets the {@code Z} (reserved for future use) field of this DNS message.
64 */
65 DnsMessage setZ(int z);
66
67 /**
68 * Returns the number of records in the specified {@code section} of this DNS message.
69 */
70 int count(DnsSection section);
71
72 /**
73 * Returns the number of records in this DNS message.
74 */
75 int count();
76
77 /**
78 * Returns the first record in the specified {@code section} of this DNS message.
79 * When the specified {@code section} is {@link DnsSection#QUESTION}, the type of the returned record is
80 * always {@link DnsQuestion}.
81 *
82 * @return {@code null} if this message doesn't have any records in the specified {@code section}
83 */
84 <T extends DnsRecord> T recordAt(DnsSection section);
85
86 /**
87 * Returns the record at the specified {@code index} of the specified {@code section} of this DNS message.
88 * When the specified {@code section} is {@link DnsSection#QUESTION}, the type of the returned record is
89 * always {@link DnsQuestion}.
90 *
91 * @throws IndexOutOfBoundsException if the specified {@code index} is out of bounds
92 */
93 <T extends DnsRecord> T recordAt(DnsSection section, int index);
94
95 /**
96 * Sets the specified {@code section} of this DNS message to the specified {@code record},
97 * making it a single-record section. When the specified {@code section} is {@link DnsSection#QUESTION},
98 * the specified {@code record} must be a {@link DnsQuestion}.
99 */
100 DnsMessage setRecord(DnsSection section, DnsRecord record);
101
102 /**
103 * Sets the specified {@code record} at the specified {@code index} of the specified {@code section}
104 * of this DNS message. When the specified {@code section} is {@link DnsSection#QUESTION},
105 * the specified {@code record} must be a {@link DnsQuestion}.
106 *
107 * @return the old record
108 * @throws IndexOutOfBoundsException if the specified {@code index} is out of bounds
109 */
110 <T extends DnsRecord> T setRecord(DnsSection section, int index, DnsRecord record);
111
112 /**
113 * Adds the specified {@code record} at the end of the specified {@code section} of this DNS message.
114 * When the specified {@code section} is {@link DnsSection#QUESTION}, the specified {@code record}
115 * must be a {@link DnsQuestion}.
116 */
117 DnsMessage addRecord(DnsSection section, DnsRecord record);
118
119 /**
120 * Adds the specified {@code record} at the specified {@code index} of the specified {@code section}
121 * of this DNS message. When the specified {@code section} is {@link DnsSection#QUESTION}, the specified
122 * {@code record} must be a {@link DnsQuestion}.
123 *
124 * @throws IndexOutOfBoundsException if the specified {@code index} is out of bounds
125 */
126 DnsMessage addRecord(DnsSection section, int index, DnsRecord record);
127
128 /**
129 * Removes the record at the specified {@code index} of the specified {@code section} from this DNS message.
130 * When the specified {@code section} is {@link DnsSection#QUESTION}, the type of the returned record is
131 * always {@link DnsQuestion}.
132 *
133 * @return the removed record
134 */
135 <T extends DnsRecord> T removeRecord(DnsSection section, int index);
136
137 /**
138 * Removes all the records in the specified {@code section} of this DNS message.
139 */
140 DnsMessage clear(DnsSection section);
141
142 /**
143 * Removes all the records in this DNS message.
144 */
145 DnsMessage clear();
146
147 @Override
148 DnsMessage touch();
149
150 @Override
151 DnsMessage touch(Object hint);
152
153 @Override
154 DnsMessage retain();
155
156 @Override
157 DnsMessage retain(int increment);
158 }