org.apache.asn1.ber
Class BERDecoder

java.lang.Object
  extended by org.apache.asn1.ber.BERDecoder
All Implemented Interfaces:
org.apache.asn1.codec.stateful.DecoderCallback, org.apache.asn1.codec.stateful.StatefulDecoder

public class BERDecoder
extends java.lang.Object
implements org.apache.asn1.codec.stateful.StatefulDecoder, org.apache.asn1.codec.stateful.DecoderCallback

A decoder that decodes BER encoded bytes to Tag Value Length (TLV) tuples. This decoder is a low level event based parser which operates in a fashion similar to the way SAX works except the elements of concern are the tag, length, and value entities. The decoder is a state machine which processes input as it is made available.

A Stack is used to track the state of the decoder between decode calls. It maintains the nesting of TLV tuples. Rather than creating new TLV tuple instances every time a single tuple is reused for primitive types and new tlv tuples are cloned for constructed types which are pushed onto the stack. The tuple fed to the callback must therefore be used very carefully - its values must be copied to prevent their loss if they are to be used later after the callback invokation has returned.

Note that all tuples are not created equal. Constructed TLVs nesting others will have null value members or empty buffers. Only TLV tuples of primitive types or the leaf TLV tuples of the TLV tuple tree will contain non null values. Therefore the nature of a TLV tuple should be investigated by callbacks before attempting to interpret their values. Also this decoder chunks value data returning it in parts rather than in one complete peice in the end. The value of the TLV Tuple returned is the part of the value that was read from the input fed into the decoder. These 'chunks' returned by callback makes it so there are no size limits to the value of a TLV. Again to reiterate chunking on values is only performed on primitive TLV Tuple types.

Version:
$Rev: 157644 $
Author:
Apache Directory Project

Field Summary
private  BERDecoderCallback cb
          this decoder's callback
private static BERDecoderCallback DEFAULT_CALLBACK
          the callback used by this decoder
private static org.apache.asn1.codec.stateful.DecoderMonitor DEFAULT_MONITOR
          the monitor used by this decoder
private static java.nio.ByteBuffer EMPTY_BUFFER
          empty byte buffer to be reused
private  LengthDecoder lengthDecoder
          a decoder used to decode length octets
private  org.apache.asn1.codec.stateful.DecoderMonitor monitor
          the monitor used by this decoder
private  BERDecoderState state
          the state of this decoder
private  TagDecoder tagDecoder
          a decoder used to decode tag octets
private  Tuple tlv
          the single TLV tuple used by this decoder
private  java.util.Stack tlvStack
          stack of nested/constructed TLV tuples
 
Constructor Summary
BERDecoder()
          Creates a stateful BER decoder which limits the tuple's value size.
 
Method Summary
 void decode(java.lang.Object encoded)
          Expects a ByteBuffer containing BER encoded data.
 void decodeOccurred(org.apache.asn1.codec.stateful.StatefulDecoder decoder, java.lang.Object decoded)
           
private  void decodeValue(java.nio.ByteBuffer buf)
          Extracts the value portion from the buffer for a primitive type.
private  void fireDecodeOccurred(Tuple tlv)
          Fires a complete TLV decoded event by making the appropriate calls to the callback and the monitor.
private  void fireLengthDecoded()
          Fires a length decoded event by making the appropriate calls to the callback and the monitor.
private  void fireTagDecoded()
          Fires a tag decoded event by making the appropriate calls to the callback and the monitor.
(package private)  Tuple getCurrentTuple()
          Gets a cloned copy of the current tuple.
(package private)  BERDecoderState getState()
          Gets the current state of this BERDecoder.
(package private)  java.util.Stack getTupleStack()
          Gets a deep copy of the constructed tuple stack.
 void setCallback(org.apache.asn1.codec.stateful.DecoderCallback cb)
           
 void setDecoderMonitor(org.apache.asn1.codec.stateful.DecoderMonitor monitor)
           
private  void updateStack(int increment)
          Increments the indices of constructed TLV's within the TLV Stack.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

