1 /*
2 * Copyright 2013 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.netty.handler.codec.memcache.binary;
17
18 import io.netty.buffer.ByteBuf;
19 import io.netty.handler.codec.memcache.MemcacheMessage;
20 import io.netty.util.internal.UnstableApi;
21
22 /**
23 * An interface that defines a binary Memcache message, providing common properties for
24 * {@link BinaryMemcacheRequest} and {@link BinaryMemcacheResponse}.
25 * <p/>
26 * A {@link BinaryMemcacheMessage} always consists of a header and optional extras or/and
27 * a key.
28 *
29 * @see BinaryMemcacheRequest
30 * @see BinaryMemcacheResponse
31 */
32 @UnstableApi
33 public interface BinaryMemcacheMessage extends MemcacheMessage {
34
35 /**
36 * Returns the magic byte for the message.
37 *
38 * @return the magic byte.
39 */
40 byte magic();
41
42 /**
43 * Sets the magic byte.
44 *
45 * @param magic the magic byte to use.
46 * @see BinaryMemcacheOpcodes for typesafe opcodes.
47 */
48 BinaryMemcacheMessage setMagic(byte magic);
49
50 /**
51 * Returns the opcode for the message.
52 *
53 * @return the opcode.
54 */
55 byte opcode();
56
57 /**
58 * Sets the opcode for the message.
59 *
60 * @param code the opcode to use.
61 */
62 BinaryMemcacheMessage setOpcode(byte code);
63
64 /**
65 * Returns the key length of the message.
66 * <p/>
67 * This may return 0, since the key is optional.
68 *
69 * @return the key length.
70 */
71 short keyLength();
72
73 /**
74 * Return the extras length of the message.
75 * <p/>
76 * This may be 0, since the extras content is optional.
77 *
78 * @return the extras length.
79 */
80 byte extrasLength();
81
82 /**
83 * Returns the data type of the message.
84 *
85 * @return the data type of the message.
86 */
87 byte dataType();
88
89 /**
90 * Sets the data type of the message.
91 *
92 * @param dataType the data type of the message.
93 */
94 BinaryMemcacheMessage setDataType(byte dataType);
95
96 /**
97 * Returns the total body length.
98 * <p/>
99 * Note that this may be 0, since the body is optional.
100 *
101 * @return the total body length.
102 */
103 int totalBodyLength();
104
105 /**
106 * Sets the total body length.
107 * <p/>
108 * Note that this may be 0, since the body length is optional.
109 *
110 * @param totalBodyLength the total body length.
111 */
112 BinaryMemcacheMessage setTotalBodyLength(int totalBodyLength);
113
114 /**
115 * Returns the opaque value.
116 *
117 * @return the opaque value.
118 */
119 int opaque();
120
121 /**
122 * Sets the opaque value.
123 *
124 * @param opaque the opaque value to use.
125 */
126 BinaryMemcacheMessage setOpaque(int opaque);
127
128 /**
129 * Returns the CAS identifier.
130 *
131 * @return the CAS identifier.
132 */
133 long cas();
134
135 /**
136 * Sets the CAS identifier.
137 *
138 * @param cas the CAS identifier to use.
139 */
140 BinaryMemcacheMessage setCas(long cas);
141
142 /**
143 * Returns the optional key of the document.
144 *
145 * @return the key of the document.
146 */
147 ByteBuf key();
148
149 /**
150 * Sets the key of the document. {@link ByteBuf#release()} ownership of {@code key}
151 * is transferred to this {@link BinaryMemcacheMessage}.
152 *
153 * @param key the key of the message. {@link ByteBuf#release()} ownership is transferred
154 * to this {@link BinaryMemcacheMessage}.
155 */
156 BinaryMemcacheMessage setKey(ByteBuf key);
157
158 /**
159 * Returns a {@link ByteBuf} representation of the optional extras.
160 *
161 * @return the optional extras.
162 */
163 ByteBuf extras();
164
165 /**
166 * Sets the extras buffer on the message. {@link ByteBuf#release()} ownership of {@code extras}
167 * is transferred to this {@link BinaryMemcacheMessage}.
168 *
169 * @param extras the extras buffer of the document. {@link ByteBuf#release()} ownership is transferred
170 * to this {@link BinaryMemcacheMessage}.
171 */
172 BinaryMemcacheMessage setExtras(ByteBuf extras);
173
174 /**
175 * Increases the reference count by {@code 1}.
176 */
177 @Override
178 BinaryMemcacheMessage retain();
179
180 /**
181 * Increases the reference count by the specified {@code increment}.
182 */
183 @Override
184 BinaryMemcacheMessage retain(int increment);
185
186 @Override
187 BinaryMemcacheMessage touch();
188
189 @Override
190 BinaryMemcacheMessage touch(Object hint);
191 }