001/*
002 *  Licensed to the Apache Software Foundation (ASF) under one
003 *  or more contributor license agreements.  See the NOTICE file
004 *  distributed with this work for additional information
005 *  regarding copyright ownership.  The ASF licenses this file
006 *  to you under the Apache License, Version 2.0 (the
007 *  "License"); you may not use this file except in compliance
008 *  with the License.  You may obtain a copy of the License at
009 *
010 *    http://www.apache.org/licenses/LICENSE-2.0
011 *
012 *  Unless required by applicable law or agreed to in writing,
013 *  software distributed under the License is distributed on an
014 *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 *  KIND, either express or implied.  See the License for the
016 *  specific language governing permissions and limitations
017 *  under the License.
018 *
019 */
020package org.apache.directory.api.asn1.ber;
021
022
023import java.nio.ByteBuffer;
024
025import org.apache.directory.api.asn1.ber.grammar.Grammar;
026import org.apache.directory.api.asn1.ber.tlv.TLV;
027import org.apache.directory.api.asn1.ber.tlv.TLVStateEnum;
028
029
030/**
031 * Every ASN1 container must implement this interface.
032 *
033 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
034 */
035public interface Asn1Container
036{
037    /**
038     * Gets the current stream containing the bytes to decode
039     *
040     * @return The current stream
041     */
042    ByteBuffer getStream();
043
044
045    /**
046     * Stores the Stream being decoded
047     *
048     * @param stream The stream being decoded
049     */
050    void setStream( ByteBuffer stream );
051
052
053    /**
054     * Gets the current grammar state
055     *
056     * @return Returns the current grammar state
057     */
058    TLVStateEnum getState();
059
060
061    /**
062     * Sets the new current state
063     *
064     * @param state The new state
065     */
066    void setState( TLVStateEnum state );
067
068
069    /**
070     * Gets the currentTLV
071     *
072     * @return Returns the current TLV being decoded
073     */
074    TLV getCurrentTLV();
075
076
077    /**
078     * Sets the current TLV
079     *
080     * @param tlv The current TLV
081     */
082    void setCurrentTLV( TLV tlv );
083
084
085    /**
086     * Gets the grammar
087     *
088     * @return Returns the grammar used to decode a LdapMessage.
089     */
090    @SuppressWarnings("rawtypes")
091    Grammar getGrammar();
092
093
094    /**
095     * Sets the grammar
096     *
097     * @param grammar The grammar to set
098     */
099    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}