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 * Gets the transition
96 *
97 * @return Returns the transition from the previous state to the new state
98 */
99 Enum<?> getTransition();
100
101
102 /**
103 * Updates the transition from a state to another
104 *
105 * @param transition The transition to set
106 */
107 void setTransition( Enum<?> transition );
108
109
110 /**
111 * @return The parent TLV.
112 */
113 TLV getParentTLV();
114
115
116 /**
117 * Sets the parent TLV
118 *
119 * @param parentTLV The new parent TLV
120 */
121 void setParentTLV( TLV parentTLV );
122
123
124 /**
125 * Checks that we can have a end state after this transition
126 *
127 * @return true if this can be the last transition
128 */
129 boolean isGrammarEndAllowed();
130
131
132 /**
133 * Sets the flag to allow a end transition
134 *
135 * @param grammarEndAllowed true or false, depending on the next transition
136 * being an end or not.
137 */
138 void setGrammarEndAllowed( boolean grammarEndAllowed );
139
140
141 /**
142 * Gets a new TLV id
143 * @return a unique value representing the current TLV id
144 */
145 int getNewTlvId();
146
147
148 /**
149 * Gets the current TLV id
150 * @return a unique value representing the current TLV id
151 */
152 int getTlvId();
153
154
155 /**
156 * @return The number of decoded bytes for this message. This is used
157 * to control the PDU size and avoid PDU exceeding the maximum allowed
158 * size to break the server.
159 */
160 int getDecodeBytes();
161
162
163 /**
164 * Increment the decodedBytes by the latest received buffer's size.
165 * @param nb The buffer size.
166 */
167 void incrementDecodeBytes( int nb );
168
169
170 /**
171 * @return The maximum PDU size.
172 */
173 int getMaxPDUSize();
174
175
176 /**
177 * Set the maximum PDU size.
178 * @param maxPDUSize The maximum PDU size (if negative or null, will be
179 * replaced by the max integer value)
180 */
181 void setMaxPDUSize( int maxPDUSize );
182
183
184 /**
185 * Move backward in the stream to the first byte for a given TLV. This is useful when we have
186 * read some Tag and Length in order to define the next transition, and if this transition
187 * do a grammar switch.
188 * @param tlv The TLV to roll-back
189 */
190 void rewind();
191
192
193 /**
194 * Update the parent's length
195 */
196 void updateParent();
197
198
199 /**
200 * @return true if the container should gather the value into itself, false
201 * if the decoding of the Value part should be done immediately for
202 * constructed types.
203 */
204 boolean isGathering();
205
206
207 /**
208 * Set the isGathering flag
209 * @param isGathering true to ask the Asn1Decoder to gather the data
210 * into the container. If not set, the default value is 'false'
211 */
212 void setGathering( boolean isGathering );
213 }