1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 *
19 */
20 package org.apache.directory.api.asn1.ber;
21
22
23 import java.nio.ByteBuffer;
24
25 import org.apache.directory.api.asn1.ber.grammar.Grammar;
26 import org.apache.directory.api.asn1.ber.tlv.TLV;
27 import org.apache.directory.api.asn1.ber.tlv.TLVStateEnum;
28
29
30 /**
31 * Every ASN1 container must implement this interface.
32 *
33 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
34 */
35 public interface Asn1Container
36 {
37 /**
38 * Gets the current stream containing the bytes to decode
39 *
40 * @return The current stream
41 */
42 ByteBuffer getStream();
43
44
45 /**
46 * Stores the Stream being decoded
47 *
48 * @param stream The stream being decoded
49 */
50 void setStream( ByteBuffer stream );
51
52
53 /**
54 * Gets the current grammar state
55 *
56 * @return Returns the current grammar state
57 */
58 TLVStateEnum getState();
59
60
61 /**
62 * Sets the new current state
63 *
64 * @param state The new state
65 */
66 void setState( TLVStateEnum state );
67
68
69 /**
70 * Gets the currentTLV
71 *
72 * @return Returns the current TLV being decoded
73 */
74 TLV getCurrentTLV();
75
76
77 /**
78 * Sets the current TLV
79 *
80 * @param tlv The current TLV
81 */
82 void setCurrentTLV( TLV tlv );
83
84
85 /**
86 * Gets the grammar
87 *
88 * @return Returns the grammar used to decode a LdapMessage.
89 */
90 @SuppressWarnings("rawtypes")
91 Grammar getGrammar();
92
93
94 /**
95 * Sets the grammar
96 *
97 * @param grammar The grammar to set
98 */
99 void setGrammar( Grammar<?> grammar );
100
101
102 /**
103 * Gets the transition
104 *
105 * @return Returns the transition from the previous state to the new state
106 */
107 Enum<?> getTransition();
108
109
110 /**
111 * Updates the transition from a state to another
112 *
113 * @param transition The transition to set
114 */
115 void setTransition( Enum<?> transition );
116
117
118 /**
119 * @return The parent TLV.
120 */
121 TLV getParentTLV();
122
123
124 /**
125 * Sets the parent TLV
126 *
127 * @param parentTLV The new parent TLV
128 */
129 void setParentTLV( TLV parentTLV );
130
131
132 /**
133 * Checks that we can have a end state after this transition
134 *
135 * @return true if this can be the last transition
136 */
137 boolean isGrammarEndAllowed();
138
139
140 /**
141 * Sets the flag to allow a end transition
142 *
143 * @param grammarEndAllowed true or false, depending on the next transition
144 * being an end or not.
145 */
146 void setGrammarEndAllowed( boolean grammarEndAllowed );
147
148
149 /**
150 * Gets a new TLV id
151 * @return a unique value representing the current TLV id
152 */
153 int getNewTlvId();
154
155
156 /**
157 * Gets the current TLV id
158 * @return a unique value representing the current TLV id
159 */
160 int getTlvId();
161
162
163 /**
164 * @return The number of decoded bytes for this message. This is used
165 * to control the PDU size and avoid PDU exceeding the maximum allowed
166 * size to break the server.
167 */
168 int getDecodedBytes();
169
170
171 /**
172 * @param decodedBytes The number of decoded bytes for this message.
173 */
174 void setDecodedBytes( int decodedBytes );
175
176
177 /**
178 * Increment the decodedBytes by the latest received buffer's size.
179 * @param nb The buffer size.
180 */
181 void incrementDecodedBytes( int nb );
182
183
184 /**
185 * @return The maximum PDU size.
186 */
187 int getMaxPDUSize();
188
189
190 /**
191 * Set the maximum PDU size.
192 * @param maxPDUSize The maximum PDU size (if negative or null, will be
193 * replaced by the max integer value)
194 */
195 void setMaxPDUSize( int maxPDUSize );
196
197
198 /**
199 * Move backward in the stream to the first byte for a given TLV. This is useful when we have
200 * read some Tag and Length in order to define the next transition, and if this transition
201 * do a grammar switch.
202 */
203 void rewind();
204
205
206 /**
207 * Update the parent's length
208 */
209 void updateParent();
210
211
212 /**
213 * @return true if the container should gather the value into itself, false
214 * if the decoding of the Value part should be done immediately for
215 * constructed types.
216 */
217 boolean isGathering();
218
219
220 /**
221 * Set the isGathering flag
222 * @param isGathering true to ask the Asn1Decoder to gather the data
223 * into the container. If not set, the default value is 'false'
224 */
225 void setGathering( boolean isGathering );
226 }