View Javadoc
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    *   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.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 }