View Javadoc
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    *   http://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.netty.handler.codec.dns;
17  
18  import io.netty.util.ReferenceCounted;
19  import io.netty.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 }