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}