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}