View Javadoc
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   *    https://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<? extends Asn1Container> 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 }