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.shared.asn1.ber;
021
022
023import java.nio.ByteBuffer;
024
025import org.apache.directory.shared.asn1.ber.grammar.Grammar;
026import org.apache.directory.shared.asn1.ber.tlv.TLV;
027import org.apache.directory.shared.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     * Get the current grammar state
055     *
056     * @return Returns the current grammar state
057     */
058    TLVStateEnum getState();
059
060
061    /**
062     * Set the new current state
063     *
064     * @param state The new state
065     */
066    void setState( TLVStateEnum state );
067
068
069    /**
070     * Get the currentTLV
071     *
072     * @return Returns the current TLV being decoded
073     */
074    TLV getCurrentTLV();
075
076
077    /**
078     * Set the current TLV
079     *
080     * @param tlv The current TLV
081     */
082    void setCurrentTLV( TLV tlv );
083
084
085    /**
086     * Get the grammar
087     *
088     * @return Returns the grammar used to decode a LdapMessage.
089     */
090    Grammar getGrammar();
091
092
093    /**
094     * Get the transition
095     *
096     * @return Returns the transition from the previous state to the new state
097     */
098    Enum<?> getTransition();
099
100
101    /**
102     * Update the transition from a state to another
103     *
104     * @param transition The transition to set
105     */
106    void setTransition( Enum<?> transition );
107
108
109    /**
110     * @return get the parent TLV.
111     */
112    TLV getParentTLV();
113
114
115    /**
116     * Set the parent TLV
117     *
118     * @param parentTLV The new parent TLV
119     */
120    void setParentTLV( TLV parentTLV );
121
122
123    /**
124     * Check that we can have a end state after this transition
125     *
126     * @return true if this can be the last transition
127     */
128    boolean isGrammarEndAllowed();
129
130
131    /**
132     * Set the flag to allow a end transition
133     *
134     * @param grammarEndAllowed true or false, depending on the next transition
135     * being an end or not.
136     */
137    void setGrammarEndAllowed( boolean grammarEndAllowed );
138
139
140    /**
141     * Get a new TLV id
142     * @return a unique value representing the current TLV id
143     */
144    int getNewTlvId();
145
146
147    /**
148     * Get the current TLV id
149     * @return a unique value representing the current TLV id
150     */
151    int getTlvId();
152
153
154    /**
155     * @return The number of decoded bytes for this message. This is used
156     * to control the PDU size and avoid PDU exceeding the maximum allowed
157     * size to break the server.
158     */
159    int getDecodeBytes();
160
161
162    /**
163     * Increment the decodedBytes by the latest received buffer's size.
164     * @param nb The buffer size.
165     */
166    void incrementDecodeBytes( int nb );
167
168
169    /**
170     * @return The maximum PDU size.
171     */
172    int getMaxPDUSize();
173
174
175    /**
176     * Set the maximum PDU size.
177     * @param maxPDUSize The maximum PDU size (if negative or null, will be
178     * replaced by the max integer value)
179     */
180    void setMaxPDUSize( int maxPDUSize );
181
182
183    /**
184     * Move backward in the stream to the first byte for a given TLV. This is useful when we have
185     * read some Tag and Length in order to define the next transition, and if this transition
186     * do a grammar switch.
187     * @param tlv The TLV to rollback
188     */
189    void rewind();
190
191
192    /**
193     * Look for the closest parent which has an expected length above 0
194     */
195    void updateParent();
196
197
198    /**
199     * @return true if the container should gather the value into itself, false
200     * if the decoding of the Value part should be done immediately for
201     * constructed types.
202     */
203    boolean isGathering();
204
205
206    /**
207     * Set the isGathering flag
208     * @param isGathering true to ask the Asn1Decoder to gather the data
209     * into the container. If not set, the default value is 'false'
210     */
211    void setGathering( boolean isGathering );
212}