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     * Gets the transition
096     *
097     * @return Returns the transition from the previous state to the new state
098     */
099    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}