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<? 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}