EMPTY_BUFFER

private static final java.nio.ByteBuffer EMPTY_BUFFER
empty byte buffer to be reused


DEFAULT_CALLBACK

private static final BERDecoderCallback DEFAULT_CALLBACK
the callback used by this decoder


DEFAULT_MONITOR

private static final org.apache.asn1.codec.stateful.DecoderMonitor DEFAULT_MONITOR
the monitor used by this decoder


cb

private BERDecoderCallback cb
this decoder's callback


monitor

private org.apache.asn1.codec.stateful.DecoderMonitor monitor
the monitor used by this decoder


tlv

private final Tuple tlv
the single TLV tuple used by this decoder


tagDecoder

private final TagDecoder tagDecoder
a decoder used to decode tag octets


lengthDecoder

private final LengthDecoder lengthDecoder
a decoder used to decode length octets


tlvStack

private final java.util.Stack tlvStack
stack of nested/constructed TLV tuples


state

private BERDecoderState state
the state of this decoder

Constructor Detail

BERDecoder

public BERDecoder()
Creates a stateful BER decoder which limits the tuple's value size.

Method Detail

decode

public void decode(java.lang.Object encoded)
            throws org.apache.asn1.codec.DecoderException
Expects a ByteBuffer containing BER encoded data.

Specified by:
decode in interface org.apache.asn1.codec.stateful.StatefulDecoder
Throws:
java.lang.ClassCastException - if the encoded argument is not a ByteBuffer
java.lang.IllegalArgumentException - if the buffer is null or empty
org.apache.asn1.codec.DecoderException
See Also:
StatefulDecoder.decode( java.lang.Object)

setCallback

public void setCallback(org.apache.asn1.codec.stateful.DecoderCallback cb)
Specified by:
setCallback in interface org.apache.asn1.codec.stateful.StatefulDecoder

setDecoderMonitor

public void setDecoderMonitor(org.apache.asn1.codec.stateful.DecoderMonitor monitor)
Specified by:
setDecoderMonitor in interface org.apache.asn1.codec.stateful.StatefulDecoder

decodeValue

private void decodeValue(java.nio.ByteBuffer buf)
Extracts the value portion from the buffer for a primitive type.

Parameters:
buf - the byte byffer containing BER encoded data

decodeOccurred

public void decodeOccurred(org.apache.asn1.codec.stateful.StatefulDecoder decoder,
                           java.lang.Object decoded)
Specified by:
decodeOccurred in interface org.apache.asn1.codec.stateful.DecoderCallback

fireTagDecoded

private void fireTagDecoded()
Fires a tag decoded event by making the appropriate calls to the callback and the monitor. If the monitor is a BERDecoderMonitor with extended reporting, then those methods are invoked. Also as a side-effect this method clears the tag buffer once it has finished notifying the monitor and calling the callback.


fireLengthDecoded

private void fireLengthDecoded()
Fires a length decoded event by making the appropriate calls to the callback and the monitor. If the monitor is a BERDecoderMonitor with extended reporting, then those methods are invoked. Also as a side-effect this method clears the length buffer once it has finished notifying the monitor and calling the callback.


fireDecodeOccurred

private void fireDecodeOccurred(Tuple tlv)
Fires a complete TLV decoded event by making the appropriate calls to the callback and the monitor.


updateStack

private void updateStack(int increment)
Increments the indices of constructed TLV's within the TLV Stack.

Parameters:
increment - the amount to increment indices by.

getState

BERDecoderState getState()
Gets the current state of this BERDecoder. Used only for debugging and testing.

Returns:
the state enum

getCurrentTuple

Tuple getCurrentTuple()
Gets a cloned copy of the current tuple. Used only for debugging and testing.

Returns:
a clone of the current tlv

getTupleStack

java.util.Stack getTupleStack()
Gets a deep copy of the constructed tuple stack. Used only for debugging and testing.

Returns:
a deep copy of the tuple stack


Copyright © 2004-2009 . All Rights Reserved.